sl@0: /* sl@0: * Copyright (c) 2006-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: sl@0: #ifndef MAUDIOCONTEXT_H sl@0: #define MAUDIOCONTEXT_H sl@0: sl@0: #include sl@0: sl@0: #include sl@0: sl@0: class MAudioStream; sl@0: class MAudioProcessingUnit; sl@0: class MAudioContextObserver; sl@0: sl@0: /** sl@0: * An interface to an audio context. sl@0: * sl@0: * Audio context is a container for a set of logically related audio streams and audio processing units. sl@0: * All streams and processing units are created into a context. sl@0: * A new context can be created using an instance of CAudioContextFactory. sl@0: * When the context is no longer needed, it must be removed using CAudioContextFactory::DeleteAudioContext(). sl@0: */ sl@0: class MAudioContext sl@0: { sl@0: public: sl@0: sl@0: /** sl@0: * Returns the context identifier. sl@0: * sl@0: * @return return the context identifier sl@0: */ sl@0: virtual TAudioContextId ContextId() const = 0; sl@0: sl@0: /** sl@0: * Creates a new audio stream into this context. sl@0: * sl@0: * The stream must be removed using DeleteAudioStream() when it is no longer needed. sl@0: * sl@0: * @param aStream on return contains a pointer to the created stream. sl@0: * @return an error code. KErrNone if successful, otherwise one of the system wide error codes. sl@0: */ sl@0: virtual TInt CreateAudioStream(MAudioStream*& aStream)=0; sl@0: sl@0: /** sl@0: * Deletes an audio stream from this context. sl@0: * sl@0: * After removing the stream all references to it will become invalid and must not be used. sl@0: * At the end of the call, aStream will have been set to NULL. sl@0: * Calling DeleteAudioStream() with a parameter whose value is NULL is itself a null operation. sl@0: * @param aStream a pointer to the stream to Delete. sl@0: * @return an error code. KErrNone if successful, otherwise one of the system wide error codes. sl@0: */ sl@0: virtual void DeleteAudioStream(MAudioStream*& aStream)=0; sl@0: sl@0: /** sl@0: * Creates a new audio processing unit into this context. sl@0: * sl@0: * The processing unit must be removed using DeleteProcessingUnit() when it is no longer needed. sl@0: * sl@0: * @param aType the type of the processing unit. sl@0: * @param aProcessingUnit on return contains a pointer to the created processing unit. sl@0: * @return an error code. KErrNone if successful, otherwise one of the system wide error codes. sl@0: */ sl@0: virtual TInt CreateAudioProcessingUnit(TUid aTypeId, MAudioProcessingUnit*& aProcessingUnit)=0; sl@0: sl@0: /** sl@0: * Deletes the audio processing unit from this context. sl@0: * sl@0: * After removing the processing unit all references to it will become invalid and must not be used. sl@0: * At the end of the call, aProcessingUnit will have been set to NULL. sl@0: * Calling DeleteAudioProcessingUnit() with a parameter whose value is NULL is itself a null operation. sl@0: * @param aProcessingUnit a pointer to the processing unit to remove. sl@0: * @return an error code. KErrNone if successful, otherwise one of the system wide error codes. sl@0: */ sl@0: virtual void DeleteAudioProcessingUnit(MAudioProcessingUnit*& aProcessingUnit)=0; sl@0: sl@0: /** sl@0: * Apply changes made to audio components associated with this context. sl@0: * sl@0: * A state change applied to an Audio Stream should be considered "pending" until Commit() is called, sl@0: * in that the adaptation merely records that the state setting has been requested and does not seek sl@0: * to implement the state change until Commit(). sl@0: * sl@0: * Commit() can be thought of as an asynchronous call, and completion is signalled by the appropriate sl@0: * ContextEvent() callback of MAudioContextObserver. sl@0: * @return An error code. KErrNone on success. KErrNotReady if SetClientSettings() has not been called. sl@0: */ sl@0: virtual TInt Commit()=0; sl@0: sl@0: /** sl@0: * Forget any pending, requested changes made to this context or its components. sl@0: * sl@0: * Typically called where the client has started to request changes, has yet to call Commit() and changes its mind. sl@0: * sl@0: * @return A system wide error code. KErrNone on success. KErrNotReady if called during Commit() cycle. sl@0: */ sl@0: virtual TInt Reset()=0; sl@0: sl@0: /** sl@0: * Sets the client information used by the underlying MMRC. sl@0: * sl@0: * This must be called before any call to Commit(). The client context contains information about the client application sl@0: * which is utilising the audio functionality, since this will typically be a different process than is calling A3F. sl@0: * sl@0: * @param aSettings Essentially the process Id of the client application, sl@0: * the one whose details are used to determine capabilities and policy. sl@0: * @return an error code. KErrNone for success, otherwise one of the system-wide error codes. sl@0: */ sl@0: virtual TInt SetClientSettings(const TClientContextSettings& aSettings)=0; sl@0: sl@0: /** sl@0: * A mechanism to obtain extensions to the Context API. 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. sl@0: * 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: * Registers an audio context observer. sl@0: * sl@0: * The observer will be notified about context state changes. sl@0: * sl@0: * @param aObserver the observer reference to register. sl@0: * @return An error code. KErrNone on success, otherwise one of the system wide error codes. sl@0: */ sl@0: virtual TInt RegisterAudioContextObserver(MAudioContextObserver& aObserver) = 0; sl@0: sl@0: /** sl@0: * Unregisters an audio context observer. sl@0: * sl@0: * @param aObserver the observer reference to unregister. sl@0: * @return An error code. KErrNone on success, otherwise one of the system wide error codes. sl@0: */ sl@0: virtual void UnregisterAudioContextObserver(MAudioContextObserver& aObserver) = 0; sl@0: }; sl@0: sl@0: #endif // MAUDIOCONTEXT_H