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