1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/mm/mmlibs/mmfw/inc/MdaAudioOutputStream.h Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,416 @@
1.4 +// Copyright (c) 2002-2009 Nokia Corporation and/or its subsidiary(-ies).
1.5 +// All rights reserved.
1.6 +// This component and the accompanying materials are made available
1.7 +// under the terms of "Eclipse Public License v1.0"
1.8 +// which accompanies this distribution, and is available
1.9 +// at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.10 +//
1.11 +// Initial Contributors:
1.12 +// Nokia Corporation - initial contribution.
1.13 +//
1.14 +// Contributors:
1.15 +//
1.16 +// Description:
1.17 +//
1.18 +
1.19 +#ifndef __MDAAUDIOOUTPUTSTREAM_H
1.20 +#define __MDAAUDIOOUTPUTSTREAM_H
1.21 +
1.22 +
1.23 +#include <e32std.h>
1.24 +#include <mmf/common/mmfbase.h>
1.25 +#include <mmf/common/mmfstandardcustomcommands.h>
1.26 +#include <mda/common/base.h>
1.27 +#include <mda/client/utility.h>
1.28 +#include <mmf/common/mmfaudio.h>
1.29 +#include <mmfclntutility.h>
1.30 +
1.31 +
1.32 +/**
1.33 +@publishedAll
1.34 +@released
1.35 +
1.36 +An interface class that notifies the client of the progress of audio output streaming.
1.37 +
1.38 +It must be implemented by users of the CMdaAudioOutputStream class.
1.39 +
1.40 +An object that implements this interface is passed to CMdaAudioOutputStream::NewL().
1.41 +*/
1.42 +class MMdaAudioOutputStreamCallback
1.43 + {
1.44 +public:
1.45 +
1.46 + /**
1.47 + A callback function that is called when CMdaAudioOutputStream::Open() has completed, indicating that the
1.48 + audio output stream is ready for use.
1.49 +
1.50 + @param aError
1.51 + An error value which indicates if open was completed successfully. KErrNone if succeeded.
1.52 + */
1.53 + virtual void MaoscOpenComplete(TInt aError) = 0;
1.54 +
1.55 + /**
1.56 + A callback function that is called when a descriptor has been copied to the lower layers of MMF.
1.57 +
1.58 + It is also called when an error has occurred or when the client has stopped the stream playing before the descriptor
1.59 + has been fully copied (by calling CMdaAudioOutputStream::Stop()).
1.60 +
1.61 + This function indicates to the client that it is safe to destroy the buffer passed to CMdaAudioOutputStream::WriteL().
1.62 + It can also be used to make the next call to WriteL().
1.63 +
1.64 + @param aError
1.65 + KErrNone if the copy succeeded, otherwise one of the system error codes. KErrAbort indicates that
1.66 + the client has stopped the stream playing before the descriptor has been copied.
1.67 + @param aBuffer
1.68 + A reference to the buffer that has been copied.
1.69 + */
1.70 + virtual void MaoscBufferCopied(TInt aError, const TDesC8& aBuffer) = 0;
1.71 +
1.72 + /**
1.73 + A callback function that is called when playback terminates as a result of a CMdaAudioOutputStream::Stop().
1.74 +
1.75 + If the end of the sound data has been reached, the function returns KErrUnderFlow. If playback terminates for any
1.76 + other reason, the function returns an appropriate error value.
1.77 +
1.78 + @param aError
1.79 + An error value which indicates play success or not. KErrNone if the close succeeded, otherwise one of the
1.80 + system error codes.
1.81 + */
1.82 + virtual void MaoscPlayComplete(TInt aError) = 0;
1.83 + };
1.84 +
1.85 +
1.86 +class CMMFMdaAudioOutputStream;
1.87 +
1.88 +/**
1.89 +@publishedAll
1.90 +@released
1.91 +
1.92 +The interface to an audio stream player passing raw audio data from specified buffers to the audio hardware.
1.93 +
1.94 +This class enables MMF clients to:
1.95 +
1.96 +Stream raw audio data to the audio hardware from specified buffers
1.97 +
1.98 +Specify the priority of the audio stream in relation to other clients that may request to use the same audio hardware
1.99 +
1.100 +Set the sample rate and the number of channels after successfully opening the stream. It is not possible to change these
1.101 +values once streaming has started.
1.102 +
1.103 +Change the volume and balance before or while the stream is open for writing. Volume and balance settings take effect immediately.
1.104 +
1.105 +The API supports callbacks from the server to notify the client:
1.106 +
1.107 +MaoscOpenComplete() will be called when the audio streaming object is open and ready to stream data back to the
1.108 +audio hardware as a result of a previous call to Open().
1.109 +
1.110 +MaoscBufferCopied() will be called each time audio data has been successfully copied to the lower layers of the
1.111 +MMF as a result of a previous WriteL().
1.112 +
1.113 +MaoscPlayComplete() will be called when the audio data stream has been closed as a result of a previous Stop().
1.114 +*/
1.115 +class CMdaAudioOutputStream : public CBase,
1.116 + public MMMFClientUtility
1.117 + {
1.118 +public:
1.119 +
1.120 + /**
1.121 + Allocates and constructs an audio stream player object.
1.122 +
1.123 + @param aCallBack
1.124 + A callback to notify the client when the sound device is open and ready to receive data, when
1.125 + each descriptor has been copied and when the stream is closed. The caller must create a
1.126 + callback class which implements this interface.
1.127 + @param aServer
1.128 + A pointer to a CMdaServer. CMdaServer is deprecated and as such this parameter is only provided
1.129 + for backward compatibility.
1.130 +
1.131 + @return A pointer to new audio stream player.
1.132 + */
1.133 + IMPORT_C static CMdaAudioOutputStream* NewL(MMdaAudioOutputStreamCallback& aCallBack,
1.134 + CMdaServer* aServer = NULL);
1.135 +
1.136 + /**
1.137 + Constructs and initialises a new instance of an audio streaming object.
1.138 +
1.139 + The function leaves if the audio streaming object cannot be created.
1.140 +
1.141 + @param aCallBack
1.142 + A callback to notify the client when the sound device is open and ready to receive data, when each
1.143 + descriptor has been copied and when the stream is closed. The caller must create a callback class
1.144 + which implements this interface.
1.145 + @param aPriority
1.146 + The Priority Value - this client's relative priority. This is a value between EMdaPriorityMin and
1.147 + EMdaPriorityMax and represents a relative priority. A higher value indicates a more important request.
1.148 + @param aPref
1.149 + The Priority Preference - an additional audio policy parameter. The suggested default is
1.150 + EMdaPriorityPreferenceNone. Further values are given by TMdaPriorityPreference, and additional
1.151 + values may be supported by given phones and/or platforms, but should not be depended upon by
1.152 + portable code.
1.153 +
1.154 + @return A pointer to CMdaAudioOutputStream.
1.155 +
1.156 + Note: The Priority Value and Priority Preference are used primarily when deciding what to do when
1.157 + several audio clients attempt to play or record simultaneously. In addition to the Priority Value and Preference,
1.158 + the adaptation may consider other parameters such as the SecureId and Capabilities of the client process.
1.159 + Whatever, the decision as to what to do in such situations is up to the audio adaptation, and may
1.160 + vary between different phones. Portable applications are advised not to assume any specific behaviour.
1.161 + */
1.162 + IMPORT_C static CMdaAudioOutputStream* NewL(MMdaAudioOutputStreamCallback& aCallBack,
1.163 + TInt aPriority,
1.164 + TInt aPref = EMdaPriorityPreferenceTimeAndQuality);
1.165 +
1.166 +
1.167 + /**
1.168 + Destructor.
1.169 +
1.170 + Frees all resources owned by the object prior to its destruction.
1.171 + */
1.172 + ~CMdaAudioOutputStream();
1.173 +
1.174 + /**
1.175 + Sets the sample rate and number of audio channels.
1.176 +
1.177 + @param aSampleRate
1.178 + The new sample rate. For possible values, see the TAudioCaps enum in class TMdaAudioDataSettings.
1.179 + @param aChannels
1.180 + The new number of channels. For possible values, see the TAudioCaps enum in class TMdaAudioDataSettings.
1.181 +
1.182 + */
1.183 + virtual void SetAudioPropertiesL(TInt aSampleRate, TInt aChannels);
1.184 +
1.185 + /**
1.186 + Opens an output audio stream package.
1.187 +
1.188 + The MMdaAudioOutputStreamCallback::MaoscOpenComplete() callback function is called when the stream has been
1.189 + opened and is ready to receive audio data. If the open was unsuccessful, this is indicated by the aError
1.190 + parameter of the callback.
1.191 +
1.192 +
1.193 + @param aSettings
1.194 + A pointer to a TMdaPackage object.
1.195 +
1.196 + */
1.197 + virtual void Open(TMdaPackage* aSettings);
1.198 +
1.199 + /**
1.200 + Returns the maximum volume level.
1.201 +
1.202 + @return The maximum volume level supported by the sound device, as an integer.
1.203 + */
1.204 + virtual TInt MaxVolume();
1.205 +
1.206 + /**
1.207 + Returns the current volume.
1.208 +
1.209 + @return The current volume as an integer.
1.210 + */
1.211 + virtual TInt Volume();
1.212 +
1.213 + /**
1.214 + Sets the audio volume.
1.215 +
1.216 + Set the volume to zero for "sound off" or any other value between 1 and MaxVolume().
1.217 +
1.218 + @param aNewVolume
1.219 + A specified audio volume.
1.220 +
1.221 + */
1.222 + virtual void SetVolume(const TInt aNewVolume);
1.223 +
1.224 + /**
1.225 + Sets the audio priority values.
1.226 +
1.227 + This function cannot be used while the stream object is open. It is intended for use before an Open()
1.228 + is issued, or between a previous Stop() and a new Open().
1.229 +
1.230 + @param aPriority
1.231 + The Priority Value.
1.232 + @param aPref
1.233 + The Priority Preference.
1.234 +
1.235 + @see CMdaAudioOutputStream::NewL()
1.236 + */
1.237 + virtual void SetPriority(TInt aPriority, TInt aPref);
1.238 +
1.239 + /**
1.240 + Writes (plays) streaming raw audio data.
1.241 +
1.242 + This function is asynchronous. When aData has been received, the client is notified by a call to
1.243 + MMdaAudioOutputStreamCallback::MaoscBufferCopied(). The client can call WriteL() again before this notification
1.244 + takes place because the buffers are maintained in a client-side queue until they have been sent. An active object
1.245 + performs the notification, and copies the next item in the queue to the server.
1.246 + MMdaAudioOutputStreamCallback::MaoscPlayComplete() is called when all descriptors have been sent.
1.247 +
1.248 + @param aData
1.249 + A reference to the stream data.
1.250 +
1.251 + */
1.252 + virtual void WriteL(const TDesC8& aData);
1.253 +
1.254 + /**
1.255 + Stops writing data to a stream.
1.256 +
1.257 + */
1.258 + virtual void Stop();
1.259 +
1.260 + /**
1.261 + Pause data rendering by audio hardware.
1.262 + @return An error code indicating if the operation was successful. KErrNone on success,
1.263 + KErrNotReady if not streaming
1.264 + KErrNotSupported if trying to pause when resume is not supported by DevSound
1.265 + */
1.266 +
1.267 + IMPORT_C TInt Pause();
1.268 +
1.269 +
1.270 + /**
1.271 + Resume data rendering by audio hardware.
1.272 + @return An error code indicating if the operation was successful. KErrNone on success,
1.273 + KErrNotReady if not paused.
1.274 + KErrNotSupported if trying to resume when resume is not supported by DevSound
1.275 + */
1.276 + IMPORT_C TInt Resume();
1.277 +
1.278 +
1.279 + /**
1.280 + Returns the current position within the data stream.
1.281 +
1.282 + @return The current position within the stream in microseconds.
1.283 + */
1.284 + virtual const TTimeIntervalMicroSeconds& Position();
1.285 +
1.286 + /**
1.287 + Sets the audio balance.
1.288 +
1.289 + @param aBalance
1.290 + A specified balance volume. Default is KMMFBalanceCenter.
1.291 +
1.292 + */
1.293 + IMPORT_C void SetBalanceL(TInt aBalance = KMMFBalanceCenter);
1.294 +
1.295 + /**
1.296 + Returns the current balance as an integer.
1.297 +
1.298 + @return The current balance value as integer.
1.299 + */
1.300 + IMPORT_C TInt GetBalanceL() const;
1.301 +
1.302 + /**
1.303 + Returns the current number of bytes rendered by audio hardware.
1.304 +
1.305 + @return The current current number of bytes rendered by audio hardware as an integer.
1.306 + */
1.307 + IMPORT_C TInt GetBytes();
1.308 +
1.309 + /**
1.310 + Sets the data type. If the data type is not explicitly set it will assumed to be pcm16.
1.311 + If it is set then the hardware must support the data type being set otherwise the
1.312 + function leaves with KErrNotSupported.
1.313 +
1.314 + @param aAudioType The fourCC code used to specify the data type of the streamed audio
1.315 +
1.316 + @leave KErrNotSupported
1.317 + Leaves with this for any unsuported data type.
1.318 + */
1.319 + IMPORT_C void SetDataTypeL(TFourCC aAudioType);
1.320 +
1.321 + /**
1.322 + Returns the current data type.
1.323 +
1.324 + @return The ID of the data type.
1.325 + */
1.326 + IMPORT_C TFourCC DataType() const;
1.327 +
1.328 + /**
1.329 + Registers the Event for Notification when resource is avaliable.
1.330 + @param aCallback
1.331 + The audio outputstream observer interface..
1.332 + @param aNotificationEventUid
1.333 + The Event for which the client is registered.
1.334 + @param aNotificationRegistrationData
1.335 + Notification registration specific data.
1.336 + @return An error code indicating if the registration was successful. KErrNone on success,
1.337 + otherwise another of the system-wide error codes.
1.338 + */
1.339 + IMPORT_C TInt RegisterAudioResourceNotification(MMMFAudioResourceNotificationCallback& aCallback,TUid aNotificationEventUid,const TDesC8& aNotificationRegistrationData = KNullDesC8);
1.340 +
1.341 + /**
1.342 + Cancels the registered notification event.
1.343 + @param aNotificationEventUid
1.344 + The Event to notify the client.
1.345 +
1.346 + @return An error code indicating if the registration was successful. KErrNone on success,
1.347 + otherwise another of the system-wide error codes.
1.348 + */
1.349 + IMPORT_C TInt CancelRegisterAudioResourceNotification(TUid aNotificationEventId);
1.350 +
1.351 + /**
1.352 + Waits for the client to resume the play even after the default timer expires.
1.353 + @return An error code indicating if the registration was successful. KErrNone on success,
1.354 + otherwise another of the system-wide error codes.
1.355 + */
1.356 + IMPORT_C TInt WillResumePlay();
1.357 +
1.358 + /**
1.359 + Retrieves a custom interface to the underlying device.
1.360 +
1.361 + @param aInterfaceId
1.362 + The interface UID, defined with the custom interface.
1.363 +
1.364 + @return A pointer to the interface implementation, or NULL if the device does not
1.365 + implement the interface requested. The return value must be cast to the
1.366 + correct type by the user.
1.367 + */
1.368 + IMPORT_C TAny* CustomInterface(TUid aInterfaceId);
1.369 +
1.370 + /**
1.371 + When this method is called, AudioOutputStream goes into a different mode wherein it does not call
1.372 + MaoscPlayComplete() with KErrUnderflow when all the supplied data has been played. Instead client
1.373 + should signal the end of the play by calling RequestStop() or Stop() on AudioOutputStream.
1.374 + If the client calls RequestStop(), AudioOutputStream waits until all the queued data has been played out
1.375 + and then calls MaoscPlayComplete(). This behaviour is different from that of Stop(), which stops the play
1.376 + immediately by discarding all the queued data.
1.377 +
1.378 + Client should call this method on CMdaAudioOutputStream just after its construction and its
1.379 + effect remains through out its lifetime.
1.380 +
1.381 + Note: This feature is supported only on a DevSound which ignores the underflow errors in the middle of
1.382 + the play i.e which returns ETrue from QueryIgnoresUnderflow().
1.383 +
1.384 + @return KErrNone on success,
1.385 + KErrNotSupported if the underlying DevSound does not ignore the underflow errors in the middle of the play
1.386 +
1.387 + @see CMdaAudioOutputStream::RequestStop()
1.388 + @see CMMFDevSound::QueryIgnoresUnderflow()
1.389 + */
1.390 + IMPORT_C TInt KeepOpenAtEnd();
1.391 +
1.392 + /**
1.393 + This method signals the end of play when the AudioOutputStream is in KeepOpenAtEnd mode i.e when client
1.394 + makes KeepOpenAtEnd call on it. When RequestStop is called, AudioOutputStream completes playing all
1.395 + the data that is supplied to it and calls MaoscPlayComplete() with KErrUnderflow.
1.396 +
1.397 + Note: Before calling this method, client must have already called KeepOpenAtEnd() successfully, Otherwise, this
1.398 + method returns KErrNotSupported.
1.399 + It is recommended to use KeepOpenAtEnd and RequestStop calls to get a predictable behaviour during stopping.
1.400 +
1.401 + @return KErrNone on success
1.402 + KErrNotSupported when this method is called without calling KeepOpenAtEnd
1.403 + KErrNotReady when this method is called before completing previous RequestStop or AudioOutputStream
1.404 + is already in the stopped state
1.405 +
1.406 + @see CMdaAudioOutputStream::KeepOpenAtEnd()
1.407 + */
1.408 + IMPORT_C TInt RequestStop();
1.409 +
1.410 +private:
1.411 + CMdaAudioOutputStream();
1.412 +private:
1.413 + /**
1.414 + This member is internal and not intended for use.
1.415 + */
1.416 + CMMFMdaAudioOutputStream* iProperties;
1.417 + };
1.418 +
1.419 +#endif