1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/mm/devsound/a3facf/inc/maudiocontext.h Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,163 @@
1.4 +/*
1.5 +* Copyright (c) 2006-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 +
1.31 +#ifndef MAUDIOCONTEXT_H
1.32 +#define MAUDIOCONTEXT_H
1.33 +
1.34 +#include <e32base.h>
1.35 +
1.36 +#include <a3f/a3fbase.h>
1.37 +
1.38 +class MAudioStream;
1.39 +class MAudioProcessingUnit;
1.40 +class MAudioContextObserver;
1.41 +
1.42 +/**
1.43 + * An interface to an audio context.
1.44 + *
1.45 + * Audio context is a container for a set of logically related audio streams and audio processing units.
1.46 + * All streams and processing units are created into a context.
1.47 + * A new context can be created using an instance of CAudioContextFactory.
1.48 + * When the context is no longer needed, it must be removed using CAudioContextFactory::DeleteAudioContext().
1.49 + */
1.50 +class MAudioContext
1.51 + {
1.52 +public:
1.53 +
1.54 + /**
1.55 + * Returns the context identifier.
1.56 + *
1.57 + * @return return the context identifier
1.58 + */
1.59 + virtual TAudioContextId ContextId() const = 0;
1.60 +
1.61 + /**
1.62 + * Creates a new audio stream into this context.
1.63 + *
1.64 + * The stream must be removed using DeleteAudioStream() when it is no longer needed.
1.65 + *
1.66 + * @param aStream on return contains a pointer to the created stream.
1.67 + * @return an error code. KErrNone if successful, otherwise one of the system wide error codes.
1.68 + */
1.69 + virtual TInt CreateAudioStream(MAudioStream*& aStream)=0;
1.70 +
1.71 + /**
1.72 + * Deletes an audio stream from this context.
1.73 + *
1.74 + * After removing the stream all references to it will become invalid and must not be used.
1.75 + * At the end of the call, aStream will have been set to NULL.
1.76 + * Calling DeleteAudioStream() with a parameter whose value is NULL is itself a null operation.
1.77 + * @param aStream a pointer to the stream to Delete.
1.78 + * @return an error code. KErrNone if successful, otherwise one of the system wide error codes.
1.79 + */
1.80 + virtual void DeleteAudioStream(MAudioStream*& aStream)=0;
1.81 +
1.82 + /**
1.83 + * Creates a new audio processing unit into this context.
1.84 + *
1.85 + * The processing unit must be removed using DeleteProcessingUnit() when it is no longer needed.
1.86 + *
1.87 + * @param aType the type of the processing unit.
1.88 + * @param aProcessingUnit on return contains a pointer to the created processing unit.
1.89 + * @return an error code. KErrNone if successful, otherwise one of the system wide error codes.
1.90 + */
1.91 + virtual TInt CreateAudioProcessingUnit(TUid aTypeId, MAudioProcessingUnit*& aProcessingUnit)=0;
1.92 +
1.93 + /**
1.94 + * Deletes the audio processing unit from this context.
1.95 + *
1.96 + * After removing the processing unit all references to it will become invalid and must not be used.
1.97 + * At the end of the call, aProcessingUnit will have been set to NULL.
1.98 + * Calling DeleteAudioProcessingUnit() with a parameter whose value is NULL is itself a null operation.
1.99 + * @param aProcessingUnit a pointer to the processing unit to remove.
1.100 + * @return an error code. KErrNone if successful, otherwise one of the system wide error codes.
1.101 + */
1.102 + virtual void DeleteAudioProcessingUnit(MAudioProcessingUnit*& aProcessingUnit)=0;
1.103 +
1.104 + /**
1.105 + * Apply changes made to audio components associated with this context.
1.106 + *
1.107 + * A state change applied to an Audio Stream should be considered "pending" until Commit() is called,
1.108 + * in that the adaptation merely records that the state setting has been requested and does not seek
1.109 + * to implement the state change until Commit().
1.110 + *
1.111 + * Commit() can be thought of as an asynchronous call, and completion is signalled by the appropriate
1.112 + * ContextEvent() callback of MAudioContextObserver.
1.113 + * @return An error code. KErrNone on success. KErrNotReady if SetClientSettings() has not been called.
1.114 + */
1.115 + virtual TInt Commit()=0;
1.116 +
1.117 + /**
1.118 + * Forget any pending, requested changes made to this context or its components.
1.119 + *
1.120 + * Typically called where the client has started to request changes, has yet to call Commit() and changes its mind.
1.121 + *
1.122 + * @return A system wide error code. KErrNone on success. KErrNotReady if called during Commit() cycle.
1.123 + */
1.124 + virtual TInt Reset()=0;
1.125 +
1.126 + /**
1.127 + * Sets the client information used by the underlying MMRC.
1.128 + *
1.129 + * This must be called before any call to Commit(). The client context contains information about the client application
1.130 + * which is utilising the audio functionality, since this will typically be a different process than is calling A3F.
1.131 + *
1.132 + * @param aSettings Essentially the process Id of the client application,
1.133 + * the one whose details are used to determine capabilities and policy.
1.134 + * @return an error code. KErrNone for success, otherwise one of the system-wide error codes.
1.135 + */
1.136 + virtual TInt SetClientSettings(const TClientContextSettings& aSettings)=0;
1.137 +
1.138 + /**
1.139 + * A mechanism to obtain extensions to the Context API.
1.140 + *
1.141 + * @param aType Uid that denotes the type of the interface.
1.142 + * @return the pointer to the specified interface, or NULL if it does not exist.
1.143 + * Must be cast to correct type by the user.
1.144 + */
1.145 + virtual TAny* Interface(TUid aType)=0;
1.146 +
1.147 + /**
1.148 + * Registers an audio context observer.
1.149 + *
1.150 + * The observer will be notified about context state changes.
1.151 + *
1.152 + * @param aObserver the observer reference to register.
1.153 + * @return An error code. KErrNone on success, otherwise one of the system wide error codes.
1.154 + */
1.155 + virtual TInt RegisterAudioContextObserver(MAudioContextObserver& aObserver) = 0;
1.156 +
1.157 + /**
1.158 + * Unregisters an audio context observer.
1.159 + *
1.160 + * @param aObserver the observer reference to unregister.
1.161 + * @return An error code. KErrNone on success, otherwise one of the system wide error codes.
1.162 + */
1.163 + virtual void UnregisterAudioContextObserver(MAudioContextObserver& aObserver) = 0;
1.164 + };
1.165 +
1.166 +#endif // MAUDIOCONTEXT_H