/*
* Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies).
* All rights reserved.
* This component and the accompanying materials are made available
* under the terms of "Eclipse Public License v1.0"
* which accompanies this distribution, and is available
* at the URL "http://www.eclipse.org/legal/epl-v10.html".
*
* Initial Contributors:
* Nokia Corporation - initial contribution.
*
* Contributors:
*
* Description:
*
*/




/**
 @file
 @publishedPartner
 @released
*/

#ifndef MAUDIOCODEC_H
#define MAUDIOCODEC_H

#include <a3f/a3fbase.h>
#include <a3f/maudioprocessingunit.h>
#include <a3f/maudiocodecobserver.h>


/**
 * A generic abstract interface for codecs.
 *
 * The client must add a codec to a stream for operation.
 * The codec can only be added to a stream when the codec is in uninitialized state.
 * The codec can only be removed from a stream when the codec is in uninitialized or dead states.
 */
class MAudioCodec
	{
	public:
	
	/**
	 * Sets the codec format.
	 *
	 * For encoders this sets the output format.
	 * For decoders this configures the input format.
	 * Format must be set before the codec can transfer to initialized state.
	 *
	 * @param aFormat codec format.
	 * @return An error code. KErrNone on success, otherwise one of the system wide error codes.
	 */
	virtual TInt SetFormat(TUid aFormat)=0;

	/**
	* Sets the sample rate in samples/sec.
	*
	* sets the sample rate of the encoded data,
	* and says nothing about the sample rate used on the output device
	* or whether re-sampling is required that is up to the adaptation.
	* the result of the operation is returned by MAudioCodecObserver::SampleRateSet().
	*
	* @param aSampleRate sample rate to be used, in samples/sec.
	* @return An error code. KErrNone on success, otherwise one of the system wide error codes.
	*/
	virtual TInt SetSampleRate(TInt aSampleRate)=0;

	/**
	* Sets the mode, e.g. mono/stereo. 
	* The result of the operation is returned by MAudioCodecObserver::ModeSet().
	*
	* @param aMode uid stating the mode.
	* @return An error code. KErrNone on success, otherwise one of the system wide error codes.
	*/
	virtual TInt SetMode(TUid aMode)=0;

	/**
	* This returns a list of supported sample rates. The list need just include those of the standard list 
	* that are supported. Includes rates supported by sample rate conversion. 
	* GetSupportedSampleRatesComplete() callback shows result.
	* TODO Need to document that the implementation is responsible for calling Reset() on aSupportedRates.
	*
	* @param aSupportedRates array that is populated with the supported rates list.
	* @return An error code. KErrNone on success, otherwise one of the system wide error codes.
	*/
	virtual TInt GetSupportedSamplesRates(RArray<TInt>& aSupportedRates)=0;

	/**
	* This returns a list of supported sample modes. The list corresponds to the current configuration 
	* and support may include the use of mono/stereo conversion etc. 
	* GetSupportedModesComplete() callback shows result.
	* TODO Need to document that the implementation is responsible for calling Reset() on aSupportedModes.
	*
	* @param aSupportedModes array that is populated with the supported modes list.
	* @return An error code. KErrNone on success, otherwise one of the system wide error codes.
	*/
	virtual TInt GetSupportedModes(RArray<TUid>& aSupportedModes)=0;

	/**
	* Registers an audio codec observer.
	*
	* Note that this function is meant for clients of the Audio codec. 
	* The client should unregister using UnregisterAudioCodecObserver() when applicable
	*
	* @param aObserver reference to the observer to register.
	* @return an error code. KErrNone if successful.
	*				KErrAlreadyExists if the client is already registered.
	*				KErrOutOfMemory in case of memory exhaustion.
	*/
	virtual TInt RegisterAudioCodecObserver(MAudioCodecObserver& aObserver)=0;

	/**
	* Unregisters an audio codec observer.
	*
	* @param aObserver reference to the observer to unregister.
	* @return an error code.  KErrNone if successful.
	* 						KErrNotFound if the client has not been registered as observer.
	*/
	virtual void UnregisterAudioCodecObserver(MAudioCodecObserver& aObserver)=0;

	};

#endif // MAUDIOCODEC_H