|
sl@0
|
1 |
/*
|
|
sl@0
|
2 |
* Copyright (c) 2007-2009 Nokia Corporation and/or its subsidiary(-ies).
|
|
sl@0
|
3 |
* All rights reserved.
|
|
sl@0
|
4 |
* This component and the accompanying materials are made available
|
|
sl@0
|
5 |
* under the terms of "Eclipse Public License v1.0"
|
|
sl@0
|
6 |
* which accompanies this distribution, and is available
|
|
sl@0
|
7 |
* at the URL "http://www.eclipse.org/legal/epl-v10.html".
|
|
sl@0
|
8 |
*
|
|
sl@0
|
9 |
* Initial Contributors:
|
|
sl@0
|
10 |
* Nokia Corporation - initial contribution.
|
|
sl@0
|
11 |
*
|
|
sl@0
|
12 |
* Contributors:
|
|
sl@0
|
13 |
*
|
|
sl@0
|
14 |
* Description:
|
|
sl@0
|
15 |
*
|
|
sl@0
|
16 |
*/
|
|
sl@0
|
17 |
|
|
sl@0
|
18 |
|
|
sl@0
|
19 |
|
|
sl@0
|
20 |
|
|
sl@0
|
21 |
/**
|
|
sl@0
|
22 |
@file
|
|
sl@0
|
23 |
@publishedPartner
|
|
sl@0
|
24 |
@released
|
|
sl@0
|
25 |
*/
|
|
sl@0
|
26 |
|
|
sl@0
|
27 |
#ifndef MAUDIOSTREAM_H
|
|
sl@0
|
28 |
#define MAUDIOSTREAM_H
|
|
sl@0
|
29 |
|
|
sl@0
|
30 |
#include <e32base.h>
|
|
sl@0
|
31 |
#include <f32file.h>
|
|
sl@0
|
32 |
#include <mmf/common/mmfcontroller.h>
|
|
sl@0
|
33 |
#include <a3f/a3fbase.h>
|
|
sl@0
|
34 |
|
|
sl@0
|
35 |
class MAudioStreamObserver;
|
|
sl@0
|
36 |
class MAudioCodecObserver;
|
|
sl@0
|
37 |
class MAudioCodec;
|
|
sl@0
|
38 |
class MAudioProcessingUnit;
|
|
sl@0
|
39 |
|
|
sl@0
|
40 |
/**
|
|
sl@0
|
41 |
* this is the main control interface for the state of a processing unit chain.
|
|
sl@0
|
42 |
*
|
|
sl@0
|
43 |
* An AudioStream object binds together audio components processing the same data.
|
|
sl@0
|
44 |
* An AudioStrem executes the audio processing states as requested by the client. The processing units
|
|
sl@0
|
45 |
* attached to a stream will follow the state of the stream.
|
|
sl@0
|
46 |
*
|
|
sl@0
|
47 |
* The possible states of an AudioStream object are:
|
|
sl@0
|
48 |
* EUninitialized: The state which the chain is in initially.
|
|
sl@0
|
49 |
* The logical chain can be constructed.
|
|
sl@0
|
50 |
* The settings in the logical chain cannot be related to the adaptation because no adaptation has been selected yet.
|
|
sl@0
|
51 |
*
|
|
sl@0
|
52 |
* EInitialized: this state is set after a successful initialization request.
|
|
sl@0
|
53 |
* EIdle: All the chain resources are allocated, however, no processing time
|
|
sl@0
|
54 |
* (other than expended to put the chain into EIdle state) is consumed in this phase.
|
|
sl@0
|
55 |
* EPrimed: As per EIdle, but the stream can consume processing time, by filling its buffers.
|
|
sl@0
|
56 |
* EActive: The chain has all the resources as per EIdle and EPrimed but also has started to
|
|
sl@0
|
57 |
* process the actions requested by the client.
|
|
sl@0
|
58 |
* EDead: The stream can no longer function due to fatal error.
|
|
sl@0
|
59 |
* The logical chain still exists, but any physical resources should be reclaimed by the adaptation.
|
|
sl@0
|
60 |
*
|
|
sl@0
|
61 |
* The MAudioStreamObserver includes completion callbacks for many of the methods of MAudioStream.
|
|
sl@0
|
62 |
* The protocol is such that when an asynchronous method is called and KErrNone is returned,
|
|
sl@0
|
63 |
* then the call will be followed by a corresponding callback. if the returned error code from
|
|
sl@0
|
64 |
* the asynchronous function is other than KErrNone, then a callback will not be made as
|
|
sl@0
|
65 |
* a result of that method call. The callbacks will always occur out-of-context.
|
|
sl@0
|
66 |
* Note that many of the functions will also require a context commit for the actual processing to take place.
|
|
sl@0
|
67 |
*/
|
|
sl@0
|
68 |
class MAudioStream
|
|
sl@0
|
69 |
{
|
|
sl@0
|
70 |
public:
|
|
sl@0
|
71 |
/**
|
|
sl@0
|
72 |
* Registers an audio stream observer.
|
|
sl@0
|
73 |
*
|
|
sl@0
|
74 |
* Note that this function is meant for clients of the Audio Stream.
|
|
sl@0
|
75 |
* The client should unregister using UnregisterAudioStreamObserver() when applicable.
|
|
sl@0
|
76 |
*
|
|
sl@0
|
77 |
* @param aObserver reference to the observer to register.
|
|
sl@0
|
78 |
* @return an error code. KErrNone if successful.
|
|
sl@0
|
79 |
* KErrAlreadyExists if the client is already registered.
|
|
sl@0
|
80 |
* KErrOutOfMemory in case of memory exhaustion.
|
|
sl@0
|
81 |
*/
|
|
sl@0
|
82 |
virtual TInt RegisterAudioStreamObserver(MAudioStreamObserver& aObserver)=0;
|
|
sl@0
|
83 |
|
|
sl@0
|
84 |
/**
|
|
sl@0
|
85 |
* Unregisters an audio stream observer.
|
|
sl@0
|
86 |
*
|
|
sl@0
|
87 |
* @param aObserver reference to the observer to unregister.
|
|
sl@0
|
88 |
* @return an error code. KErrNone if successful. KErrNotFound if the client has not been registered as observer.
|
|
sl@0
|
89 |
*/
|
|
sl@0
|
90 |
virtual void UnregisterAudioStreamObserver(MAudioStreamObserver& aObserver)=0;
|
|
sl@0
|
91 |
|
|
sl@0
|
92 |
|
|
sl@0
|
93 |
/**
|
|
sl@0
|
94 |
* Sets the type of audio being processed in this context.
|
|
sl@0
|
95 |
*
|
|
sl@0
|
96 |
* The audio type settings are used by the resource control subsystem when it arbitrates between multiple clients
|
|
sl@0
|
97 |
* trying to access the same resource. Additionally it may impact the availability of certain audio features for the client.
|
|
sl@0
|
98 |
* It may also have an effect on other aspects, including, but not limited to routing and automatically applied effects.
|
|
sl@0
|
99 |
* The audio types available for the client may be limited by the platform security capabilities, vendorId etc of the client application.
|
|
sl@0
|
100 |
*
|
|
sl@0
|
101 |
* @param aAudioTypeSettings defines the settings associated with this stream.
|
|
sl@0
|
102 |
* @return an error code. KErrNone if successful, otherwise one of the system wide error codes.
|
|
sl@0
|
103 |
*/
|
|
sl@0
|
104 |
virtual TInt SetAudioType(const TAudioTypeSettings& aAudioTypeSettings)=0;
|
|
sl@0
|
105 |
|
|
sl@0
|
106 |
/**
|
|
sl@0
|
107 |
* Fetch the type of audio being processed in this stream.
|
|
sl@0
|
108 |
*
|
|
sl@0
|
109 |
* @param aAudioTypeSettings On return contains the audio type of this stream.
|
|
sl@0
|
110 |
*/
|
|
sl@0
|
111 |
virtual void GetAudioType(TAudioTypeSettings& aAudioTypeSettings) const = 0;
|
|
sl@0
|
112 |
|
|
sl@0
|
113 |
/**
|
|
sl@0
|
114 |
* Requests a transition to the EInitialized state.
|
|
sl@0
|
115 |
*
|
|
sl@0
|
116 |
* this function is asynchronous, and its successful return merely issues a request which is acted upon on Commit(),
|
|
sl@0
|
117 |
* and while will lead to a StateEvent() callback. this function is only allowed while the stream is in EUninitialized state.
|
|
sl@0
|
118 |
* A call in any other state will cause an error code of KErrNotReady to be returned.
|
|
sl@0
|
119 |
*
|
|
sl@0
|
120 |
* @return an error code. if KErrNone, the state transition has been requested,
|
|
sl@0
|
121 |
* and there will be a StateEvent() callback following Commit().
|
|
sl@0
|
122 |
* On error, there is no request made: KErrNotReady states the stream if not in valid current state,
|
|
sl@0
|
123 |
* otherwise one of the system-wide error codes.
|
|
sl@0
|
124 |
*/
|
|
sl@0
|
125 |
virtual TInt Initialize()=0;
|
|
sl@0
|
126 |
|
|
sl@0
|
127 |
/**
|
|
sl@0
|
128 |
* Requests a transition to the EIdle state.
|
|
sl@0
|
129 |
*
|
|
sl@0
|
130 |
* this function is asynchronous, and its successful return merely issues a request which is acted upon on Commit(),
|
|
sl@0
|
131 |
* and while will lead to a StateEvent() callback. this function is only allowed while the stream is in EInitialized state.
|
|
sl@0
|
132 |
* A call in any other state will cause an error code of KErrNotReady to be returned
|
|
sl@0
|
133 |
*
|
|
sl@0
|
134 |
* The resources must be released using Unload() when they are no longer needed.
|
|
sl@0
|
135 |
* Note that it is recommended that the resources are not kept reserved for long periods of inactivity,
|
|
sl@0
|
136 |
* since it may prevent other audio streams from becoming active by stealing resources they need to use
|
|
sl@0
|
137 |
*
|
|
sl@0
|
138 |
* @return An error code. if KErrNone, the state transition has been requested,
|
|
sl@0
|
139 |
* and there will be a StateEvent() callback following Commit().
|
|
sl@0
|
140 |
* On error, there is no request made: KErrNotReady states the stream if not in valid current state,
|
|
sl@0
|
141 |
* otherwise one of the system-wide error codes.
|
|
sl@0
|
142 |
*/
|
|
sl@0
|
143 |
virtual TInt Load()=0;
|
|
sl@0
|
144 |
|
|
sl@0
|
145 |
/**
|
|
sl@0
|
146 |
* Starts the audio processing. this function is only allowed while the stream is in EIdle or EPrimed states.
|
|
sl@0
|
147 |
*
|
|
sl@0
|
148 |
* The start-up procedures include requesting permission for audio processing from audio policy.
|
|
sl@0
|
149 |
*
|
|
sl@0
|
150 |
* @return an error code. A call in any state different to EIdle or EPrimed will cause an error code of KErrNotReady.
|
|
sl@0
|
151 |
* if permission to start is denied by audio policy, a state change back to EPrimed will occur with error code KErrAccessDenied
|
|
sl@0
|
152 |
*/
|
|
sl@0
|
153 |
virtual TInt Activate()=0;
|
|
sl@0
|
154 |
|
|
sl@0
|
155 |
/**
|
|
sl@0
|
156 |
* Requests a transition to the Idle state – stopping the ongoing operation.
|
|
sl@0
|
157 |
*
|
|
sl@0
|
158 |
* this function is asynchronous, and its successful return merely issues a request which is acted upon on Commit(),
|
|
sl@0
|
159 |
* and while will lead to a StateEvent() callback this function is only allowed while the stream is either Active or Primed.
|
|
sl@0
|
160 |
* A call in any other state will cause an error code of KErrNotReady to be returned.
|
|
sl@0
|
161 |
* @return An error code. if KErrNone, the state transition has been requested, and there will be a StateEvent() callback
|
|
sl@0
|
162 |
* following Commit(). On error, there is no request made: KErrNotReady states the stream if not in valid current state,
|
|
sl@0
|
163 |
* otherwise one of the system-wide error codes
|
|
sl@0
|
164 |
*/
|
|
sl@0
|
165 |
virtual TInt Stop()=0;
|
|
sl@0
|
166 |
|
|
sl@0
|
167 |
/**
|
|
sl@0
|
168 |
* Prepares the audio stream for releasing the resources reserved for it and for the processing units attached to the stream.
|
|
sl@0
|
169 |
*
|
|
sl@0
|
170 |
* this function is only allowed while the stream is EIdle state.
|
|
sl@0
|
171 |
* A call in any other state will cause an error code of KErrNotReady to be returned.
|
|
sl@0
|
172 |
*
|
|
sl@0
|
173 |
* During this call the stream will query all attached processing units whether they are ready to unload.
|
|
sl@0
|
174 |
* if a processing unit indicates that it is not ready to uninitialize, then an error code other than KErrNone will be returned.
|
|
sl@0
|
175 |
* Provided that this call succeeds, the actual unloading process will begins once Commit() is called for the context of this stream.
|
|
sl@0
|
176 |
*
|
|
sl@0
|
177 |
* @return An error code. KErrNone if successful.
|
|
sl@0
|
178 |
* KErrNotReady if called while the stream is not in correct state.
|
|
sl@0
|
179 |
* Other system wide error codes are also possible.
|
|
sl@0
|
180 |
*/
|
|
sl@0
|
181 |
virtual TInt Unload()=0;
|
|
sl@0
|
182 |
|
|
sl@0
|
183 |
/**
|
|
sl@0
|
184 |
* Requests a transition to the Unitialized state – returning the stream to its initial state.
|
|
sl@0
|
185 |
*
|
|
sl@0
|
186 |
* this function is asynchronous, and its successful return merely issues a request which is acted upon on Commit(),
|
|
sl@0
|
187 |
* and while will lead to a StateEvent() callback. this function is only allowed while the stream is in Initialized state.
|
|
sl@0
|
188 |
* A call in any other state will cause an error code of KErrNotReady to be returned.
|
|
sl@0
|
189 |
*
|
|
sl@0
|
190 |
* @return an error code. if KErrNone, the state transition has been requested, and there will be a StateEvent() callback
|
|
sl@0
|
191 |
* following Commit(). On error, there is no request made: KErrNotReady states the stream if not in valid current state,
|
|
sl@0
|
192 |
* otherwise one of the system-wide error codes.
|
|
sl@0
|
193 |
*/
|
|
sl@0
|
194 |
virtual TInt Uninitialize()=0;
|
|
sl@0
|
195 |
|
|
sl@0
|
196 |
/**
|
|
sl@0
|
197 |
* Requests a transition to the EPrime state.
|
|
sl@0
|
198 |
*
|
|
sl@0
|
199 |
* this function is asynchronous, and its successful return merely issues a request which is acted upon on Commit(),
|
|
sl@0
|
200 |
* and while will lead to a StateEvent() callback. this function is only allowed while the stream is in EActive
|
|
sl@0
|
201 |
* (semantics of Prime in EActive– go into a buffering pause) or EIdle state (semantics of Prime in EIdle – start to buffer).
|
|
sl@0
|
202 |
* A call in any other state will cause an error code of KErrNotReady to be returned. Not all streams support Prime.
|
|
sl@0
|
203 |
*
|
|
sl@0
|
204 |
* @return an error code. if KErrNone, the state transition has been requested, and there will be a StateEvent() callback
|
|
sl@0
|
205 |
* following Commit(). On error, there is no request made: KErrNotReady states the stream if not in valid current state,
|
|
sl@0
|
206 |
* otherwise one of the system-wide error codes
|
|
sl@0
|
207 |
*/
|
|
sl@0
|
208 |
virtual TInt Prime()=0;
|
|
sl@0
|
209 |
|
|
sl@0
|
210 |
|
|
sl@0
|
211 |
/**
|
|
sl@0
|
212 |
* Empty any buffers that have been filled.
|
|
sl@0
|
213 |
*
|
|
sl@0
|
214 |
* Reclain any outstanding buffers from the client, if required.
|
|
sl@0
|
215 |
* this function is only allowed while the stream is in Idle state. this is an asynchronous operation.
|
|
sl@0
|
216 |
* if the call returns KErrNone it merely indicates a flush has been requested and there will be a subsequent FlushComplete() callback.
|
|
sl@0
|
217 |
* Note that this does not relate to the Commit() cycle, and is not considered transactional.
|
|
sl@0
|
218 |
*
|
|
sl@0
|
219 |
* @return a system wide error code. KErrNone if successful.
|
|
sl@0
|
220 |
* KErrNotReady if called while the stream is not in correct state. Other system wide error codes are also possible.
|
|
sl@0
|
221 |
*/
|
|
sl@0
|
222 |
virtual TInt Flush()=0;
|
|
sl@0
|
223 |
|
|
sl@0
|
224 |
/**
|
|
sl@0
|
225 |
* Adds an audio source to this stream.
|
|
sl@0
|
226 |
*
|
|
sl@0
|
227 |
* A stream cannot operate before a source has been set.
|
|
sl@0
|
228 |
* The source must be removed from the stream before the sink or the stream is destroyed.
|
|
sl@0
|
229 |
* The source can only be set while the stream is in uninitialized state.
|
|
sl@0
|
230 |
* this is an asynchronous call and the completion will be indicated to the
|
|
sl@0
|
231 |
* client via a callback in the stream observer interface.
|
|
sl@0
|
232 |
*
|
|
sl@0
|
233 |
* @param aSource the audio source for this stream.
|
|
sl@0
|
234 |
* @return an error code. KErrNone if successful, there will be a subsequent callback on MAudioStreamObserver::AddProcessingUnitComplete().
|
|
sl@0
|
235 |
* KErrInUse a source has already been set fot this stream.
|
|
sl@0
|
236 |
* KErrNotReady the stream is not in correct state.
|
|
sl@0
|
237 |
*/
|
|
sl@0
|
238 |
virtual TInt AddSource(MAudioProcessingUnit* aSource)=0;
|
|
sl@0
|
239 |
|
|
sl@0
|
240 |
/**
|
|
sl@0
|
241 |
* Adds sink for this stream.
|
|
sl@0
|
242 |
*
|
|
sl@0
|
243 |
* Stream cannot operate before source and sink have been set.
|
|
sl@0
|
244 |
* The sink must be removed from the stream before it is destroyed.
|
|
sl@0
|
245 |
* The sink can only be set while the stream is in uninitialized state.
|
|
sl@0
|
246 |
* this is an asynchronous call and the completion will be indicated to the
|
|
sl@0
|
247 |
* client via a callback in the stream observer interface.
|
|
sl@0
|
248 |
*
|
|
sl@0
|
249 |
* @param aSink the sink for this stream
|
|
sl@0
|
250 |
* @return an error code. KErrNone if successful, there will be a subsequent callback on MAudioStreamObserver::AddProcessingUnitComplete().
|
|
sl@0
|
251 |
* KErrInUse a sink has already been set fot this stream.
|
|
sl@0
|
252 |
* KErrNotReady the stream is not in correct state,
|
|
sl@0
|
253 |
*/
|
|
sl@0
|
254 |
virtual TInt AddSink(MAudioProcessingUnit* aSink)=0;
|
|
sl@0
|
255 |
|
|
sl@0
|
256 |
/**
|
|
sl@0
|
257 |
* Adds an codec for this stream.
|
|
sl@0
|
258 |
*
|
|
sl@0
|
259 |
* The codec must be removed from the stream before the codec or the stream
|
|
sl@0
|
260 |
* is deleted. The codec can only be set while the stream is in uninitialized state.
|
|
sl@0
|
261 |
* this is an asynchronous call and the completion will be indicated to
|
|
sl@0
|
262 |
* the client via a callback in the stream observer interface.
|
|
sl@0
|
263 |
*
|
|
sl@0
|
264 |
* @param aCodec the codec for this stream
|
|
sl@0
|
265 |
* @return an error code. KErrNone if successful, there will be a subsequent callback on MAudioStreamObserver::AddProcessingUnitComplete().
|
|
sl@0
|
266 |
* KErrInUse a codec has already been set fot this stream.
|
|
sl@0
|
267 |
* KErrNotReady the stream is not in correct state.
|
|
sl@0
|
268 |
*/
|
|
sl@0
|
269 |
virtual TInt AddAudioCodec(MAudioProcessingUnit* aCodec)=0;
|
|
sl@0
|
270 |
|
|
sl@0
|
271 |
/**
|
|
sl@0
|
272 |
* Adds an audio processing unit to this stream.
|
|
sl@0
|
273 |
*
|
|
sl@0
|
274 |
* The processing unit must be removed from the stream before the processing unit or the stream is removed from the context.
|
|
sl@0
|
275 |
* The supplied component must implement the AudioGainControl feature.
|
|
sl@0
|
276 |
*
|
|
sl@0
|
277 |
* @param aGainControl the gain control to add to this stream.
|
|
sl@0
|
278 |
* @return KErrNone if succesful returned, there will be a subsequent callback on MAudioStreamObserver::AddProcessingUnitComplete().
|
|
sl@0
|
279 |
* KErrInUse a gain control has already been set fot this stream.
|
|
sl@0
|
280 |
* KErrNotReady the stream is not in correct state.
|
|
sl@0
|
281 |
*/
|
|
sl@0
|
282 |
virtual TInt AddGainControl(MAudioProcessingUnit* aGainControl)=0;
|
|
sl@0
|
283 |
|
|
sl@0
|
284 |
/**
|
|
sl@0
|
285 |
* Removes any audio processing unit from this stream, whether it has been added by AddSource(), AddSink(), AddCodec() or AddGainControl().
|
|
sl@0
|
286 |
* this is an asynchronous function, on successful call there will be a subsequent RemoveProcessingUnitComplete() callback.
|
|
sl@0
|
287 |
* @param aProcessingUnit the processing unit to remove.
|
|
sl@0
|
288 |
* @return a system wide error code, KErrNone if successful, or the processing unit had not been added to the stream.
|
|
sl@0
|
289 |
* KErrNotReady the decoder is not in correct state. Other system wide error codes are also possible.
|
|
sl@0
|
290 |
*/
|
|
sl@0
|
291 |
virtual TInt RemoveProcessingUnit(MAudioProcessingUnit* aProcessingUnit)=0;
|
|
sl@0
|
292 |
|
|
sl@0
|
293 |
/**
|
|
sl@0
|
294 |
* Resets the duration counter.
|
|
sl@0
|
295 |
*
|
|
sl@0
|
296 |
* Used to differentiate between when a stream has been momentarily interrupted and when
|
|
sl@0
|
297 |
* a different conceptual use-case is underway. Defined for EIdle.
|
|
sl@0
|
298 |
*/
|
|
sl@0
|
299 |
virtual TInt ResetStreamTime()=0;
|
|
sl@0
|
300 |
|
|
sl@0
|
301 |
/**
|
|
sl@0
|
302 |
* Returns the duration of audio that has been processed from the hardware device perspective.
|
|
sl@0
|
303 |
* The time is reset when the MAudioStream object transfers from Initialized state to Idle.
|
|
sl@0
|
304 |
* as a result of calling Load(). It can be reset at other times using ResetStreamTime().
|
|
sl@0
|
305 |
*/
|
|
sl@0
|
306 |
virtual TInt GetStreamTime(TTimeIntervalMicroSeconds& aStreamTime)=0;
|
|
sl@0
|
307 |
|
|
sl@0
|
308 |
/**
|
|
sl@0
|
309 |
* A mechanism to obtain additional control APIs on the stream.
|
|
sl@0
|
310 |
*
|
|
sl@0
|
311 |
* These can be used to extend the basic play/record, pause, stop with future use-cases such as seek play.
|
|
sl@0
|
312 |
*
|
|
sl@0
|
313 |
* @param aType Uid that denotes the type of the interface.
|
|
sl@0
|
314 |
* @return the pointer to the specified interface, or NULL if it does not exist. Must be cast to correct type by the user..
|
|
sl@0
|
315 |
*/
|
|
sl@0
|
316 |
virtual TAny* Interface(TUid aType)=0;
|
|
sl@0
|
317 |
|
|
sl@0
|
318 |
/**
|
|
sl@0
|
319 |
* Returns the component instance id.
|
|
sl@0
|
320 |
*
|
|
sl@0
|
321 |
* @return component instance id.
|
|
sl@0
|
322 |
*/
|
|
sl@0
|
323 |
virtual TAudioStreamId InstanceId() const =0;
|
|
sl@0
|
324 |
|
|
sl@0
|
325 |
};
|
|
sl@0
|
326 |
|
|
sl@0
|
327 |
#endif // MAUDIOSTREAM_H
|