1 // Copyright (c) 2002-2009 Nokia Corporation and/or its subsidiary(-ies).
2 // All rights reserved.
3 // This component and the accompanying materials are made available
4 // under the terms of "Eclipse Public License v1.0"
5 // which accompanies this distribution, and is available
6 // at the URL "http://www.eclipse.org/legal/epl-v10.html".
8 // Initial Contributors:
9 // Nokia Corporation - initial contribution.
16 #ifndef __MDAAUDIOOUTPUTSTREAM_H
17 #define __MDAAUDIOOUTPUTSTREAM_H
21 #include <mmf/common/mmfbase.h>
22 #include <mmf/common/mmfstandardcustomcommands.h>
23 #include <mda/common/base.h>
24 #include <mda/client/utility.h>
25 #include <mmf/common/mmfaudio.h>
26 #include <mmfclntutility.h>
33 An interface class that notifies the client of the progress of audio output streaming.
35 It must be implemented by users of the CMdaAudioOutputStream class.
37 An object that implements this interface is passed to CMdaAudioOutputStream::NewL().
39 class MMdaAudioOutputStreamCallback
44 A callback function that is called when CMdaAudioOutputStream::Open() has completed, indicating that the
45 audio output stream is ready for use.
48 An error value which indicates if open was completed successfully. KErrNone if succeeded.
50 virtual void MaoscOpenComplete(TInt aError) = 0;
53 A callback function that is called when a descriptor has been copied to the lower layers of MMF.
55 It is also called when an error has occurred or when the client has stopped the stream playing before the descriptor
56 has been fully copied (by calling CMdaAudioOutputStream::Stop()).
58 This function indicates to the client that it is safe to destroy the buffer passed to CMdaAudioOutputStream::WriteL().
59 It can also be used to make the next call to WriteL().
62 KErrNone if the copy succeeded, otherwise one of the system error codes. KErrAbort indicates that
63 the client has stopped the stream playing before the descriptor has been copied.
65 A reference to the buffer that has been copied.
67 virtual void MaoscBufferCopied(TInt aError, const TDesC8& aBuffer) = 0;
70 A callback function that is called when playback terminates as a result of a CMdaAudioOutputStream::Stop().
72 If the end of the sound data has been reached, the function returns KErrUnderFlow. If playback terminates for any
73 other reason, the function returns an appropriate error value.
76 An error value which indicates play success or not. KErrNone if the close succeeded, otherwise one of the
79 virtual void MaoscPlayComplete(TInt aError) = 0;
83 class CMMFMdaAudioOutputStream;
89 The interface to an audio stream player passing raw audio data from specified buffers to the audio hardware.
91 This class enables MMF clients to:
93 Stream raw audio data to the audio hardware from specified buffers
95 Specify the priority of the audio stream in relation to other clients that may request to use the same audio hardware
97 Set the sample rate and the number of channels after successfully opening the stream. It is not possible to change these
98 values once streaming has started.
100 Change the volume and balance before or while the stream is open for writing. Volume and balance settings take effect immediately.
102 The API supports callbacks from the server to notify the client:
104 MaoscOpenComplete() will be called when the audio streaming object is open and ready to stream data back to the
105 audio hardware as a result of a previous call to Open().
107 MaoscBufferCopied() will be called each time audio data has been successfully copied to the lower layers of the
108 MMF as a result of a previous WriteL().
110 MaoscPlayComplete() will be called when the audio data stream has been closed as a result of a previous Stop().
112 class CMdaAudioOutputStream : public CBase,
113 public MMMFClientUtility
118 Allocates and constructs an audio stream player object.
121 A callback to notify the client when the sound device is open and ready to receive data, when
122 each descriptor has been copied and when the stream is closed. The caller must create a
123 callback class which implements this interface.
125 A pointer to a CMdaServer. CMdaServer is deprecated and as such this parameter is only provided
126 for backward compatibility.
128 @return A pointer to new audio stream player.
130 IMPORT_C static CMdaAudioOutputStream* NewL(MMdaAudioOutputStreamCallback& aCallBack,
131 CMdaServer* aServer = NULL);
134 Constructs and initialises a new instance of an audio streaming object.
136 The function leaves if the audio streaming object cannot be created.
139 A callback to notify the client when the sound device is open and ready to receive data, when each
140 descriptor has been copied and when the stream is closed. The caller must create a callback class
141 which implements this interface.
143 The Priority Value - this client's relative priority. This is a value between EMdaPriorityMin and
144 EMdaPriorityMax and represents a relative priority. A higher value indicates a more important request.
146 The Priority Preference - an additional audio policy parameter. The suggested default is
147 EMdaPriorityPreferenceNone. Further values are given by TMdaPriorityPreference, and additional
148 values may be supported by given phones and/or platforms, but should not be depended upon by
151 @return A pointer to CMdaAudioOutputStream.
153 Note: The Priority Value and Priority Preference are used primarily when deciding what to do when
154 several audio clients attempt to play or record simultaneously. In addition to the Priority Value and Preference,
155 the adaptation may consider other parameters such as the SecureId and Capabilities of the client process.
156 Whatever, the decision as to what to do in such situations is up to the audio adaptation, and may
157 vary between different phones. Portable applications are advised not to assume any specific behaviour.
159 IMPORT_C static CMdaAudioOutputStream* NewL(MMdaAudioOutputStreamCallback& aCallBack,
161 TInt aPref = EMdaPriorityPreferenceTimeAndQuality);
167 Frees all resources owned by the object prior to its destruction.
169 ~CMdaAudioOutputStream();
172 Sets the sample rate and number of audio channels.
175 The new sample rate. For possible values, see the TAudioCaps enum in class TMdaAudioDataSettings.
177 The new number of channels. For possible values, see the TAudioCaps enum in class TMdaAudioDataSettings.
180 virtual void SetAudioPropertiesL(TInt aSampleRate, TInt aChannels);
183 Opens an output audio stream package.
185 The MMdaAudioOutputStreamCallback::MaoscOpenComplete() callback function is called when the stream has been
186 opened and is ready to receive audio data. If the open was unsuccessful, this is indicated by the aError
187 parameter of the callback.
191 A pointer to a TMdaPackage object.
194 virtual void Open(TMdaPackage* aSettings);
197 Returns the maximum volume level.
199 @return The maximum volume level supported by the sound device, as an integer.
201 virtual TInt MaxVolume();
204 Returns the current volume.
206 @return The current volume as an integer.
208 virtual TInt Volume();
211 Sets the audio volume.
213 Set the volume to zero for "sound off" or any other value between 1 and MaxVolume().
216 A specified audio volume.
219 virtual void SetVolume(const TInt aNewVolume);
222 Sets the audio priority values.
224 This function cannot be used while the stream object is open. It is intended for use before an Open()
225 is issued, or between a previous Stop() and a new Open().
230 The Priority Preference.
232 @see CMdaAudioOutputStream::NewL()
234 virtual void SetPriority(TInt aPriority, TInt aPref);
237 Writes (plays) streaming raw audio data.
239 This function is asynchronous. When aData has been received, the client is notified by a call to
240 MMdaAudioOutputStreamCallback::MaoscBufferCopied(). The client can call WriteL() again before this notification
241 takes place because the buffers are maintained in a client-side queue until they have been sent. An active object
242 performs the notification, and copies the next item in the queue to the server.
243 MMdaAudioOutputStreamCallback::MaoscPlayComplete() is called when all descriptors have been sent.
246 A reference to the stream data.
249 virtual void WriteL(const TDesC8& aData);
252 Stops writing data to a stream.
258 Pause data rendering by audio hardware.
259 @return An error code indicating if the operation was successful. KErrNone on success,
260 KErrNotReady if not streaming
261 KErrNotSupported if trying to pause when resume is not supported by DevSound
264 IMPORT_C TInt Pause();
268 Resume data rendering by audio hardware.
269 @return An error code indicating if the operation was successful. KErrNone on success,
270 KErrNotReady if not paused.
271 KErrNotSupported if trying to resume when resume is not supported by DevSound
273 IMPORT_C TInt Resume();
277 Returns the current position within the data stream.
279 @return The current position within the stream in microseconds.
281 virtual const TTimeIntervalMicroSeconds& Position();
284 Sets the audio balance.
287 A specified balance volume. Default is KMMFBalanceCenter.
290 IMPORT_C void SetBalanceL(TInt aBalance = KMMFBalanceCenter);
293 Returns the current balance as an integer.
295 @return The current balance value as integer.
297 IMPORT_C TInt GetBalanceL() const;
300 Returns the current number of bytes rendered by audio hardware.
302 @return The current current number of bytes rendered by audio hardware as an integer.
304 IMPORT_C TInt GetBytes();
307 Sets the data type. If the data type is not explicitly set it will assumed to be pcm16.
308 If it is set then the hardware must support the data type being set otherwise the
309 function leaves with KErrNotSupported.
311 @param aAudioType The fourCC code used to specify the data type of the streamed audio
313 @leave KErrNotSupported
314 Leaves with this for any unsuported data type.
316 IMPORT_C void SetDataTypeL(TFourCC aAudioType);
319 Returns the current data type.
321 @return The ID of the data type.
323 IMPORT_C TFourCC DataType() const;
326 Registers the Event for Notification when resource is avaliable.
328 The audio outputstream observer interface..
329 @param aNotificationEventUid
330 The Event for which the client is registered.
331 @param aNotificationRegistrationData
332 Notification registration specific data.
333 @return An error code indicating if the registration was successful. KErrNone on success,
334 otherwise another of the system-wide error codes.
336 IMPORT_C TInt RegisterAudioResourceNotification(MMMFAudioResourceNotificationCallback& aCallback,TUid aNotificationEventUid,const TDesC8& aNotificationRegistrationData = KNullDesC8);
339 Cancels the registered notification event.
340 @param aNotificationEventUid
341 The Event to notify the client.
343 @return An error code indicating if the registration was successful. KErrNone on success,
344 otherwise another of the system-wide error codes.
346 IMPORT_C TInt CancelRegisterAudioResourceNotification(TUid aNotificationEventId);
349 Waits for the client to resume the play even after the default timer expires.
350 @return An error code indicating if the registration was successful. KErrNone on success,
351 otherwise another of the system-wide error codes.
353 IMPORT_C TInt WillResumePlay();
356 Retrieves a custom interface to the underlying device.
359 The interface UID, defined with the custom interface.
361 @return A pointer to the interface implementation, or NULL if the device does not
362 implement the interface requested. The return value must be cast to the
363 correct type by the user.
365 IMPORT_C TAny* CustomInterface(TUid aInterfaceId);
368 When this method is called, AudioOutputStream goes into a different mode wherein it does not call
369 MaoscPlayComplete() with KErrUnderflow when all the supplied data has been played. Instead client
370 should signal the end of the play by calling RequestStop() or Stop() on AudioOutputStream.
371 If the client calls RequestStop(), AudioOutputStream waits until all the queued data has been played out
372 and then calls MaoscPlayComplete(). This behaviour is different from that of Stop(), which stops the play
373 immediately by discarding all the queued data.
375 Client should call this method on CMdaAudioOutputStream just after its construction and its
376 effect remains through out its lifetime.
378 Note: This feature is supported only on a DevSound which ignores the underflow errors in the middle of
379 the play i.e which returns ETrue from QueryIgnoresUnderflow().
381 @return KErrNone on success,
382 KErrNotSupported if the underlying DevSound does not ignore the underflow errors in the middle of the play
384 @see CMdaAudioOutputStream::RequestStop()
385 @see CMMFDevSound::QueryIgnoresUnderflow()
387 IMPORT_C TInt KeepOpenAtEnd();
390 This method signals the end of play when the AudioOutputStream is in KeepOpenAtEnd mode i.e when client
391 makes KeepOpenAtEnd call on it. When RequestStop is called, AudioOutputStream completes playing all
392 the data that is supplied to it and calls MaoscPlayComplete() with KErrUnderflow.
394 Note: Before calling this method, client must have already called KeepOpenAtEnd() successfully, Otherwise, this
395 method returns KErrNotSupported.
396 It is recommended to use KeepOpenAtEnd and RequestStop calls to get a predictable behaviour during stopping.
398 @return KErrNone on success
399 KErrNotSupported when this method is called without calling KeepOpenAtEnd
400 KErrNotReady when this method is called before completing previous RequestStop or AudioOutputStream
401 is already in the stopped state
403 @see CMdaAudioOutputStream::KeepOpenAtEnd()
405 IMPORT_C TInt RequestStop();
408 CMdaAudioOutputStream();
411 This member is internal and not intended for use.
413 CMMFMdaAudioOutputStream* iProperties;