1 mmfdatasource.h |
1 // Copyright (c) 2001-2009 Nokia Corporation and/or its subsidiary(-ies). |
|
2 // All rights reserved. |
|
3 // This component and the accompanying materials are made available |
|
4 // under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members |
|
5 // which accompanies this distribution, and is available |
|
6 // at the URL "http://www.symbianfoundation.org/legal/licencesv10.html". |
|
7 // |
|
8 // Initial Contributors: |
|
9 // Nokia Corporation - initial contribution. |
|
10 // |
|
11 // Contributors: |
|
12 // |
|
13 // Description: |
|
14 // include\mmf\Server\mmfdatasource.h |
|
15 // |
|
16 // |
|
17 |
|
18 #ifndef __MMF_SERVER_DATASOURCE_H__ |
|
19 #define __MMF_SERVER_DATASOURCE_H__ |
|
20 |
|
21 #include <e32base.h> |
|
22 #include <mmf/server/mmfdatasourcesink.hrh> |
|
23 #include <mmf/common/mmfutilities.h> |
|
24 #include <ecom/ecom.h> |
|
25 #include <mmf/common/mmfbase.h> |
|
26 #include <mmf/common/mmfcontrollerframework.h> |
|
27 |
|
28 // |
|
29 // MDataSource mixim |
|
30 // |
|
31 |
|
32 class CMMFBuffer; |
|
33 class MDataSink; |
|
34 class MAsyncEventHandler; |
|
35 |
|
36 /** |
|
37 @publishedAll |
|
38 @released |
|
39 |
|
40 Abstract class representing a data source. |
|
41 */ |
|
42 class MDataSource |
|
43 { |
|
44 public: |
|
45 static inline MDataSource* NewSourceL( TUid aImplementationUid, const TDesC8& aInitData ) ; |
|
46 |
|
47 /** |
|
48 Destructor. |
|
49 */ |
|
50 virtual ~MDataSource() {REComSession::DestroyedImplementation(iDtor_ID_Key);}; |
|
51 |
|
52 /** |
|
53 Returns the UID identifying the type of data source. |
|
54 |
|
55 @return The UID identifying the type of data source. |
|
56 */ |
|
57 virtual TUid DataSourceType() const {return iDataSourceType;}; |
|
58 |
|
59 /** |
|
60 Returns the data type as a fourCC code of the data source. |
|
61 |
|
62 This is a pure virtual function that each derrived class must implement. |
|
63 |
|
64 @param aMediaId |
|
65 This identifies the type of media eg. audio or video and the stream ID. |
|
66 This parameter is required in cases where the source can supply data |
|
67 of more than one media type and/or multiple streams of data. |
|
68 |
|
69 @return The fourCC code identifying the source datatype for the specified aMediaId. |
|
70 */ |
|
71 virtual TFourCC SourceDataTypeCode(TMediaId aMediaId) = 0; |
|
72 |
|
73 inline virtual TInt SetSourceDataTypeCode(TFourCC aSourceFourCC, TMediaId aMediaId); |
|
74 |
|
75 /** |
|
76 Function called by a MDataSink to request the data source to fill aBuffer with data. |
|
77 |
|
78 This is a pure virtual function that each derived class must implement. |
|
79 This method is used when a data source is passively waiting for requests from a consumer ie. a data sink |
|
80 to fill a buffer. The data source must call the BufferFilledL member on aConsumer when it has filled |
|
81 the buffer with data. The data source can either make this callback synchronously or asynchronously. |
|
82 |
|
83 The format should read the frame number of the buffer via the buffer's CMMFBuffer::FrameNumber() |
|
84 function. From this, the format should be able to determine the actual position of the data on |
|
85 the data source. The technique here depends on the nature of the format. For a linear audio |
|
86 format, the position can be obtained by a simple calculation of the frame size, the header size |
|
87 and where appropriate the datatype. |
|
88 |
|
89 For non-linear formats, either an index table of frame number and location will need to be |
|
90 created in the NewL() or some form of approximating algorithm will be required. Some formats |
|
91 have an index table as part of the format eg. AVI. If no random access is required then no index |
|
92 table is required, the format can keep track of the current read position and increment it on |
|
93 each access, and reset it if the frame number is reset to 0 or 1. Given that for non-linear |
|
94 ie. variable bit rate formats, the size of the data read may vary from frame to frame, then the |
|
95 format should either set the request size of the buffer for the required frame or call the |
|
96 source's ReadBufferL() (either CMMFClip::ReadBufferL(), CMMFDescriptor ::ReadBufferL() or |
|
97 CMMFFile::ReadBufferL()) function that takes the aLength parameter. |
|
98 |
|
99 It is the responsibility of the format decode to determine the size and position of the source |
|
100 data for each frame. For linear audio formats, the format decode should fill the buffer up to |
|
101 its maximum length. For multimedia formats e.g. mp4, AVI etc, the format decode is effectively |
|
102 acting as a demultiplexor, and must obtain the appropriate data from the source depending on |
|
103 the aMediaId. |
|
104 |
|
105 @param aBuffer |
|
106 The buffer that needs filling with data. |
|
107 @param aConsumer |
|
108 The data sink that consumes the data. The data source needs this to make the BufferFilledL |
|
109 callback on aConsumer when the data source has completed filling the aBuffer. |
|
110 @param aMediaId |
|
111 This identifies the type of media eg. audio or video and the stream ID. |
|
112 This parameter is required in cases where the source can supply data |
|
113 of more than one media type and/or multiple strams of data eg. a multimedia file. |
|
114 */ |
|
115 virtual void FillBufferL(CMMFBuffer* aBuffer, MDataSink* aConsumer,TMediaId aMediaId)=0; |
|
116 |
|
117 /** |
|
118 Function called by a data sink to pass back an emptied buffer to the source. |
|
119 |
|
120 This is a pure virtual function that each derived class must implement. |
|
121 This method is used as the callback when the data source actively requests a consumer ie. a data |
|
122 sink to empty a buffer by calling the data sinks EmptyBufferL. |
|
123 When the data source gets this callback it knows that the buffer has been emptied and can be |
|
124 reused. |
|
125 |
|
126 @param aBuffer |
|
127 The buffer that has been emptied by a data sink and is now available for reuse. |
|
128 */ |
|
129 virtual void BufferEmptiedL(CMMFBuffer* aBuffer)=0; |
|
130 |
|
131 /** |
|
132 @deprecated |
|
133 |
|
134 Function to indicate whether the data source can create a buffer. |
|
135 |
|
136 This is a pure virtual function that each derived class must implement. |
|
137 |
|
138 @return A boolean indicating if the data source can create a buffer. ETrue if it can otherwise |
|
139 EFalse. |
|
140 */ |
|
141 virtual TBool CanCreateSourceBuffer()=0; |
|
142 |
|
143 /** |
|
144 @deprecated |
|
145 |
|
146 Returns a buffer created by the data source |
|
147 |
|
148 This is a pure virtual function that each derived class must implement. |
|
149 |
|
150 @param aMediaId |
|
151 This identifies the type of media eg. audio or video and the stream ID. |
|
152 This parameter is required in cases where the source can supply data |
|
153 of more than one media type and/or multiple strams of data eg a multimedia file. |
|
154 @param aReference |
|
155 This must be written to by the method to indicate whether the created buffer is |
|
156 a 'reference' buffer. A 'reference' buffer is a buffer that is owned by the source |
|
157 and should be used in preference to the sink buffer provided the sink buffer |
|
158 is also not a reference buffer. |
|
159 |
|
160 @return A pointer to the created buffer. |
|
161 */ |
|
162 virtual CMMFBuffer* CreateSourceBufferL(TMediaId aMediaId, TBool &aReference) = 0; |
|
163 |
|
164 inline virtual CMMFBuffer* CreateSourceBufferL(TMediaId aMediaId, CMMFBuffer& aSinkBuffer, TBool &aReference); |
|
165 |
|
166 inline virtual TInt SourceThreadLogon(MAsyncEventHandler& aEventHandler); |
|
167 |
|
168 /** |
|
169 Function to 'logoff' the data source from the same thread that source supplies data in. |
|
170 |
|
171 This method may be required as the thread that the data source is deleted in may not be |
|
172 the same thread that the data transfer took place in. Therefore any thread specific |
|
173 releasing of resources needs to be performed in the SourceThreadLogoff rather than in the |
|
174 destructor. |
|
175 |
|
176 This is a virtual function that a derrived data source can implement if any thread specific |
|
177 releasing of resources is required. |
|
178 */ |
|
179 virtual void SourceThreadLogoff() {}; |
|
180 |
|
181 inline virtual void NegotiateSourceL(MDataSink& aDataSink); //called if source setup depends on sink |
|
182 |
|
183 /** |
|
184 Indicates whether the data source supports sample rate conversion. |
|
185 |
|
186 This is a virtual function that a derived class can implement. |
|
187 |
|
188 @return A boolean indicating if the data source can perform a sample rate conversion. ETrue if |
|
189 it can otherwise EFalse. |
|
190 */ |
|
191 virtual TBool SourceSampleConvert() {return EFalse;}; |
|
192 |
|
193 /** |
|
194 Function to 'prime' the data source. |
|
195 |
|
196 This is a virtual function that a derrived data source can implement if |
|
197 any data source specific 'priming' is required. |
|
198 */ |
|
199 virtual void SourcePrimeL() {}; |
|
200 |
|
201 /** |
|
202 Function to 'play' the data source. |
|
203 |
|
204 This is a virtual function that a derrived data source can implement if |
|
205 any data source specific action is required prior to 'playing' ie. the start of data transfer. |
|
206 */ |
|
207 virtual void SourcePlayL() {}; |
|
208 |
|
209 /** |
|
210 Function to 'pause' the data source. |
|
211 |
|
212 This is a virtual function that a derrived data source can implement if |
|
213 any data source specific action is required to 'pause' |
|
214 */ |
|
215 virtual void SourcePauseL() {}; |
|
216 |
|
217 /** |
|
218 Function to 'stop' the data source. |
|
219 |
|
220 This is a virtual function that a derrived data source can implement if |
|
221 any data source specific action is required to 'stop'. |
|
222 */ |
|
223 virtual void SourceStopL() {}; |
|
224 |
|
225 inline virtual void SetSourcePrioritySettings(const TMMFPrioritySettings& aPrioritySettings); |
|
226 |
|
227 /** |
|
228 Function to call a source specific custom command. |
|
229 |
|
230 This is a virtual function that a derrived data source can implement if |
|
231 it implements any custom commands. |
|
232 |
|
233 @param aMessage |
|
234 The message specifying the custom command. |
|
235 */ |
|
236 virtual void SourceCustomCommand(TMMFMessage& aMessage) {aMessage.Complete(KErrNotSupported);}; |
|
237 protected: |
|
238 |
|
239 /** |
|
240 Performs any source construction dependant on the source construction |
|
241 initialisation data aInitData. |
|
242 |
|
243 This is a pure virtual function that a derrived data source must implement |
|
244 |
|
245 @param aInitData |
|
246 The source specific initialisation data required for source construction. |
|
247 */ |
|
248 virtual void ConstructSourceL( const TDesC8& aInitData ) = 0 ; |
|
249 |
|
250 /** |
|
251 Protected constructor. |
|
252 */ |
|
253 MDataSource(TUid aType): iDataSourceType(aType) {} |
|
254 private: |
|
255 TUid iDataSourceType; |
|
256 TUid iDtor_ID_Key; |
|
257 |
|
258 }; |
|
259 |
|
260 /** |
|
261 Instantiates a data source. |
|
262 |
|
263 @param aImplementationUid |
|
264 The UID identifying the data source to be instantiated. |
|
265 @param aInitData |
|
266 The source specific initialisation data required for source construction. |
|
267 |
|
268 @return The instantiated data source. |
|
269 */ |
|
270 inline MDataSource* MDataSource::NewSourceL( TUid aImplementationUid, const TDesC8& aInitData ) |
|
271 { |
|
272 MDataSource* retPtr = REINTERPRET_CAST( MDataSource*, REComSession::CreateImplementationL( aImplementationUid, |
|
273 _FOFF(MDataSource, iDtor_ID_Key) ) ) ; |
|
274 CleanupDeletePushL(retPtr); |
|
275 retPtr->ConstructSourceL( aInitData ) ; |
|
276 |
|
277 CleanupStack::Pop(retPtr); |
|
278 return retPtr ; |
|
279 } |
|
280 |
|
281 /** |
|
282 Sets the data type as a fourCC code for the data source. |
|
283 |
|
284 This is a virtual function that each derived class can implement if the data source supports |
|
285 the ability to have its data type set. |
|
286 |
|
287 @param aSourceFourCC |
|
288 This specifies the data type as a fourCC code to set the source to. |
|
289 @param aMediaId |
|
290 This identifies the type of media eg. audio or video and the stream ID. |
|
291 This parameter is required in cases where the source can supply data |
|
292 of more than one media type and/or multiple strams of data eg a multimedia file. |
|
293 |
|
294 @return KErrNone if successful, KErrNotSupported if the source does not support having |
|
295 it's data type set, otherwise a system wide error code. |
|
296 */ |
|
297 inline TInt MDataSource::SetSourceDataTypeCode(TFourCC /*aSourceFourCC*/, TMediaId /*aMediaId*/) |
|
298 { |
|
299 return KErrNotSupported; |
|
300 } |
|
301 |
|
302 /** |
|
303 @deprecated |
|
304 |
|
305 Returns a buffer created by the data source. |
|
306 |
|
307 This is a virtual function that a derived class can implement. |
|
308 This can be used in preference to the above CreateSourceBufferL method in cases where |
|
309 the source buffer creation has a dependancy on the sink buffer. |
|
310 |
|
311 @param aMediaId |
|
312 This identifies the type of media eg. audio or video and the stream ID. |
|
313 This parameter is required in cases where the source can supply data |
|
314 of more than one media type and/or multiple strams of data eg a multimedia file |
|
315 @param aSinkBuffer |
|
316 The sink buffer the nature of which may influence the creation of the source buffer. |
|
317 @param aReference |
|
318 This must be written to by the method to indicate whether the created buffer is |
|
319 a 'reference' buffer. A 'reference' buffer is a buffer that is owned by the source |
|
320 and should be used in preference to the sink buffer provided the sink buffer is not a |
|
321 reference buffer. |
|
322 |
|
323 @return A pointer to the created buffer. |
|
324 */ |
|
325 inline CMMFBuffer* MDataSource::CreateSourceBufferL(TMediaId aMediaId, CMMFBuffer& /*aSinkBuffer*/, TBool &aReference) |
|
326 { |
|
327 return CreateSourceBufferL(aMediaId, aReference); |
|
328 } |
|
329 |
|
330 /** |
|
331 Function to 'logon' the data source to the same thread that source will be supplying data in. |
|
332 |
|
333 This method may be required as the thread that the data source was created in is not always |
|
334 the same thread that the data transfer will take place in. Therefore any thread specific |
|
335 initialisation needs to be performed in the SourceThreadLogon rather than in the creation |
|
336 of the data source. |
|
337 |
|
338 This is a virtual function that a derrived data source can implement if any thread specific |
|
339 initialisation is required and/or the data source can create any asynchronous events. |
|
340 |
|
341 @param aEventHandler |
|
342 This is an MAsyncEventHandler to handle asynchronous events that occur during the |
|
343 transfer of multimedia data. The event handler must be in the same thread as the data transfer |
|
344 thread. Hence the reason it is passed in the SourceThreadLogon as opposed to say the constructor. |
|
345 |
|
346 @return An error code indicating if the function call was successful. KErrNone on success, otherwise |
|
347 another of the system-wide error codes. |
|
348 */ |
|
349 inline TInt MDataSource::SourceThreadLogon(MAsyncEventHandler& /*aEventHandler*/) |
|
350 { |
|
351 return KErrNone; |
|
352 } |
|
353 |
|
354 /** |
|
355 Function to allow the data source to negotiate with a data sink |
|
356 |
|
357 This method is required in cases where the settings of data source are dependant on those of a |
|
358 data sink. This is a virtual function that a derrived data source can implement. |
|
359 |
|
360 @param aDataSink |
|
361 The data sink whose settings can affect the data source. |
|
362 */ |
|
363 inline void MDataSource::NegotiateSourceL(MDataSink& /*aDataSink*/) |
|
364 { |
|
365 } |
|
366 |
|
367 /** |
|
368 Function to set the source priority settings. |
|
369 |
|
370 This is a virtual function that a derrived data source can implement if |
|
371 a priority mechanism is required to arbitrate between multiple clients |
|
372 trying to access the same resource. |
|
373 |
|
374 @param aPrioritySettings |
|
375 The source priority settings. |
|
376 |
|
377 @capability MultimediaDD |
|
378 A process requesting or using this method that has MultimediaDD capability will |
|
379 always have precedence over a process that does not have MultimediaDD. |
|
380 */ |
|
381 inline void MDataSource::SetSourcePrioritySettings(const TMMFPrioritySettings& /*aPrioritySettings*/) |
|
382 { |
|
383 } |
|
384 |
|
385 /** |
|
386 This function is used by TCleanupItem objects to perform |
|
387 a SourceStopL() when leaving functions exist, ususally between SourcePrimeL-SourceStopL pairs. |
|
388 |
|
389 @param aSource |
|
390 The data source to be stopped. |
|
391 */ |
|
392 inline static void DoDataSourceStop(TAny* aSource) |
|
393 { |
|
394 MDataSource* source = STATIC_CAST(MDataSource*, aSource); |
|
395 // we don't want this function to leave because no leaving functions are supposed |
|
396 // to be used as argument to the TCleanupItem objects. Hence we catch the error but |
|
397 // we do nothing with it. |
|
398 TRAP_IGNORE(source->SourceStopL()); |
|
399 } |
|
400 |
|
401 /** |
|
402 This method is used by TCleanupItem objects to perform a SourceThreadLogoff(). |
|
403 |
|
404 @param aSource |
|
405 The data source to be logged off. |
|
406 */ |
|
407 inline static void DoDataSourceThreadLogoff(TAny* aSource) |
|
408 { |
|
409 MDataSource* source = STATIC_CAST(MDataSource*, aSource); |
|
410 source->SourceThreadLogoff(); |
|
411 } |
|
412 |
|
413 #endif |