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