sl@0: /* sl@0: * Copyright (c) 2007-2009 Nokia Corporation and/or its subsidiary(-ies). sl@0: * All rights reserved. sl@0: * This component and the accompanying materials are made available sl@0: * under the terms of "Eclipse Public License v1.0" sl@0: * which accompanies this distribution, and is available sl@0: * at the URL "http://www.eclipse.org/legal/epl-v10.html". sl@0: * sl@0: * Initial Contributors: sl@0: * Nokia Corporation - initial contribution. sl@0: * sl@0: * Contributors: sl@0: * sl@0: * Description: sl@0: * sl@0: */ sl@0: sl@0: sl@0: sl@0: sl@0: /** sl@0: @file sl@0: @publishedPartner sl@0: @released sl@0: */ sl@0: sl@0: #ifndef MAUDIOSTREAM_H sl@0: #define MAUDIOSTREAM_H sl@0: sl@0: #include sl@0: #include sl@0: #include sl@0: #include sl@0: sl@0: class MAudioStreamObserver; sl@0: class MAudioCodecObserver; sl@0: class MAudioCodec; sl@0: class MAudioProcessingUnit; sl@0: sl@0: /** sl@0: * this is the main control interface for the state of a processing unit chain. sl@0: * sl@0: * An AudioStream object binds together audio components processing the same data. sl@0: * An AudioStrem executes the audio processing states as requested by the client. The processing units sl@0: * attached to a stream will follow the state of the stream. sl@0: * sl@0: * The possible states of an AudioStream object are: sl@0: * EUninitialized: The state which the chain is in initially. sl@0: * The logical chain can be constructed. sl@0: * The settings in the logical chain cannot be related to the adaptation because no adaptation has been selected yet. sl@0: * sl@0: * EInitialized: this state is set after a successful initialization request. sl@0: * EIdle: All the chain resources are allocated, however, no processing time sl@0: * (other than expended to put the chain into EIdle state) is consumed in this phase. sl@0: * EPrimed: As per EIdle, but the stream can consume processing time, by filling its buffers. sl@0: * EActive: The chain has all the resources as per EIdle and EPrimed but also has started to sl@0: * process the actions requested by the client. sl@0: * EDead: The stream can no longer function due to fatal error. sl@0: * The logical chain still exists, but any physical resources should be reclaimed by the adaptation. sl@0: * sl@0: * The MAudioStreamObserver includes completion callbacks for many of the methods of MAudioStream. sl@0: * The protocol is such that when an asynchronous method is called and KErrNone is returned, sl@0: * then the call will be followed by a corresponding callback. if the returned error code from sl@0: * the asynchronous function is other than KErrNone, then a callback will not be made as sl@0: * a result of that method call. The callbacks will always occur out-of-context. sl@0: * Note that many of the functions will also require a context commit for the actual processing to take place. sl@0: */ sl@0: class MAudioStream sl@0: { sl@0: public: sl@0: /** sl@0: * Registers an audio stream observer. sl@0: * sl@0: * Note that this function is meant for clients of the Audio Stream. sl@0: * The client should unregister using UnregisterAudioStreamObserver() when applicable. sl@0: * sl@0: * @param aObserver reference to the observer to register. sl@0: * @return an error code. KErrNone if successful. sl@0: * KErrAlreadyExists if the client is already registered. sl@0: * KErrOutOfMemory in case of memory exhaustion. sl@0: */ sl@0: virtual TInt RegisterAudioStreamObserver(MAudioStreamObserver& aObserver)=0; sl@0: sl@0: /** sl@0: * Unregisters an audio stream observer. sl@0: * sl@0: * @param aObserver reference to the observer to unregister. sl@0: * @return an error code. KErrNone if successful. KErrNotFound if the client has not been registered as observer. sl@0: */ sl@0: virtual void UnregisterAudioStreamObserver(MAudioStreamObserver& aObserver)=0; sl@0: sl@0: sl@0: /** sl@0: * Sets the type of audio being processed in this context. sl@0: * sl@0: * The audio type settings are used by the resource control subsystem when it arbitrates between multiple clients sl@0: * trying to access the same resource. Additionally it may impact the availability of certain audio features for the client. sl@0: * It may also have an effect on other aspects, including, but not limited to routing and automatically applied effects. sl@0: * The audio types available for the client may be limited by the platform security capabilities, vendorId etc of the client application. sl@0: * sl@0: * @param aAudioTypeSettings defines the settings associated with this stream. sl@0: * @return an error code. KErrNone if successful, otherwise one of the system wide error codes. sl@0: */ sl@0: virtual TInt SetAudioType(const TAudioTypeSettings& aAudioTypeSettings)=0; sl@0: sl@0: /** sl@0: * Fetch the type of audio being processed in this stream. sl@0: * sl@0: * @param aAudioTypeSettings On return contains the audio type of this stream. sl@0: */ sl@0: virtual void GetAudioType(TAudioTypeSettings& aAudioTypeSettings) const = 0; sl@0: sl@0: /** sl@0: * Requests a transition to the EInitialized state. sl@0: * sl@0: * this function is asynchronous, and its successful return merely issues a request which is acted upon on Commit(), sl@0: * and while will lead to a StateEvent() callback. this function is only allowed while the stream is in EUninitialized state. sl@0: * A call in any other state will cause an error code of KErrNotReady to be returned. sl@0: * sl@0: * @return an error code. if KErrNone, the state transition has been requested, sl@0: * and there will be a StateEvent() callback following Commit(). sl@0: * On error, there is no request made: KErrNotReady states the stream if not in valid current state, sl@0: * otherwise one of the system-wide error codes. sl@0: */ sl@0: virtual TInt Initialize()=0; sl@0: sl@0: /** sl@0: * Requests a transition to the EIdle state. sl@0: * sl@0: * this function is asynchronous, and its successful return merely issues a request which is acted upon on Commit(), sl@0: * and while will lead to a StateEvent() callback. this function is only allowed while the stream is in EInitialized state. sl@0: * A call in any other state will cause an error code of KErrNotReady to be returned sl@0: * sl@0: * The resources must be released using Unload() when they are no longer needed. sl@0: * Note that it is recommended that the resources are not kept reserved for long periods of inactivity, sl@0: * since it may prevent other audio streams from becoming active by stealing resources they need to use sl@0: * sl@0: * @return An error code. if KErrNone, the state transition has been requested, sl@0: * and there will be a StateEvent() callback following Commit(). sl@0: * On error, there is no request made: KErrNotReady states the stream if not in valid current state, sl@0: * otherwise one of the system-wide error codes. sl@0: */ sl@0: virtual TInt Load()=0; sl@0: sl@0: /** sl@0: * Starts the audio processing. this function is only allowed while the stream is in EIdle or EPrimed states. sl@0: * sl@0: * The start-up procedures include requesting permission for audio processing from audio policy. sl@0: * sl@0: * @return an error code. A call in any state different to EIdle or EPrimed will cause an error code of KErrNotReady. sl@0: * if permission to start is denied by audio policy, a state change back to EPrimed will occur with error code KErrAccessDenied sl@0: */ sl@0: virtual TInt Activate()=0; sl@0: sl@0: /** sl@0: * Requests a transition to the Idle state – stopping the ongoing operation. sl@0: * sl@0: * this function is asynchronous, and its successful return merely issues a request which is acted upon on Commit(), sl@0: * and while will lead to a StateEvent() callback this function is only allowed while the stream is either Active or Primed. sl@0: * A call in any other state will cause an error code of KErrNotReady to be returned. sl@0: * @return An error code. if KErrNone, the state transition has been requested, and there will be a StateEvent() callback sl@0: * following Commit(). On error, there is no request made: KErrNotReady states the stream if not in valid current state, sl@0: * otherwise one of the system-wide error codes sl@0: */ sl@0: virtual TInt Stop()=0; sl@0: sl@0: /** sl@0: * Prepares the audio stream for releasing the resources reserved for it and for the processing units attached to the stream. sl@0: * sl@0: * this function is only allowed while the stream is EIdle state. sl@0: * A call in any other state will cause an error code of KErrNotReady to be returned. sl@0: * sl@0: * During this call the stream will query all attached processing units whether they are ready to unload. sl@0: * if a processing unit indicates that it is not ready to uninitialize, then an error code other than KErrNone will be returned. sl@0: * Provided that this call succeeds, the actual unloading process will begins once Commit() is called for the context of this stream. sl@0: * sl@0: * @return An error code. KErrNone if successful. sl@0: * KErrNotReady if called while the stream is not in correct state. sl@0: * Other system wide error codes are also possible. sl@0: */ sl@0: virtual TInt Unload()=0; sl@0: sl@0: /** sl@0: * Requests a transition to the Unitialized state – returning the stream to its initial state. sl@0: * sl@0: * this function is asynchronous, and its successful return merely issues a request which is acted upon on Commit(), sl@0: * and while will lead to a StateEvent() callback. this function is only allowed while the stream is in Initialized state. sl@0: * A call in any other state will cause an error code of KErrNotReady to be returned. sl@0: * sl@0: * @return an error code. if KErrNone, the state transition has been requested, and there will be a StateEvent() callback sl@0: * following Commit(). On error, there is no request made: KErrNotReady states the stream if not in valid current state, sl@0: * otherwise one of the system-wide error codes. sl@0: */ sl@0: virtual TInt Uninitialize()=0; sl@0: sl@0: /** sl@0: * Requests a transition to the EPrime state. sl@0: * sl@0: * this function is asynchronous, and its successful return merely issues a request which is acted upon on Commit(), sl@0: * and while will lead to a StateEvent() callback. this function is only allowed while the stream is in EActive sl@0: * (semantics of Prime in EActive– go into a buffering pause) or EIdle state (semantics of Prime in EIdle – start to buffer). sl@0: * A call in any other state will cause an error code of KErrNotReady to be returned. Not all streams support Prime. sl@0: * sl@0: * @return an error code. if KErrNone, the state transition has been requested, and there will be a StateEvent() callback sl@0: * following Commit(). On error, there is no request made: KErrNotReady states the stream if not in valid current state, sl@0: * otherwise one of the system-wide error codes sl@0: */ sl@0: virtual TInt Prime()=0; sl@0: sl@0: sl@0: /** sl@0: * Empty any buffers that have been filled. sl@0: * sl@0: * Reclain any outstanding buffers from the client, if required. sl@0: * this function is only allowed while the stream is in Idle state. this is an asynchronous operation. sl@0: * if the call returns KErrNone it merely indicates a flush has been requested and there will be a subsequent FlushComplete() callback. sl@0: * Note that this does not relate to the Commit() cycle, and is not considered transactional. sl@0: * sl@0: * @return a system wide error code. KErrNone if successful. sl@0: * KErrNotReady if called while the stream is not in correct state. Other system wide error codes are also possible. sl@0: */ sl@0: virtual TInt Flush()=0; sl@0: sl@0: /** sl@0: * Adds an audio source to this stream. sl@0: * sl@0: * A stream cannot operate before a source has been set. sl@0: * The source must be removed from the stream before the sink or the stream is destroyed. sl@0: * The source can only be set while the stream is in uninitialized state. sl@0: * this is an asynchronous call and the completion will be indicated to the sl@0: * client via a callback in the stream observer interface. sl@0: * sl@0: * @param aSource the audio source for this stream. sl@0: * @return an error code. KErrNone if successful, there will be a subsequent callback on MAudioStreamObserver::AddProcessingUnitComplete(). sl@0: * KErrInUse a source has already been set fot this stream. sl@0: * KErrNotReady the stream is not in correct state. sl@0: */ sl@0: virtual TInt AddSource(MAudioProcessingUnit* aSource)=0; sl@0: sl@0: /** sl@0: * Adds sink for this stream. sl@0: * sl@0: * Stream cannot operate before source and sink have been set. sl@0: * The sink must be removed from the stream before it is destroyed. sl@0: * The sink can only be set while the stream is in uninitialized state. sl@0: * this is an asynchronous call and the completion will be indicated to the sl@0: * client via a callback in the stream observer interface. sl@0: * sl@0: * @param aSink the sink for this stream sl@0: * @return an error code. KErrNone if successful, there will be a subsequent callback on MAudioStreamObserver::AddProcessingUnitComplete(). sl@0: * KErrInUse a sink has already been set fot this stream. sl@0: * KErrNotReady the stream is not in correct state, sl@0: */ sl@0: virtual TInt AddSink(MAudioProcessingUnit* aSink)=0; sl@0: sl@0: /** sl@0: * Adds an codec for this stream. sl@0: * sl@0: * The codec must be removed from the stream before the codec or the stream sl@0: * is deleted. The codec can only be set while the stream is in uninitialized state. sl@0: * this is an asynchronous call and the completion will be indicated to sl@0: * the client via a callback in the stream observer interface. sl@0: * sl@0: * @param aCodec the codec for this stream sl@0: * @return an error code. KErrNone if successful, there will be a subsequent callback on MAudioStreamObserver::AddProcessingUnitComplete(). sl@0: * KErrInUse a codec has already been set fot this stream. sl@0: * KErrNotReady the stream is not in correct state. sl@0: */ sl@0: virtual TInt AddAudioCodec(MAudioProcessingUnit* aCodec)=0; sl@0: sl@0: /** sl@0: * Adds an audio processing unit to this stream. sl@0: * sl@0: * The processing unit must be removed from the stream before the processing unit or the stream is removed from the context. sl@0: * The supplied component must implement the AudioGainControl feature. sl@0: * sl@0: * @param aGainControl the gain control to add to this stream. sl@0: * @return KErrNone if succesful returned, there will be a subsequent callback on MAudioStreamObserver::AddProcessingUnitComplete(). sl@0: * KErrInUse a gain control has already been set fot this stream. sl@0: * KErrNotReady the stream is not in correct state. sl@0: */ sl@0: virtual TInt AddGainControl(MAudioProcessingUnit* aGainControl)=0; sl@0: sl@0: /** sl@0: * Removes any audio processing unit from this stream, whether it has been added by AddSource(), AddSink(), AddCodec() or AddGainControl(). sl@0: * this is an asynchronous function, on successful call there will be a subsequent RemoveProcessingUnitComplete() callback. sl@0: * @param aProcessingUnit the processing unit to remove. sl@0: * @return a system wide error code, KErrNone if successful, or the processing unit had not been added to the stream. sl@0: * KErrNotReady the decoder is not in correct state. Other system wide error codes are also possible. sl@0: */ sl@0: virtual TInt RemoveProcessingUnit(MAudioProcessingUnit* aProcessingUnit)=0; sl@0: sl@0: /** sl@0: * Resets the duration counter. sl@0: * sl@0: * Used to differentiate between when a stream has been momentarily interrupted and when sl@0: * a different conceptual use-case is underway. Defined for EIdle. sl@0: */ sl@0: virtual TInt ResetStreamTime()=0; sl@0: sl@0: /** sl@0: * Returns the duration of audio that has been processed from the hardware device perspective. sl@0: * The time is reset when the MAudioStream object transfers from Initialized state to Idle. sl@0: * as a result of calling Load(). It can be reset at other times using ResetStreamTime(). sl@0: */ sl@0: virtual TInt GetStreamTime(TTimeIntervalMicroSeconds& aStreamTime)=0; sl@0: sl@0: /** sl@0: * A mechanism to obtain additional control APIs on the stream. sl@0: * sl@0: * These can be used to extend the basic play/record, pause, stop with future use-cases such as seek play. sl@0: * sl@0: * @param aType Uid that denotes the type of the interface. sl@0: * @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: */ sl@0: virtual TAny* Interface(TUid aType)=0; sl@0: sl@0: /** sl@0: * Returns the component instance id. sl@0: * sl@0: * @return component instance id. sl@0: */ sl@0: virtual TAudioStreamId InstanceId() const =0; sl@0: sl@0: }; sl@0: sl@0: #endif // MAUDIOSTREAM_H