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

Revision 336, 6.4 kB (checked in by pieterpalmers, 17 years ago)

- Merged the developments on trunk since branch-off:

branch occurred at rev 194
svn merge -r 194:HEAD https://svn.sourceforge.net/svnroot/freebob/trunk/libfreebob

- Modified libfreebobavc to use the messagebuffer for debug info.
- This should compile and run

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
27 class ConfigRom;
28 class Ieee1394Service;
29
30 namespace FreebobStreaming {
31         class StreamProcessor;
32 }
33 /*!
34 \brief Interface that is to be implemented to support a device.
35
36  This interface should be used to implement freebob support for a specific device.
37
38 */
39 class IAvDevice {
40 public:
41         virtual ~IAvDevice() {}
42        
43         /// Returns the ConfigRom object of the device node.
44         virtual ConfigRom& getConfigRom() const = 0;
45        
46         /**
47          * This is called by the probe function to discover & configure the device
48          *
49          *
50          * @return true if the device was discovered successfully
51          */
52         virtual bool discover() = 0;
53        
54         /**
55          * Set the samping frequency
56          * @param samplingFrequency
57          * @return true if successfull
58          */
59         virtual bool setSamplingFrequency( ESamplingFrequency samplingFrequency ) = 0;
60         /**
61          * get the samplingfrequency as an integer
62          * @return the sampling frequency as integer
63          */
64         virtual int getSamplingFrequency( ) = 0;
65        
66     /**
67      * This is called by the device manager to give the device
68      * 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 successfull
94      */
95     virtual bool setId(unsigned int id) = 0;
96        
97         /**
98          * 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 successfull
106          */
107         virtual bool addXmlDescription( xmlNodePtr deviceNode ) = 0;
108        
109         /**
110          * 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          * Prepare the device
119          *  \todo when exactly is this called? and what should it do?
120          */
121         virtual bool prepare() = 0;
122        
123         ///
124         /**
125          * Returns the number of ISO streams implemented/used by this device
126          *
127          * Most likely this is 2 streams, i.e. one transmit stream and one
128          * receive stream. However there are devices that implement more, for
129          * example BeBoB's implement 4 streams:
130          * - 2 audio streams (1 xmit/1 recv)
131          * - 2 sync streams (1 xmit/1 recv), which are an optional sync source
132          *   for the device.
133          *
134          * \note you have to have a StreamProcessor for every stream. I.e.
135          *       getStreamProcessorByIndex(i) should return a valid StreamProcessor
136          *       for i=0 to i=getStreamCount()-1
137          * \note
138          *
139          * @return
140          */
141         virtual int getStreamCount() = 0;
142        
143         /**
144          * Returns the StreamProcessor object for the stream with index i
145          * \note a streamprocessor returned by getStreamProcessorByIndex(i)
146          *       cannot be the same object as one returned by
147          *       getStreamProcessorByIndex(j) if i isn't equal to j
148          * \note you could have two streamprocessors handling the same ISO
149          *       channel if that's needed
150          * \param i : Stream index
151          * \pre \ref i smaller than getStreamCount()
152          * @return a StreamProcessor object if successfull, NULL otherwise
153          */
154         virtual FreebobStreaming::StreamProcessor *getStreamProcessorByIndex(int i) = 0;
155        
156         /**
157          * starts the stream with index i
158          *
159          * This function is called by the streaming layer when this stream should
160          * be started, i.e. the device should start sending data or should be prepared to
161          * be ready to receive data.
162          *
163          * It returns the channel number that was assigned for this stream.
164          *
165          * For BeBoB's this implements the IEC61883 connection management procedure (CMP).
166          * This CMP is a way to negotiate the channel that should be used, the bandwidth
167          * consumed and to start the device's streaming mode.
168          *
169          * Note that this IEC61883 CMP is nescessary to allow multiple ISO devices on the bus,
170          * because otherwise there is no way to know what ISO channels are already in use.
171          * or is there?
172          * \note I wouldn't know how to assign channels for devices that don't implement
173          *       IEC61883 CMP (like the Motu?). As long as there is only one device on the
174          *       bus this is no problem and can be solved with static assignments.
175          *
176          * \param i : Stream index
177          * \pre \ref i smaller than getStreamCount()
178          * \return the ISO channel number assigned to this stream
179          */
180         virtual int startStreamByIndex(int i) = 0;
181        
182         /**
183          * stops the stream with index \ref i
184          *
185          * \param i : Stream index
186          * \pre \ref i smaller than getStreamCount()
187          * \return 0 on success, -1 else
188          */
189         virtual int stopStreamByIndex(int i) = 0;
190
191 };
192
193 #endif
Note: See TracBrowser for help on using the browser.