root/branches/streaming-rework/src/iavdevice.h

Revision 419, 7.1 kB (checked in by pieterpalmers, 16 years ago)

namespace simplification

Line 
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
Note: See TracBrowser for help on using the browser.