sl@0: sl@0: // Copyright (c) 2002-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: #ifndef __MDAAUDIOINPUTSTREAM_H sl@0: #define __MDAAUDIOINPUTSTREAM_H sl@0: sl@0: sl@0: #include sl@0: #include sl@0: #include sl@0: #include sl@0: #include sl@0: sl@0: sl@0: /** sl@0: @publishedAll sl@0: @released sl@0: sl@0: An interface class that notifies the client of the progress of the audio input streaming. sl@0: sl@0: It must be implemented by users of the CMdaAudioInputStream class. sl@0: sl@0: An object that implements this interface is passed to CMdaAudioInputStream::NewL(). sl@0: */ sl@0: class MMdaAudioInputStreamCallback sl@0: { sl@0: public: sl@0: sl@0: /** sl@0: A callback function that is called when CMdaAudioInputStream::Open() has sl@0: completed, indicating that the audio input stream is ready for use. sl@0: sl@0: @param aError sl@0: An error value which indicates if open was successful or not. KErrNone if the open succeeded, sl@0: otherwise one of the system error codes. sl@0: sl@0: */ sl@0: virtual void MaiscOpenComplete(TInt aError) = 0; sl@0: sl@0: /** sl@0: A callback function that is called when a chunk of audio data has been copied to the descriptor specified sl@0: in a CMdaAudioInputStream::ReadL(). sl@0: sl@0: It is also called as part of a 'cleanup' operation when CMdaAudioInputStream::Stop() is used. In such circumstances, sl@0: the remaining audio data in the FIFO since the last ReadL() and the Stop() command is returned. In addition aError sl@0: is set to KErrAbort. sl@0: sl@0: Use this callback to retrieve the pointers to your recorded data and to issue subsequent ReadL() calls, and be prepared sl@0: to shut down you recording functions if KErrAbort (input stream closed) is returned in aError. sl@0: sl@0: @param aError sl@0: An error value indicating if the copy was successful. KErrNone if the copy succeeded, KErrAbort if the input stream sl@0: was closed for some reason, otherwise one of the system error codes. sl@0: @param aBuffer sl@0: A reference to the buffer that has been copied. sl@0: */ sl@0: virtual void MaiscBufferCopied(TInt aError, const TDesC8& aBuffer) = 0; sl@0: sl@0: /** sl@0: A callback function that is called when the input stream is closed using CMdaAudioInputStream::Stop(). sl@0: sl@0: This callback is usually 'paired' with a MaiscBufferCopied() that returns the last remaining audio data sl@0: in the FIFO between the last CMdaAudioInputStream::ReadL() and the Stop() command. sl@0: sl@0: @param aError sl@0: An error value indicating if the record was successful. KErrNone if the stop succeeded, otherwise one sl@0: of the system error codes. sl@0: */ sl@0: virtual void MaiscRecordComplete(TInt aError) = 0; sl@0: }; sl@0: sl@0: sl@0: class CMMFMdaAudioInputStream; sl@0: sl@0: /** sl@0: @publishedAll sl@0: @released sl@0: sl@0: The interface to an audio stream player passing raw audio data from the audio hardware to specified buffers. sl@0: sl@0: This class enables MMF clients to: sl@0: sl@0: Stream raw audio data from the audio hardware to specified buffers. sl@0: sl@0: Specify the priority of the audio stream in relation to other clients that may request to use the same audio hardware. sl@0: sl@0: Set the sample rate and the number of channels after successfully opening the stream. It is not possible to sl@0: change these values once streaming has started. sl@0: sl@0: Change the gain and balance before or while streaming is in progress. Gain and balance settings take effect immediately. sl@0: sl@0: sl@0: The API supports callbacks from the server to notify the client: sl@0: sl@0: MaiscOpenComplete() will be called when the audio streaming object is open and ready to stream data back to the sl@0: user as a result of a previous call to Open(). sl@0: sl@0: MaiscBufferCopied() will be called multiple times while the FIFO (queued via ReadL()) is emptied. sl@0: Note: Each buffer will be flagged with KErrAbort if received after Stop() on is called. MaiscRecordComplete is called sl@0: once all remaining buffers have been read. sl@0: sl@0: sl@0: MaiscRecordComplete() is called after Stop() has been called. aError - KErrAbort if MaiscRecordComplete called sl@0: as a result of a call to Stop(). sl@0: sl@0: Users of object CMdaAudioInputStream should ensure that implementation of the callback methods MaiscOpenComplete,MaiscBufferCopied sl@0: and MaiscRecordComplete in class MMdaAudioInputStreamCallback do not delete the object,otherwise a Kern-Exec 3 would occur during callback. sl@0: */ sl@0: class CMdaAudioInputStream : public CBase, sl@0: public MMMFClientUtility sl@0: { sl@0: public: sl@0: sl@0: /** sl@0: Instantiates a new audio input stream using default priority preferences. sl@0: sl@0: @param aCallBack sl@0: A callback to notify the client when the input stream has been initialised and is ready sl@0: for use, when data has been copied to a specified descriptor and when input streaming is sl@0: stopped. The caller must create a callback class that implements this interface. sl@0: sl@0: @return A pointer to the audio input stream object. sl@0: sl@0: @capability UserEnvironment sl@0: For recording - the requesting client process must have a sl@0: UserEnvironment capability. sl@0: */ sl@0: IMPORT_C static CMdaAudioInputStream* NewL(MMdaAudioInputStreamCallback& aCallBack); sl@0: sl@0: /** sl@0: Instantiates a new audio input stream. sl@0: sl@0: @param aCallBack sl@0: A callback to notify the client when the input stream has been initialised and is ready for sl@0: use. The caller must create a callback class which implements this interface. sl@0: @param aPriority sl@0: The Priority Value - this client's relative priority. This is a value between EMdaPriorityMin and sl@0: EMdaPriorityMax and represents a relative priority. A higher value indicates a more important request. sl@0: @param aPref sl@0: The Priority Preference - an additional audio policy parameter. The suggested default is sl@0: EMdaPriorityPreferenceNone. Further values are given by TMdaPriorityPreference, and additional sl@0: values may be supported by given phones and/or platforms, but should not be depended upon by sl@0: portable code. sl@0: sl@0: @return A pointer to the audio input stream object. sl@0: sl@0: @capability UserEnvironment sl@0: For recording - the requesting client process must have a sl@0: UserEnvironment capability. sl@0: sl@0: Note: The Priority Value and Priority Preference are used primarily when deciding what to do when sl@0: several audio clients attempt to play or record simultaneously. In addition to the Priority Value and Preference, sl@0: the adaptation may consider other parameters such as the SecureId and Capabilities of the client process. sl@0: Whatever, the decision as to what to do in such situations is up to the audio adaptation, and may sl@0: vary between different phones. Portable applications are advised not to assume any specific behaviour. sl@0: */ sl@0: IMPORT_C static CMdaAudioInputStream* NewL(MMdaAudioInputStreamCallback& aCallBack, sl@0: TInt aPriority, TInt aPref); sl@0: sl@0: /** sl@0: Destructor. sl@0: sl@0: Frees all resources owned by the object prior to its destruction. sl@0: */ sl@0: ~CMdaAudioInputStream(); sl@0: sl@0: /** sl@0: Sets the sample rate and number of audio channels. sl@0: sl@0: @param aSampleRate sl@0: The new sample rate. For possible values, see the TAudioCaps enum in class TMdaAudioDataSettings. sl@0: @param aChannels sl@0: The new number of channels. For possible values, see the TAudioCaps enum in class TMdaAudioDataSettings. sl@0: */ sl@0: IMPORT_C void SetAudioPropertiesL(TInt aSampleRate, TInt aChannels); sl@0: sl@0: /** sl@0: Opens an input audio stream package. sl@0: sl@0: The MMdaAudioInputStreamCallback::MaisOpenComplete() callback function is called when the stream has been sl@0: opened and is ready to record data. If the open was unsuccessful, this is indicated by the aError parameter sl@0: of the callback. sl@0: sl@0: @param aSettings sl@0: A pointer to an TMdaPackage object. sl@0: */ sl@0: IMPORT_C void Open(TMdaPackage* aSettings); sl@0: sl@0: /** sl@0: Sets the gain for the audio device to a specified value. sl@0: sl@0: @param aNewGain sl@0: The gain setting. This can be any value from zero to the value returned by a call to sl@0: MaxGain(). A value which is less than zero is set to zero. A value which is greater sl@0: than MaxGain() is set to MaxGain(). sl@0: */ sl@0: IMPORT_C void SetGain(TInt aNewGain); sl@0: sl@0: /** sl@0: Returns the current gain setting. sl@0: sl@0: @return The current gain setting. sl@0: */ sl@0: IMPORT_C TInt Gain() const; sl@0: sl@0: /** sl@0: Returns the maximum gain level. sl@0: sl@0: @return The maximum gain value that is supported by the sound device. sl@0: */ sl@0: IMPORT_C TInt MaxGain() const; sl@0: sl@0: /** sl@0: Sets the current audio balance. sl@0: sl@0: The balance can be any value between KMMFBalanceMaxLeft and KMMFBalanceMaxRight, the default value sl@0: being KMMFBalanceCenter. sl@0: sl@0: @param aBalance sl@0: A specified balance value. sl@0: */ sl@0: IMPORT_C void SetBalanceL(TInt aBalance = KMMFBalanceCenter); sl@0: sl@0: /** sl@0: Returns the current audio balance. sl@0: sl@0: @return The current balance value. sl@0: */ sl@0: IMPORT_C TInt GetBalanceL() const; sl@0: sl@0: /** sl@0: Sets the audio priority values. sl@0: sl@0: This function cannot be used while the stream object is open. It is intended for use before an Open() sl@0: is issued, or between a previous Stop() and a new Open(). sl@0: sl@0: @param aPriority sl@0: The Priority Value. sl@0: @param aPref sl@0: The Priority Preference. sl@0: sl@0: @see CMdaAudioInputStream::NewL() sl@0: */ sl@0: IMPORT_C void SetPriority(TInt aPriority, TInt aPref); sl@0: sl@0: /** sl@0: Records streaming raw audio data. sl@0: sl@0: If this is the first ReadL() after a successful Open() this function starts the audio recording process. sl@0: sl@0: The MMdaAudioInputStreamCallback::MaisBufferCopied() callback function is called when the buffer has been successfully sl@0: filled. A pointer to the newly filled buffer is returned in the callback. sl@0: sl@0: Note: The MMdaAudioInputStreamCallback::MaisBufferCopied() callback function is also called when a Stop() is issued, with a sl@0: pointer to the remaining recorded audio data and the aError parameter of the callback set to indicate recording has finished. sl@0: sl@0: @param aData sl@0: A reference to a buffer to be written into. sl@0: */ sl@0: IMPORT_C void ReadL(TDes8& aData); sl@0: sl@0: /** sl@0: Stops the recording process. sl@0: sl@0: The MMdaAudioInputStreamCallback::MaisRecordComplete() callback function is called when recording has been halted. Just prior sl@0: to issuing this callback, the FIFO buffers are read and the remaining audio data passed back by a final sl@0: MMdaAudioInputStreamCallback::MaisBufferCopied() callback with its aError parameter set to KErrAbort. sl@0: sl@0: Any remaining FIFO buffers are also passed back, with their aError parameter set to KErrAbort. sl@0: sl@0: Stop is immediate and best used for premature stops, for example within destructors. sl@0: If it is critical to receive all data buffers upto the point that Recording has Stopped, sl@0: we recommend using RequestStop instead. Otherwise some trailing buffers may be lost from the recording process. sl@0: sl@0: If a Stop is issued after a RequestStop, Stop will take precedent. sl@0: sl@0: @see CMdaAudioInputStream::RequestStop() sl@0: */ sl@0: IMPORT_C void Stop(); sl@0: sl@0: /** sl@0: Returns the current position within the data stream in microseconds since the start of streaming. sl@0: sl@0: @return The current position. sl@0: */ sl@0: IMPORT_C const TTimeIntervalMicroSeconds& Position(); sl@0: sl@0: /** sl@0: Returns the current number of bytes rendered by audio hardware. sl@0: sl@0: @return The number of bytes. sl@0: */ sl@0: IMPORT_C TInt GetBytes(); sl@0: sl@0: sl@0: /** sl@0: Sets the data type. If the data type is not explicitly set it will assumed to be pcm16. sl@0: If it is set then the hardware must support the data type being set otherwise the sl@0: function leaves with KErrNotSupported. sl@0: sl@0: @param aAudioType The fourCC code used to request the data type of the recorded data. sl@0: sl@0: @leave KErrNotSupported sl@0: Leaves with this for any unsuported data type. sl@0: */ sl@0: IMPORT_C void SetDataTypeL(TFourCC aAudioType); sl@0: sl@0: /** sl@0: Returns the current data type. sl@0: sl@0: @return The ID of the data type. sl@0: */ sl@0: IMPORT_C TFourCC DataType() const; sl@0: sl@0: /** sl@0: Returns the bit rates supported by the sound device sl@0: sl@0: @param aSupportedBitRates sl@0: @leave KErrNotSupported sl@0: If the sound device does not support setting the bit rate sl@0: The supported bit rates, in bits per second, shall be appended to this array. Note that sl@0: the array shall be reset by this method. sl@0: */ sl@0: IMPORT_C void GetSupportedBitRatesL(RArray& aSupportedBitRates); sl@0: /** sl@0: Returns the current bit rate. sl@0: @return The current bit rate, in bits per second. sl@0: @leave KErrNotSupported sl@0: If the sound device does not support returning the current bit rate sl@0: */ sl@0: IMPORT_C TInt BitRateL() const; sl@0: /** sl@0: Sets the bit rate to a new value. sl@0: @param aBitRate sl@0: The new bit rate, in bits per second. sl@0: @leave KErrNotSupported sl@0: If the sound device does not support returning the current bit rate or the bit rate set is not supported sl@0: */ sl@0: IMPORT_C void SetBitRateL(TInt aBitRate); sl@0: sl@0: /** sl@0: Retrieves a custom interface to the underlying device. sl@0: sl@0: @param aInterfaceId sl@0: The interface UID, defined with the custom interface. sl@0: sl@0: @return A pointer to the interface implementation, or NULL if the device does not sl@0: implement the interface requested. The return value must be cast to the sl@0: correct type by the user. sl@0: */ sl@0: IMPORT_C TAny* CustomInterface(TUid aInterfaceId); sl@0: sl@0: /** sl@0: Indicates that the client wishes to use a single buffer to collect the data. sl@0: This buffer is passed via the ReadL api. sl@0: sl@0: @param aSingleMode sl@0: ETrue to indicate setting of single buffer mode and the use of a single sl@0: buffer, EFalse to indicate use of multiple buffers. sl@0: */ sl@0: IMPORT_C void SetSingleBufferMode(TBool aSingleMode); sl@0: sl@0: /** sl@0: Requests a Stop of the recording process. sl@0: sl@0: The device is requested to Stop and does so after all unprocessed buffers are processed and passed sl@0: back to the input stream. The device is actually Stopped when the final empty buffer indicating sl@0: buffer process completion is received. sl@0: sl@0: @see CMdaAudioInputStream::Stop() sl@0: */ sl@0: IMPORT_C void RequestStop(); sl@0: sl@0: private: sl@0: CMdaAudioInputStream(); sl@0: private: sl@0: CMMFMdaAudioInputStream* iProperties; sl@0: }; sl@0: sl@0: #endif