1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/mm/devsound/a3facf/inc/maudiostream.h Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,327 @@
1.4 +/*
1.5 +* Copyright (c) 2007-2009 Nokia Corporation and/or its subsidiary(-ies).
1.6 +* All rights reserved.
1.7 +* This component and the accompanying materials are made available
1.8 +* under the terms of "Eclipse Public License v1.0"
1.9 +* which accompanies this distribution, and is available
1.10 +* at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.11 +*
1.12 +* Initial Contributors:
1.13 +* Nokia Corporation - initial contribution.
1.14 +*
1.15 +* Contributors:
1.16 +*
1.17 +* Description:
1.18 +*
1.19 +*/
1.20 +
1.21 +
1.22 +
1.23 +
1.24 +/**
1.25 + @file
1.26 + @publishedPartner
1.27 + @released
1.28 +*/
1.29 +
1.30 +#ifndef MAUDIOSTREAM_H
1.31 +#define MAUDIOSTREAM_H
1.32 +
1.33 +#include <e32base.h>
1.34 +#include <f32file.h>
1.35 +#include <mmf/common/mmfcontroller.h>
1.36 +#include <a3f/a3fbase.h>
1.37 +
1.38 +class MAudioStreamObserver;
1.39 +class MAudioCodecObserver;
1.40 +class MAudioCodec;
1.41 +class MAudioProcessingUnit;
1.42 +
1.43 +/**
1.44 + * this is the main control interface for the state of a processing unit chain.
1.45 + *
1.46 + * An AudioStream object binds together audio components processing the same data.
1.47 + * An AudioStrem executes the audio processing states as requested by the client. The processing units
1.48 + * attached to a stream will follow the state of the stream.
1.49 + *
1.50 + * The possible states of an AudioStream object are:
1.51 + * EUninitialized: The state which the chain is in initially.
1.52 + * The logical chain can be constructed.
1.53 + * The settings in the logical chain cannot be related to the adaptation because no adaptation has been selected yet.
1.54 + *
1.55 + * EInitialized: this state is set after a successful initialization request.
1.56 + * EIdle: All the chain resources are allocated, however, no processing time
1.57 + * (other than expended to put the chain into EIdle state) is consumed in this phase.
1.58 + * EPrimed: As per EIdle, but the stream can consume processing time, by filling its buffers.
1.59 + * EActive: The chain has all the resources as per EIdle and EPrimed but also has started to
1.60 + * process the actions requested by the client.
1.61 + * EDead: The stream can no longer function due to fatal error.
1.62 + * The logical chain still exists, but any physical resources should be reclaimed by the adaptation.
1.63 + *
1.64 + * The MAudioStreamObserver includes completion callbacks for many of the methods of MAudioStream.
1.65 + * The protocol is such that when an asynchronous method is called and KErrNone is returned,
1.66 + * then the call will be followed by a corresponding callback. if the returned error code from
1.67 + * the asynchronous function is other than KErrNone, then a callback will not be made as
1.68 + * a result of that method call. The callbacks will always occur out-of-context.
1.69 + * Note that many of the functions will also require a context commit for the actual processing to take place.
1.70 + */
1.71 +class MAudioStream
1.72 + {
1.73 +public:
1.74 + /**
1.75 + * Registers an audio stream observer.
1.76 + *
1.77 + * Note that this function is meant for clients of the Audio Stream.
1.78 + * The client should unregister using UnregisterAudioStreamObserver() when applicable.
1.79 + *
1.80 + * @param aObserver reference to the observer to register.
1.81 + * @return an error code. KErrNone if successful.
1.82 + * KErrAlreadyExists if the client is already registered.
1.83 + * KErrOutOfMemory in case of memory exhaustion.
1.84 + */
1.85 + virtual TInt RegisterAudioStreamObserver(MAudioStreamObserver& aObserver)=0;
1.86 +
1.87 + /**
1.88 + * Unregisters an audio stream observer.
1.89 + *
1.90 + * @param aObserver reference to the observer to unregister.
1.91 + * @return an error code. KErrNone if successful. KErrNotFound if the client has not been registered as observer.
1.92 + */
1.93 + virtual void UnregisterAudioStreamObserver(MAudioStreamObserver& aObserver)=0;
1.94 +
1.95 +
1.96 + /**
1.97 + * Sets the type of audio being processed in this context.
1.98 + *
1.99 + * The audio type settings are used by the resource control subsystem when it arbitrates between multiple clients
1.100 + * trying to access the same resource. Additionally it may impact the availability of certain audio features for the client.
1.101 + * It may also have an effect on other aspects, including, but not limited to routing and automatically applied effects.
1.102 + * The audio types available for the client may be limited by the platform security capabilities, vendorId etc of the client application.
1.103 + *
1.104 + * @param aAudioTypeSettings defines the settings associated with this stream.
1.105 + * @return an error code. KErrNone if successful, otherwise one of the system wide error codes.
1.106 + */
1.107 + virtual TInt SetAudioType(const TAudioTypeSettings& aAudioTypeSettings)=0;
1.108 +
1.109 + /**
1.110 + * Fetch the type of audio being processed in this stream.
1.111 + *
1.112 + * @param aAudioTypeSettings On return contains the audio type of this stream.
1.113 + */
1.114 + virtual void GetAudioType(TAudioTypeSettings& aAudioTypeSettings) const = 0;
1.115 +
1.116 + /**
1.117 + * Requests a transition to the EInitialized state.
1.118 + *
1.119 + * this function is asynchronous, and its successful return merely issues a request which is acted upon on Commit(),
1.120 + * and while will lead to a StateEvent() callback. this function is only allowed while the stream is in EUninitialized state.
1.121 + * A call in any other state will cause an error code of KErrNotReady to be returned.
1.122 + *
1.123 + * @return an error code. if KErrNone, the state transition has been requested,
1.124 + * and there will be a StateEvent() callback following Commit().
1.125 + * On error, there is no request made: KErrNotReady states the stream if not in valid current state,
1.126 + * otherwise one of the system-wide error codes.
1.127 + */
1.128 + virtual TInt Initialize()=0;
1.129 +
1.130 + /**
1.131 + * Requests a transition to the EIdle state.
1.132 + *
1.133 + * this function is asynchronous, and its successful return merely issues a request which is acted upon on Commit(),
1.134 + * and while will lead to a StateEvent() callback. this function is only allowed while the stream is in EInitialized state.
1.135 + * A call in any other state will cause an error code of KErrNotReady to be returned
1.136 + *
1.137 + * The resources must be released using Unload() when they are no longer needed.
1.138 + * Note that it is recommended that the resources are not kept reserved for long periods of inactivity,
1.139 + * since it may prevent other audio streams from becoming active by stealing resources they need to use
1.140 + *
1.141 + * @return An error code. if KErrNone, the state transition has been requested,
1.142 + * and there will be a StateEvent() callback following Commit().
1.143 + * On error, there is no request made: KErrNotReady states the stream if not in valid current state,
1.144 + * otherwise one of the system-wide error codes.
1.145 + */
1.146 + virtual TInt Load()=0;
1.147 +
1.148 + /**
1.149 + * Starts the audio processing. this function is only allowed while the stream is in EIdle or EPrimed states.
1.150 + *
1.151 + * The start-up procedures include requesting permission for audio processing from audio policy.
1.152 + *
1.153 + * @return an error code. A call in any state different to EIdle or EPrimed will cause an error code of KErrNotReady.
1.154 + * if permission to start is denied by audio policy, a state change back to EPrimed will occur with error code KErrAccessDenied
1.155 + */
1.156 + virtual TInt Activate()=0;
1.157 +
1.158 + /**
1.159 + * Requests a transition to the Idle state – stopping the ongoing operation.
1.160 + *
1.161 + * this function is asynchronous, and its successful return merely issues a request which is acted upon on Commit(),
1.162 + * and while will lead to a StateEvent() callback this function is only allowed while the stream is either Active or Primed.
1.163 + * A call in any other state will cause an error code of KErrNotReady to be returned.
1.164 + * @return An error code. if KErrNone, the state transition has been requested, and there will be a StateEvent() callback
1.165 + * following Commit(). On error, there is no request made: KErrNotReady states the stream if not in valid current state,
1.166 + * otherwise one of the system-wide error codes
1.167 + */
1.168 + virtual TInt Stop()=0;
1.169 +
1.170 + /**
1.171 + * Prepares the audio stream for releasing the resources reserved for it and for the processing units attached to the stream.
1.172 + *
1.173 + * this function is only allowed while the stream is EIdle state.
1.174 + * A call in any other state will cause an error code of KErrNotReady to be returned.
1.175 + *
1.176 + * During this call the stream will query all attached processing units whether they are ready to unload.
1.177 + * if a processing unit indicates that it is not ready to uninitialize, then an error code other than KErrNone will be returned.
1.178 + * Provided that this call succeeds, the actual unloading process will begins once Commit() is called for the context of this stream.
1.179 + *
1.180 + * @return An error code. KErrNone if successful.
1.181 + * KErrNotReady if called while the stream is not in correct state.
1.182 + * Other system wide error codes are also possible.
1.183 + */
1.184 + virtual TInt Unload()=0;
1.185 +
1.186 + /**
1.187 + * Requests a transition to the Unitialized state – returning the stream to its initial state.
1.188 + *
1.189 + * this function is asynchronous, and its successful return merely issues a request which is acted upon on Commit(),
1.190 + * and while will lead to a StateEvent() callback. this function is only allowed while the stream is in Initialized state.
1.191 + * A call in any other state will cause an error code of KErrNotReady to be returned.
1.192 + *
1.193 + * @return an error code. if KErrNone, the state transition has been requested, and there will be a StateEvent() callback
1.194 + * following Commit(). On error, there is no request made: KErrNotReady states the stream if not in valid current state,
1.195 + * otherwise one of the system-wide error codes.
1.196 + */
1.197 + virtual TInt Uninitialize()=0;
1.198 +
1.199 + /**
1.200 + * Requests a transition to the EPrime state.
1.201 + *
1.202 + * this function is asynchronous, and its successful return merely issues a request which is acted upon on Commit(),
1.203 + * and while will lead to a StateEvent() callback. this function is only allowed while the stream is in EActive
1.204 + * (semantics of Prime in EActive– go into a buffering pause) or EIdle state (semantics of Prime in EIdle – start to buffer).
1.205 + * A call in any other state will cause an error code of KErrNotReady to be returned. Not all streams support Prime.
1.206 + *
1.207 + * @return an error code. if KErrNone, the state transition has been requested, and there will be a StateEvent() callback
1.208 + * following Commit(). On error, there is no request made: KErrNotReady states the stream if not in valid current state,
1.209 + * otherwise one of the system-wide error codes
1.210 + */
1.211 + virtual TInt Prime()=0;
1.212 +
1.213 +
1.214 + /**
1.215 + * Empty any buffers that have been filled.
1.216 + *
1.217 + * Reclain any outstanding buffers from the client, if required.
1.218 + * this function is only allowed while the stream is in Idle state. this is an asynchronous operation.
1.219 + * if the call returns KErrNone it merely indicates a flush has been requested and there will be a subsequent FlushComplete() callback.
1.220 + * Note that this does not relate to the Commit() cycle, and is not considered transactional.
1.221 + *
1.222 + * @return a system wide error code. KErrNone if successful.
1.223 + * KErrNotReady if called while the stream is not in correct state. Other system wide error codes are also possible.
1.224 + */
1.225 + virtual TInt Flush()=0;
1.226 +
1.227 + /**
1.228 + * Adds an audio source to this stream.
1.229 + *
1.230 + * A stream cannot operate before a source has been set.
1.231 + * The source must be removed from the stream before the sink or the stream is destroyed.
1.232 + * The source can only be set while the stream is in uninitialized state.
1.233 + * this is an asynchronous call and the completion will be indicated to the
1.234 + * client via a callback in the stream observer interface.
1.235 + *
1.236 + * @param aSource the audio source for this stream.
1.237 + * @return an error code. KErrNone if successful, there will be a subsequent callback on MAudioStreamObserver::AddProcessingUnitComplete().
1.238 + * KErrInUse a source has already been set fot this stream.
1.239 + * KErrNotReady the stream is not in correct state.
1.240 + */
1.241 + virtual TInt AddSource(MAudioProcessingUnit* aSource)=0;
1.242 +
1.243 + /**
1.244 + * Adds sink for this stream.
1.245 + *
1.246 + * Stream cannot operate before source and sink have been set.
1.247 + * The sink must be removed from the stream before it is destroyed.
1.248 + * The sink can only be set while the stream is in uninitialized state.
1.249 + * this is an asynchronous call and the completion will be indicated to the
1.250 + * client via a callback in the stream observer interface.
1.251 + *
1.252 + * @param aSink the sink for this stream
1.253 + * @return an error code. KErrNone if successful, there will be a subsequent callback on MAudioStreamObserver::AddProcessingUnitComplete().
1.254 + * KErrInUse a sink has already been set fot this stream.
1.255 + * KErrNotReady the stream is not in correct state,
1.256 + */
1.257 + virtual TInt AddSink(MAudioProcessingUnit* aSink)=0;
1.258 +
1.259 + /**
1.260 + * Adds an codec for this stream.
1.261 + *
1.262 + * The codec must be removed from the stream before the codec or the stream
1.263 + * is deleted. The codec can only be set while the stream is in uninitialized state.
1.264 + * this is an asynchronous call and the completion will be indicated to
1.265 + * the client via a callback in the stream observer interface.
1.266 + *
1.267 + * @param aCodec the codec for this stream
1.268 + * @return an error code. KErrNone if successful, there will be a subsequent callback on MAudioStreamObserver::AddProcessingUnitComplete().
1.269 + * KErrInUse a codec has already been set fot this stream.
1.270 + * KErrNotReady the stream is not in correct state.
1.271 + */
1.272 + virtual TInt AddAudioCodec(MAudioProcessingUnit* aCodec)=0;
1.273 +
1.274 + /**
1.275 + * Adds an audio processing unit to this stream.
1.276 + *
1.277 + * The processing unit must be removed from the stream before the processing unit or the stream is removed from the context.
1.278 + * The supplied component must implement the AudioGainControl feature.
1.279 + *
1.280 + * @param aGainControl the gain control to add to this stream.
1.281 + * @return KErrNone if succesful returned, there will be a subsequent callback on MAudioStreamObserver::AddProcessingUnitComplete().
1.282 + * KErrInUse a gain control has already been set fot this stream.
1.283 + * KErrNotReady the stream is not in correct state.
1.284 + */
1.285 + virtual TInt AddGainControl(MAudioProcessingUnit* aGainControl)=0;
1.286 +
1.287 + /**
1.288 + * Removes any audio processing unit from this stream, whether it has been added by AddSource(), AddSink(), AddCodec() or AddGainControl().
1.289 + * this is an asynchronous function, on successful call there will be a subsequent RemoveProcessingUnitComplete() callback.
1.290 + * @param aProcessingUnit the processing unit to remove.
1.291 + * @return a system wide error code, KErrNone if successful, or the processing unit had not been added to the stream.
1.292 + * KErrNotReady the decoder is not in correct state. Other system wide error codes are also possible.
1.293 + */
1.294 + virtual TInt RemoveProcessingUnit(MAudioProcessingUnit* aProcessingUnit)=0;
1.295 +
1.296 + /**
1.297 + * Resets the duration counter.
1.298 + *
1.299 + * Used to differentiate between when a stream has been momentarily interrupted and when
1.300 + * a different conceptual use-case is underway. Defined for EIdle.
1.301 + */
1.302 + virtual TInt ResetStreamTime()=0;
1.303 +
1.304 + /**
1.305 + * Returns the duration of audio that has been processed from the hardware device perspective.
1.306 + * The time is reset when the MAudioStream object transfers from Initialized state to Idle.
1.307 + * as a result of calling Load(). It can be reset at other times using ResetStreamTime().
1.308 + */
1.309 + virtual TInt GetStreamTime(TTimeIntervalMicroSeconds& aStreamTime)=0;
1.310 +
1.311 + /**
1.312 + * A mechanism to obtain additional control APIs on the stream.
1.313 + *
1.314 + * These can be used to extend the basic play/record, pause, stop with future use-cases such as seek play.
1.315 + *
1.316 + * @param aType Uid that denotes the type of the interface.
1.317 + * @return the pointer to the specified interface, or NULL if it does not exist. Must be cast to correct type by the user..
1.318 + */
1.319 + virtual TAny* Interface(TUid aType)=0;
1.320 +
1.321 + /**
1.322 + * Returns the component instance id.
1.323 + *
1.324 + * @return component instance id.
1.325 + */
1.326 + virtual TAudioStreamId InstanceId() const =0;
1.327 +
1.328 + };
1.329 +
1.330 +#endif // MAUDIOSTREAM_H