1 /*

     2 * Copyright (c) 2007-2009 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     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".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:

    15 *

    16 */

    17 

    18 

    19 

    20 

    21 /**

    22  @file

    23  @publishedPartner

    24  @released

    25 */

    26 

    27 #ifndef MAUDIOSTREAM_H

    28 #define MAUDIOSTREAM_H

    29 

    30 #include <e32base.h>

    31 #include <f32file.h>

    32 #include <mmf/common/mmfcontroller.h>

    33 #include <a3f/a3fbase.h>

    34 

    35 class MAudioStreamObserver;

    36 class MAudioCodecObserver;

    37 class MAudioCodec;

    38 class MAudioProcessingUnit;

    39 

    40 /**

    41  * this is the main control interface for the state of a processing unit chain.

    42  *

    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.

    46  *

    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. 

    51  *

    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. 

    60  *

    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. 

    67  */

    68 class MAudioStream 

    69 	{

    70 public:

    71 	/**

    72 	 * Registers an audio stream observer.

    73 	 *

    74 	 * Note that this function is meant for clients of the Audio Stream. 

    75 	 * The client should unregister using UnregisterAudioStreamObserver() when applicable.

    76 	 *

    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.

    81 	 */

    82 	virtual TInt RegisterAudioStreamObserver(MAudioStreamObserver& aObserver)=0;

    83 

    84 	/**

    85 	 * Unregisters an audio stream observer.

    86 	 *

    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.

    89 	 */

    90 	virtual void UnregisterAudioStreamObserver(MAudioStreamObserver& aObserver)=0;

    91 

    92 

    93 	/**

    94 	 * Sets the type of audio being processed in this context.

    95 	 *

    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.

   100 	 *

   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.

   103 	 */

   104 	virtual TInt SetAudioType(const TAudioTypeSettings& aAudioTypeSettings)=0;

   105 

   106 	/**

   107 	 * Fetch the type of audio being processed in this stream.

   108 	 *

   109 	 * @param aAudioTypeSettings On return contains the audio type of this stream.

   110 	 */

   111 	virtual void GetAudioType(TAudioTypeSettings& aAudioTypeSettings) const = 0;

   112 

   113 	/**

   114 	 * Requests a transition to the EInitialized state. 

   115 	 *

   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.

   119 	 *

   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.

   124 	*/

   125 	virtual TInt Initialize()=0;

   126 

   127 	/**

   128 	 * Requests a transition to the EIdle state. 

   129 	 *

   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

   133 	 *

   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

   137 	 *

   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.

   142 	 */

   143 	virtual TInt Load()=0;

   144 

   145 	/**

   146 	 * Starts the audio processing. this function is only allowed while the stream is in EIdle or EPrimed states. 

   147 	 *

   148 	 * The start-up procedures include requesting permission for audio processing from audio policy. 

   149 	 *

   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

   152 	*/

   153 	virtual TInt Activate()=0;

   154 

   155 	/**

   156 	 * Requests a transition to the Idle state – stopping the ongoing operation. 

   157 	 *

   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

   164 	*/

   165 	virtual TInt Stop()=0;

   166 

   167 	/**

   168 	 * Prepares the audio stream for releasing the resources reserved for it and for the processing units attached to the stream.

   169 	 *

   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.

   172 	 *

   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.

   176 	 *

   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.

   180 	 */

   181 	virtual TInt Unload()=0;

   182 

   183 	/**

   184 	 * Requests a transition to the Unitialized state – returning the stream to its initial state.

   185 	 *

   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.

   189 	 *

   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.

   193 	 */

   194 	virtual TInt Uninitialize()=0;

   195 

   196 	/**

   197 	 * Requests a transition to the EPrime state. 

   198 	 * 

   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.

   203 	 *

   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

   207 	 */

   208 	virtual TInt Prime()=0;

   209 

   210 

   211 	/**

   212 	 * Empty any buffers that have been filled. 

   213 	 *

   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.

   218 	 *

   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.

   221 	 */

   222 	virtual TInt Flush()=0;

   223 

   224 	/**

   225 	 * Adds an audio source to this stream.

   226 	 *

   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.

   232  	 *

   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.

   237 	 */ 

   238 	virtual TInt AddSource(MAudioProcessingUnit* aSource)=0;

   239 

   240 	/**

   241 	 * Adds sink for this stream.

   242 	 *

   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.

   248 	 *

   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,

   253 	*/

   254 	virtual TInt AddSink(MAudioProcessingUnit* aSink)=0;

   255 

   256 	/**

   257 	 * Adds an codec for this stream.

   258 	 *

   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.

   263 	 *

   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.

   268 	 */

   269 	virtual TInt AddAudioCodec(MAudioProcessingUnit* aCodec)=0;

   270 

   271 	/**

   272 	 * Adds an audio processing unit to this stream. 

   273 	 *

   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. 

   276 	 * 

   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.

   281 	 */

   282 	virtual TInt AddGainControl(MAudioProcessingUnit* aGainControl)=0;

   283 

   284 	/**

   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. 

   290 	 */

   291 	virtual TInt RemoveProcessingUnit(MAudioProcessingUnit* aProcessingUnit)=0;

   292 

   293 	/**

   294 	 * Resets the duration counter. 

   295 	 *

   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.

   298 	 */

   299 	virtual TInt ResetStreamTime()=0;

   300 

   301 	/**

   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().

   305 	 */

   306 	virtual TInt GetStreamTime(TTimeIntervalMicroSeconds& aStreamTime)=0;

   307 

   308 	/**

   309 	 * A mechanism to obtain additional control APIs on the stream.  

   310 	 *

   311 	 * These can be used to extend the basic play/record, pause, stop with future use-cases such as seek play.	

   312 	 *

   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..

   315 	 */

   316 	virtual TAny* Interface(TUid aType)=0;

   317 

   318 	/**

   319 	 * Returns the component instance id.

   320 	 *

   321 	 * @return component instance id.

   322 	 */

   323 	virtual TAudioStreamId InstanceId() const =0;

   324 

   325 	};

   326 

   327 #endif // MAUDIOSTREAM_H