1 |
/* iavdevice.h |
---|
2 |
* Copyright (C) 2006 by Daniel Wagner |
---|
3 |
* |
---|
4 |
* This file is part of FreeBoB. |
---|
5 |
* |
---|
6 |
* FreeBoB is free software; you can redistribute it and/or modify |
---|
7 |
* it under the terms of the GNU General Public License as published by |
---|
8 |
* the Free Software Foundation; either version 2 of the License, or |
---|
9 |
* (at your option) any later version. |
---|
10 |
* FreeBoB is distributed in the hope that it will be useful, |
---|
11 |
* but WITHOUT ANY WARRANTY; without even the implied warranty of |
---|
12 |
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
---|
13 |
* GNU General Public License for more details. |
---|
14 |
* |
---|
15 |
* You should have received a copy of the GNU General Public License |
---|
16 |
* along with FreeBoB; if not, write to the Free Software |
---|
17 |
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, |
---|
18 |
* MA 02111-1307 USA. |
---|
19 |
*/ |
---|
20 |
|
---|
21 |
#ifndef IAVDEVICE_H |
---|
22 |
#define IAVDEVICE_H |
---|
23 |
|
---|
24 |
#include "libfreebobavc/avc_definitions.h" |
---|
25 |
#include "libfreebob/xmlparser.h" |
---|
26 |
#include "libutil/OptionContainer.h" |
---|
27 |
|
---|
28 |
class ConfigRom; |
---|
29 |
class Ieee1394Service; |
---|
30 |
|
---|
31 |
namespace Streaming { |
---|
32 |
class StreamProcessor; |
---|
33 |
} |
---|
34 |
/*! |
---|
35 |
@brief Interface that is to be implemented to support a device. |
---|
36 |
|
---|
37 |
This interface should be used to implement freebob support |
---|
38 |
for a specific device. |
---|
39 |
|
---|
40 |
*/ |
---|
41 |
class IAvDevice : public Util::OptionContainer { |
---|
42 |
public: |
---|
43 |
virtual ~IAvDevice() {} |
---|
44 |
|
---|
45 |
/// Returns the ConfigRom object of the device node. |
---|
46 |
virtual ConfigRom& getConfigRom() const = 0; |
---|
47 |
|
---|
48 |
/** |
---|
49 |
* @brief This is called by the DeviceManager to discover & configure the device |
---|
50 |
* |
---|
51 |
* @return true if the device was discovered successfuly |
---|
52 |
*/ |
---|
53 |
virtual bool discover() = 0; |
---|
54 |
|
---|
55 |
/** |
---|
56 |
* @brief Set the samping frequency |
---|
57 |
* @param samplingFrequency |
---|
58 |
* @return true if successful |
---|
59 |
*/ |
---|
60 |
virtual bool setSamplingFrequency( ESamplingFrequency samplingFrequency ) = 0; |
---|
61 |
/** |
---|
62 |
* @brief get the samplingfrequency as an integer |
---|
63 |
* @return the sampling frequency as integer |
---|
64 |
*/ |
---|
65 |
virtual int getSamplingFrequency( ) = 0; |
---|
66 |
|
---|
67 |
/** |
---|
68 |
* @brief This is called by the device manager to give the device a unique ID. |
---|
69 |
* |
---|
70 |
* The purpose of this is to allow for unique port naming |
---|
71 |
* in case there are multiple identical devices on the bus. |
---|
72 |
* Some audio API's (e.g. jack) don't work properly when the |
---|
73 |
* port names are not unique. |
---|
74 |
* |
---|
75 |
* Say you have two devices having a port named OutputLeft. |
---|
76 |
* This can cause the streaming |
---|
77 |
* part to present two OutputLeft ports to the audio API, |
---|
78 |
* which won't work. This ID will allow you to construct |
---|
79 |
* the port names as 'dev1_OutputLeft' and 'dev2_OutputLeft' |
---|
80 |
* |
---|
81 |
* @note Currently this is a simple integer that is equal to |
---|
82 |
* the position of the device in the devicemanager's |
---|
83 |
* device list. Therefore it is dependant on the order |
---|
84 |
* in which the devices are detected. The side-effect |
---|
85 |
* of this is that it is dependant on the bus topology |
---|
86 |
* and history (e.g. busresets etc). This makes that |
---|
87 |
* these ID's are not fixed to a specific physical device. |
---|
88 |
* At some point, we will replaced this with a GUID based |
---|
89 |
* approach, which is tied to a physiscal device and is |
---|
90 |
* bus & time independant. |
---|
91 |
* |
---|
92 |
* @param id |
---|
93 |
* @return true if successful |
---|
94 |
*/ |
---|
95 |
virtual bool setId(unsigned int id) = 0; |
---|
96 |
|
---|
97 |
/** |
---|
98 |
* @brief Constructs an XML description of the device [obsolete] |
---|
99 |
* |
---|
100 |
* this is a leftover from v1.0 and isn't used |
---|
101 |
* just provide an empty implementation that returns true |
---|
102 |
* untill it is removed |
---|
103 |
* |
---|
104 |
* @param deviceNode |
---|
105 |
* @return true if successful, false if not |
---|
106 |
*/ |
---|
107 |
virtual bool addXmlDescription( xmlNodePtr deviceNode ) = 0; |
---|
108 |
|
---|
109 |
/** |
---|
110 |
* @brief Outputs the device configuration to stderr/stdout [debug helper] |
---|
111 |
* |
---|
112 |
* This function prints out a (detailed) description of the |
---|
113 |
* device detected, and its configuration. |
---|
114 |
*/ |
---|
115 |
virtual void showDevice() const = 0; |
---|
116 |
|
---|
117 |
/** |
---|
118 |
* @brief Lock the device |
---|
119 |
* |
---|
120 |
* This is called by the streaming layer before we start manipulating |
---|
121 |
* and/or using the device. |
---|
122 |
* |
---|
123 |
* It should implement the mechanisms provided by the device to |
---|
124 |
* make sure that no other controller claims control of the device. |
---|
125 |
* |
---|
126 |
* @return true if successful, false if not |
---|
127 |
*/ |
---|
128 |
virtual bool lock() = 0; |
---|
129 |
|
---|
130 |
/** |
---|
131 |
* @brief Unlock the device |
---|
132 |
* |
---|
133 |
* This is called by the streaming layer after we finish manipulating |
---|
134 |
* and/or using the device. |
---|
135 |
* |
---|
136 |
* It should implement the mechanisms provided by the device to |
---|
137 |
* give up exclusive control of the device. |
---|
138 |
* |
---|
139 |
* @return true if successful, false if not |
---|
140 |
*/ |
---|
141 |
virtual bool unlock() = 0; |
---|
142 |
|
---|
143 |
/** |
---|
144 |
* @brief Prepare the device |
---|
145 |
* |
---|
146 |
* This is called by the streaming layer after the configuration |
---|
147 |
* parameters (e.g. sample rate) are set, and before |
---|
148 |
* getStreamProcessor[*] functions are called. |
---|
149 |
* |
---|
150 |
* It should be used to prepare the device's streamprocessors |
---|
151 |
* based upon the device's current configuration. Normally |
---|
152 |
* the streaming layer will not change the device's configuration |
---|
153 |
* after calling this function. |
---|
154 |
* |
---|
155 |
* @return true if successful, false if not |
---|
156 |
*/ |
---|
157 |
virtual bool prepare() = 0; |
---|
158 |
|
---|
159 |
/** |
---|
160 |
* @brief Returns the number of ISO streams implemented/used by this device |
---|
161 |
* |
---|
162 |
* Most likely this is 2 streams, i.e. one transmit stream and one |
---|
163 |
* receive stream. However there are devices that implement more, for |
---|
164 |
* example BeBoB's implement 4 streams: |
---|
165 |
* - 2 audio streams (1 xmit/1 recv) |
---|
166 |
* - 2 sync streams (1 xmit/1 recv), which are an optional sync source |
---|
167 |
* for the device. |
---|
168 |
* |
---|
169 |
* @note you have to have a StreamProcessor for every stream. I.e. |
---|
170 |
* getStreamProcessorByIndex(i) should return a valid StreamProcessor |
---|
171 |
* for i=0 to i=getStreamCount()-1 |
---|
172 |
* |
---|
173 |
* @return number of streams available (both transmit and receive) |
---|
174 |
*/ |
---|
175 |
virtual int getStreamCount() = 0; |
---|
176 |
|
---|
177 |
/** |
---|
178 |
* @brief Returns the StreamProcessor object for the stream with index i |
---|
179 |
* |
---|
180 |
* @note a streamprocessor returned by getStreamProcessorByIndex(i) |
---|
181 |
* cannot be the same object as one returned by |
---|
182 |
* getStreamProcessorByIndex(j) if i isn't equal to j |
---|
183 |
* @note you cannot have two streamprocessors handling the same ISO |
---|
184 |
* channel (on the same port) |
---|
185 |
* |
---|
186 |
* @param i : Stream index |
---|
187 |
* @pre @ref i smaller than getStreamCount() |
---|
188 |
* @return a StreamProcessor object if successful, NULL otherwise |
---|
189 |
*/ |
---|
190 |
virtual Streaming::StreamProcessor *getStreamProcessorByIndex(int i) = 0; |
---|
191 |
|
---|
192 |
/** |
---|
193 |
* @brief starts the stream with index i |
---|
194 |
* |
---|
195 |
* This function is called by the streaming layer when this stream should |
---|
196 |
* be started, i.e. the device should start sending data or should be prepared to |
---|
197 |
* be ready to receive data. |
---|
198 |
* |
---|
199 |
* It returns the channel number that was assigned for this stream. |
---|
200 |
* Channel allocation should be done using the allocation functions provided by the |
---|
201 |
* Ieee1394Service object that is passed in the constructor. |
---|
202 |
* |
---|
203 |
* @param i : Stream index |
---|
204 |
* @pre @ref i smaller than getStreamCount() |
---|
205 |
* @return true if successful, false if not |
---|
206 |
*/ |
---|
207 |
virtual bool startStreamByIndex(int i) = 0; |
---|
208 |
|
---|
209 |
/** |
---|
210 |
* @brief stops the stream with index @ref i |
---|
211 |
* |
---|
212 |
* @param i : Stream index |
---|
213 |
* @pre @ref i smaller than getStreamCount() |
---|
214 |
* @return true if successful, false if not |
---|
215 |
*/ |
---|
216 |
virtual bool stopStreamByIndex(int i) = 0; |
---|
217 |
|
---|
218 |
}; |
---|
219 |
|
---|
220 |
#endif |
---|