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: #ifndef __MDAAUDIOOUTPUTSTREAM_H sl@0: #define __MDAAUDIOOUTPUTSTREAM_H sl@0: sl@0: sl@0: #include sl@0: #include 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 audio output streaming. sl@0: sl@0: It must be implemented by users of the CMdaAudioOutputStream class. sl@0: sl@0: An object that implements this interface is passed to CMdaAudioOutputStream::NewL(). sl@0: */ sl@0: class MMdaAudioOutputStreamCallback sl@0: { sl@0: public: sl@0: sl@0: /** sl@0: A callback function that is called when CMdaAudioOutputStream::Open() has completed, indicating that the sl@0: audio output stream is ready for use. sl@0: sl@0: @param aError sl@0: An error value which indicates if open was completed successfully. KErrNone if succeeded. sl@0: */ sl@0: virtual void MaoscOpenComplete(TInt aError) = 0; sl@0: sl@0: /** sl@0: A callback function that is called when a descriptor has been copied to the lower layers of MMF. sl@0: sl@0: It is also called when an error has occurred or when the client has stopped the stream playing before the descriptor sl@0: has been fully copied (by calling CMdaAudioOutputStream::Stop()). sl@0: sl@0: This function indicates to the client that it is safe to destroy the buffer passed to CMdaAudioOutputStream::WriteL(). sl@0: It can also be used to make the next call to WriteL(). sl@0: sl@0: @param aError sl@0: KErrNone if the copy succeeded, otherwise one of the system error codes. KErrAbort indicates that sl@0: the client has stopped the stream playing before the descriptor has been copied. sl@0: @param aBuffer sl@0: A reference to the buffer that has been copied. sl@0: */ sl@0: virtual void MaoscBufferCopied(TInt aError, const TDesC8& aBuffer) = 0; sl@0: sl@0: /** sl@0: A callback function that is called when playback terminates as a result of a CMdaAudioOutputStream::Stop(). sl@0: sl@0: If the end of the sound data has been reached, the function returns KErrUnderFlow. If playback terminates for any sl@0: other reason, the function returns an appropriate error value. sl@0: sl@0: @param aError sl@0: An error value which indicates play success or not. KErrNone if the close succeeded, otherwise one of the sl@0: system error codes. sl@0: */ sl@0: virtual void MaoscPlayComplete(TInt aError) = 0; sl@0: }; sl@0: sl@0: sl@0: class CMMFMdaAudioOutputStream; 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 specified buffers to the audio hardware. sl@0: sl@0: This class enables MMF clients to: sl@0: sl@0: Stream raw audio data to the audio hardware from 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 change these sl@0: values once streaming has started. sl@0: sl@0: Change the volume and balance before or while the stream is open for writing. Volume and balance settings take effect immediately. sl@0: sl@0: The API supports callbacks from the server to notify the client: sl@0: sl@0: MaoscOpenComplete() will be called when the audio streaming object is open and ready to stream data back to the sl@0: audio hardware as a result of a previous call to Open(). sl@0: sl@0: MaoscBufferCopied() will be called each time audio data has been successfully copied to the lower layers of the sl@0: MMF as a result of a previous WriteL(). sl@0: sl@0: MaoscPlayComplete() will be called when the audio data stream has been closed as a result of a previous Stop(). sl@0: */ sl@0: class CMdaAudioOutputStream : public CBase, sl@0: public MMMFClientUtility sl@0: { sl@0: public: sl@0: sl@0: /** sl@0: Allocates and constructs an audio stream player object. sl@0: sl@0: @param aCallBack sl@0: A callback to notify the client when the sound device is open and ready to receive data, when sl@0: each descriptor has been copied and when the stream is closed. The caller must create a sl@0: callback class which implements this interface. sl@0: @param aServer sl@0: A pointer to a CMdaServer. CMdaServer is deprecated and as such this parameter is only provided sl@0: for backward compatibility. sl@0: sl@0: @return A pointer to new audio stream player. sl@0: */ sl@0: IMPORT_C static CMdaAudioOutputStream* NewL(MMdaAudioOutputStreamCallback& aCallBack, sl@0: CMdaServer* aServer = NULL); sl@0: sl@0: /** sl@0: Constructs and initialises a new instance of an audio streaming object. sl@0: sl@0: The function leaves if the audio streaming object cannot be created. sl@0: sl@0: @param aCallBack sl@0: A callback to notify the client when the sound device is open and ready to receive data, when each sl@0: descriptor has been copied and when the stream is closed. The caller must create a callback class sl@0: 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 CMdaAudioOutputStream. 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 CMdaAudioOutputStream* NewL(MMdaAudioOutputStreamCallback& aCallBack, sl@0: TInt aPriority, sl@0: TInt aPref = EMdaPriorityPreferenceTimeAndQuality); sl@0: 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: ~CMdaAudioOutputStream(); 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: */ sl@0: virtual void SetAudioPropertiesL(TInt aSampleRate, TInt aChannels); sl@0: sl@0: /** sl@0: Opens an output audio stream package. sl@0: sl@0: The MMdaAudioOutputStreamCallback::MaoscOpenComplete() callback function is called when the stream has been sl@0: opened and is ready to receive audio data. If the open was unsuccessful, this is indicated by the aError sl@0: parameter of the callback. sl@0: sl@0: sl@0: @param aSettings sl@0: A pointer to a TMdaPackage object. sl@0: sl@0: */ sl@0: virtual void Open(TMdaPackage* aSettings); sl@0: sl@0: /** sl@0: Returns the maximum volume level. sl@0: sl@0: @return The maximum volume level supported by the sound device, as an integer. sl@0: */ sl@0: virtual TInt MaxVolume(); sl@0: sl@0: /** sl@0: Returns the current volume. sl@0: sl@0: @return The current volume as an integer. sl@0: */ sl@0: virtual TInt Volume(); sl@0: sl@0: /** sl@0: Sets the audio volume. sl@0: sl@0: Set the volume to zero for "sound off" or any other value between 1 and MaxVolume(). sl@0: sl@0: @param aNewVolume sl@0: A specified audio volume. sl@0: sl@0: */ sl@0: virtual void SetVolume(const TInt aNewVolume); 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 CMdaAudioOutputStream::NewL() sl@0: */ sl@0: virtual void SetPriority(TInt aPriority, TInt aPref); sl@0: sl@0: /** sl@0: Writes (plays) streaming raw audio data. sl@0: sl@0: This function is asynchronous. When aData has been received, the client is notified by a call to sl@0: MMdaAudioOutputStreamCallback::MaoscBufferCopied(). The client can call WriteL() again before this notification sl@0: takes place because the buffers are maintained in a client-side queue until they have been sent. An active object sl@0: performs the notification, and copies the next item in the queue to the server. sl@0: MMdaAudioOutputStreamCallback::MaoscPlayComplete() is called when all descriptors have been sent. sl@0: sl@0: @param aData sl@0: A reference to the stream data. sl@0: sl@0: */ sl@0: virtual void WriteL(const TDesC8& aData); sl@0: sl@0: /** sl@0: Stops writing data to a stream. sl@0: sl@0: */ sl@0: virtual void Stop(); sl@0: sl@0: /** sl@0: Pause data rendering by audio hardware. sl@0: @return An error code indicating if the operation was successful. KErrNone on success, sl@0: KErrNotReady if not streaming sl@0: KErrNotSupported if trying to pause when resume is not supported by DevSound sl@0: */ sl@0: sl@0: IMPORT_C TInt Pause(); sl@0: sl@0: sl@0: /** sl@0: Resume data rendering by audio hardware. sl@0: @return An error code indicating if the operation was successful. KErrNone on success, sl@0: KErrNotReady if not paused. sl@0: KErrNotSupported if trying to resume when resume is not supported by DevSound sl@0: */ sl@0: IMPORT_C TInt Resume(); sl@0: sl@0: sl@0: /** sl@0: Returns the current position within the data stream. sl@0: sl@0: @return The current position within the stream in microseconds. sl@0: */ sl@0: virtual const TTimeIntervalMicroSeconds& Position(); sl@0: sl@0: /** sl@0: Sets the audio balance. sl@0: sl@0: @param aBalance sl@0: A specified balance volume. Default is KMMFBalanceCenter. sl@0: sl@0: */ sl@0: IMPORT_C void SetBalanceL(TInt aBalance = KMMFBalanceCenter); sl@0: sl@0: /** sl@0: Returns the current balance as an integer. sl@0: sl@0: @return The current balance value as integer. sl@0: */ sl@0: IMPORT_C TInt GetBalanceL() const; sl@0: sl@0: /** sl@0: Returns the current number of bytes rendered by audio hardware. sl@0: sl@0: @return The current current number of bytes rendered by audio hardware as an integer. sl@0: */ sl@0: IMPORT_C TInt GetBytes(); 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 specify the data type of the streamed audio 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: Registers the Event for Notification when resource is avaliable. sl@0: @param aCallback sl@0: The audio outputstream observer interface.. sl@0: @param aNotificationEventUid sl@0: The Event for which the client is registered. sl@0: @param aNotificationRegistrationData sl@0: Notification registration specific data. sl@0: @return An error code indicating if the registration was successful. KErrNone on success, sl@0: otherwise another of the system-wide error codes. sl@0: */ sl@0: IMPORT_C TInt RegisterAudioResourceNotification(MMMFAudioResourceNotificationCallback& aCallback,TUid aNotificationEventUid,const TDesC8& aNotificationRegistrationData = KNullDesC8); sl@0: sl@0: /** sl@0: Cancels the registered notification event. sl@0: @param aNotificationEventUid sl@0: The Event to notify the client. sl@0: sl@0: @return An error code indicating if the registration was successful. KErrNone on success, sl@0: otherwise another of the system-wide error codes. sl@0: */ sl@0: IMPORT_C TInt CancelRegisterAudioResourceNotification(TUid aNotificationEventId); sl@0: sl@0: /** sl@0: Waits for the client to resume the play even after the default timer expires. sl@0: @return An error code indicating if the registration was successful. KErrNone on success, sl@0: otherwise another of the system-wide error codes. sl@0: */ sl@0: IMPORT_C TInt WillResumePlay(); 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: When this method is called, AudioOutputStream goes into a different mode wherein it does not call sl@0: MaoscPlayComplete() with KErrUnderflow when all the supplied data has been played. Instead client sl@0: should signal the end of the play by calling RequestStop() or Stop() on AudioOutputStream. sl@0: If the client calls RequestStop(), AudioOutputStream waits until all the queued data has been played out sl@0: and then calls MaoscPlayComplete(). This behaviour is different from that of Stop(), which stops the play sl@0: immediately by discarding all the queued data. sl@0: sl@0: Client should call this method on CMdaAudioOutputStream just after its construction and its sl@0: effect remains through out its lifetime. sl@0: sl@0: Note: This feature is supported only on a DevSound which ignores the underflow errors in the middle of sl@0: the play i.e which returns ETrue from QueryIgnoresUnderflow(). sl@0: sl@0: @return KErrNone on success, sl@0: KErrNotSupported if the underlying DevSound does not ignore the underflow errors in the middle of the play sl@0: sl@0: @see CMdaAudioOutputStream::RequestStop() sl@0: @see CMMFDevSound::QueryIgnoresUnderflow() sl@0: */ sl@0: IMPORT_C TInt KeepOpenAtEnd(); sl@0: sl@0: /** sl@0: This method signals the end of play when the AudioOutputStream is in KeepOpenAtEnd mode i.e when client sl@0: makes KeepOpenAtEnd call on it. When RequestStop is called, AudioOutputStream completes playing all sl@0: the data that is supplied to it and calls MaoscPlayComplete() with KErrUnderflow. sl@0: sl@0: Note: Before calling this method, client must have already called KeepOpenAtEnd() successfully, Otherwise, this sl@0: method returns KErrNotSupported. sl@0: It is recommended to use KeepOpenAtEnd and RequestStop calls to get a predictable behaviour during stopping. sl@0: sl@0: @return KErrNone on success sl@0: KErrNotSupported when this method is called without calling KeepOpenAtEnd sl@0: KErrNotReady when this method is called before completing previous RequestStop or AudioOutputStream sl@0: is already in the stopped state sl@0: sl@0: @see CMdaAudioOutputStream::KeepOpenAtEnd() sl@0: */ sl@0: IMPORT_C TInt RequestStop(); sl@0: sl@0: private: sl@0: CMdaAudioOutputStream(); sl@0: private: sl@0: /** sl@0: This member is internal and not intended for use. sl@0: */ sl@0: CMMFMdaAudioOutputStream* iProperties; sl@0: }; sl@0: sl@0: #endif