1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/mm/mmlibs/mmfw/inc/MdaAudioInputStream.h Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,395 @@
1.4 +
1.5 +// Copyright (c) 2002-2009 Nokia Corporation and/or its subsidiary(-ies).
1.6 +// All rights reserved.
1.7 +// This component and the accompanying materials are made available
1.8 +// under the terms of "Eclipse Public License v1.0"
1.9 +// which accompanies this distribution, and is available
1.10 +// at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.11 +//
1.12 +// Initial Contributors:
1.13 +// Nokia Corporation - initial contribution.
1.14 +//
1.15 +// Contributors:
1.16 +//
1.17 +// Description:
1.18 +//
1.19 +
1.20 +
1.21 +
1.22 +#ifndef __MDAAUDIOINPUTSTREAM_H
1.23 +#define __MDAAUDIOINPUTSTREAM_H
1.24 +
1.25 +
1.26 +#include <e32std.h>
1.27 +#include <mmf/common/mmfbase.h>
1.28 +#include <mmf/common/mmfstandardcustomcommands.h>
1.29 +#include <mda/common/base.h>
1.30 +#include <mmfclntutility.h>
1.31 +
1.32 +
1.33 +/**
1.34 +@publishedAll
1.35 +@released
1.36 +
1.37 +An interface class that notifies the client of the progress of the audio input streaming.
1.38 +
1.39 +It must be implemented by users of the CMdaAudioInputStream class.
1.40 +
1.41 +An object that implements this interface is passed to CMdaAudioInputStream::NewL().
1.42 +*/
1.43 +class MMdaAudioInputStreamCallback
1.44 + {
1.45 +public:
1.46 +
1.47 + /**
1.48 + A callback function that is called when CMdaAudioInputStream::Open() has
1.49 + completed, indicating that the audio input stream is ready for use.
1.50 +
1.51 + @param aError
1.52 + An error value which indicates if open was successful or not. KErrNone if the open succeeded,
1.53 + otherwise one of the system error codes.
1.54 +
1.55 + */
1.56 + virtual void MaiscOpenComplete(TInt aError) = 0;
1.57 +
1.58 + /**
1.59 + A callback function that is called when a chunk of audio data has been copied to the descriptor specified
1.60 + in a CMdaAudioInputStream::ReadL().
1.61 +
1.62 + It is also called as part of a 'cleanup' operation when CMdaAudioInputStream::Stop() is used. In such circumstances,
1.63 + the remaining audio data in the FIFO since the last ReadL() and the Stop() command is returned. In addition aError
1.64 + is set to KErrAbort.
1.65 +
1.66 + Use this callback to retrieve the pointers to your recorded data and to issue subsequent ReadL() calls, and be prepared
1.67 + to shut down you recording functions if KErrAbort (input stream closed) is returned in aError.
1.68 +
1.69 + @param aError
1.70 + An error value indicating if the copy was successful. KErrNone if the copy succeeded, KErrAbort if the input stream
1.71 + was closed for some reason, otherwise one of the system error codes.
1.72 + @param aBuffer
1.73 + A reference to the buffer that has been copied.
1.74 + */
1.75 + virtual void MaiscBufferCopied(TInt aError, const TDesC8& aBuffer) = 0;
1.76 +
1.77 + /**
1.78 + A callback function that is called when the input stream is closed using CMdaAudioInputStream::Stop().
1.79 +
1.80 + This callback is usually 'paired' with a MaiscBufferCopied() that returns the last remaining audio data
1.81 + in the FIFO between the last CMdaAudioInputStream::ReadL() and the Stop() command.
1.82 +
1.83 + @param aError
1.84 + An error value indicating if the record was successful. KErrNone if the stop succeeded, otherwise one
1.85 + of the system error codes.
1.86 + */
1.87 + virtual void MaiscRecordComplete(TInt aError) = 0;
1.88 + };
1.89 +
1.90 +
1.91 +class CMMFMdaAudioInputStream;
1.92 +
1.93 +/**
1.94 +@publishedAll
1.95 +@released
1.96 +
1.97 +The interface to an audio stream player passing raw audio data from the audio hardware to specified buffers.
1.98 +
1.99 +This class enables MMF clients to:
1.100 +
1.101 +Stream raw audio data from the audio hardware to specified buffers.
1.102 +
1.103 +Specify the priority of the audio stream in relation to other clients that may request to use the same audio hardware.
1.104 +
1.105 +Set the sample rate and the number of channels after successfully opening the stream. It is not possible to
1.106 +change these values once streaming has started.
1.107 +
1.108 +Change the gain and balance before or while streaming is in progress. Gain and balance settings take effect immediately.
1.109 +
1.110 +
1.111 +The API supports callbacks from the server to notify the client:
1.112 +
1.113 +MaiscOpenComplete() will be called when the audio streaming object is open and ready to stream data back to the
1.114 +user as a result of a previous call to Open().
1.115 +
1.116 +MaiscBufferCopied() will be called multiple times while the FIFO (queued via ReadL()) is emptied.
1.117 +Note: Each buffer will be flagged with KErrAbort if received after Stop() on is called. MaiscRecordComplete is called
1.118 +once all remaining buffers have been read.
1.119 +
1.120 +
1.121 +MaiscRecordComplete() is called after Stop() has been called. aError - KErrAbort if MaiscRecordComplete called
1.122 +as a result of a call to Stop().
1.123 +
1.124 +Users of object CMdaAudioInputStream should ensure that implementation of the callback methods MaiscOpenComplete,MaiscBufferCopied
1.125 +and MaiscRecordComplete in class MMdaAudioInputStreamCallback do not delete the object,otherwise a Kern-Exec 3 would occur during callback.
1.126 +*/
1.127 +class CMdaAudioInputStream : public CBase,
1.128 + public MMMFClientUtility
1.129 +{
1.130 +public:
1.131 +
1.132 + /**
1.133 + Instantiates a new audio input stream using default priority preferences.
1.134 +
1.135 + @param aCallBack
1.136 + A callback to notify the client when the input stream has been initialised and is ready
1.137 + for use, when data has been copied to a specified descriptor and when input streaming is
1.138 + stopped. The caller must create a callback class that implements this interface.
1.139 +
1.140 + @return A pointer to the audio input stream object.
1.141 +
1.142 + @capability UserEnvironment
1.143 + For recording - the requesting client process must have a
1.144 + UserEnvironment capability.
1.145 + */
1.146 + IMPORT_C static CMdaAudioInputStream* NewL(MMdaAudioInputStreamCallback& aCallBack);
1.147 +
1.148 + /**
1.149 + Instantiates a new audio input stream.
1.150 +
1.151 + @param aCallBack
1.152 + A callback to notify the client when the input stream has been initialised and is ready for
1.153 + use. The caller must create a callback class which implements this interface.
1.154 + @param aPriority
1.155 + The Priority Value - this client's relative priority. This is a value between EMdaPriorityMin and
1.156 + EMdaPriorityMax and represents a relative priority. A higher value indicates a more important request.
1.157 + @param aPref
1.158 + The Priority Preference - an additional audio policy parameter. The suggested default is
1.159 + EMdaPriorityPreferenceNone. Further values are given by TMdaPriorityPreference, and additional
1.160 + values may be supported by given phones and/or platforms, but should not be depended upon by
1.161 + portable code.
1.162 +
1.163 + @return A pointer to the audio input stream object.
1.164 +
1.165 + @capability UserEnvironment
1.166 + For recording - the requesting client process must have a
1.167 + UserEnvironment capability.
1.168 +
1.169 + Note: The Priority Value and Priority Preference are used primarily when deciding what to do when
1.170 + several audio clients attempt to play or record simultaneously. In addition to the Priority Value and Preference,
1.171 + the adaptation may consider other parameters such as the SecureId and Capabilities of the client process.
1.172 + Whatever, the decision as to what to do in such situations is up to the audio adaptation, and may
1.173 + vary between different phones. Portable applications are advised not to assume any specific behaviour.
1.174 + */
1.175 + IMPORT_C static CMdaAudioInputStream* NewL(MMdaAudioInputStreamCallback& aCallBack,
1.176 + TInt aPriority, TInt aPref);
1.177 +
1.178 + /**
1.179 + Destructor.
1.180 +
1.181 + Frees all resources owned by the object prior to its destruction.
1.182 + */
1.183 + ~CMdaAudioInputStream();
1.184 +
1.185 + /**
1.186 + Sets the sample rate and number of audio channels.
1.187 +
1.188 + @param aSampleRate
1.189 + The new sample rate. For possible values, see the TAudioCaps enum in class TMdaAudioDataSettings.
1.190 + @param aChannels
1.191 + The new number of channels. For possible values, see the TAudioCaps enum in class TMdaAudioDataSettings.
1.192 + */
1.193 + IMPORT_C void SetAudioPropertiesL(TInt aSampleRate, TInt aChannels);
1.194 +
1.195 + /**
1.196 + Opens an input audio stream package.
1.197 +
1.198 + The MMdaAudioInputStreamCallback::MaisOpenComplete() callback function is called when the stream has been
1.199 + opened and is ready to record data. If the open was unsuccessful, this is indicated by the aError parameter
1.200 + of the callback.
1.201 +
1.202 + @param aSettings
1.203 + A pointer to an TMdaPackage object.
1.204 + */
1.205 + IMPORT_C void Open(TMdaPackage* aSettings);
1.206 +
1.207 + /**
1.208 + Sets the gain for the audio device to a specified value.
1.209 +
1.210 + @param aNewGain
1.211 + The gain setting. This can be any value from zero to the value returned by a call to
1.212 + MaxGain(). A value which is less than zero is set to zero. A value which is greater
1.213 + than MaxGain() is set to MaxGain().
1.214 + */
1.215 + IMPORT_C void SetGain(TInt aNewGain);
1.216 +
1.217 + /**
1.218 + Returns the current gain setting.
1.219 +
1.220 + @return The current gain setting.
1.221 + */
1.222 + IMPORT_C TInt Gain() const;
1.223 +
1.224 + /**
1.225 + Returns the maximum gain level.
1.226 +
1.227 + @return The maximum gain value that is supported by the sound device.
1.228 + */
1.229 + IMPORT_C TInt MaxGain() const;
1.230 +
1.231 + /**
1.232 + Sets the current audio balance.
1.233 +
1.234 + The balance can be any value between KMMFBalanceMaxLeft and KMMFBalanceMaxRight, the default value
1.235 + being KMMFBalanceCenter.
1.236 +
1.237 + @param aBalance
1.238 + A specified balance value.
1.239 + */
1.240 + IMPORT_C void SetBalanceL(TInt aBalance = KMMFBalanceCenter);
1.241 +
1.242 + /**
1.243 + Returns the current audio balance.
1.244 +
1.245 + @return The current balance value.
1.246 + */
1.247 + IMPORT_C TInt GetBalanceL() const;
1.248 +
1.249 + /**
1.250 + Sets the audio priority values.
1.251 +
1.252 + This function cannot be used while the stream object is open. It is intended for use before an Open()
1.253 + is issued, or between a previous Stop() and a new Open().
1.254 +
1.255 + @param aPriority
1.256 + The Priority Value.
1.257 + @param aPref
1.258 + The Priority Preference.
1.259 +
1.260 + @see CMdaAudioInputStream::NewL()
1.261 + */
1.262 + IMPORT_C void SetPriority(TInt aPriority, TInt aPref);
1.263 +
1.264 + /**
1.265 + Records streaming raw audio data.
1.266 +
1.267 + If this is the first ReadL() after a successful Open() this function starts the audio recording process.
1.268 +
1.269 + The MMdaAudioInputStreamCallback::MaisBufferCopied() callback function is called when the buffer has been successfully
1.270 + filled. A pointer to the newly filled buffer is returned in the callback.
1.271 +
1.272 + Note: The MMdaAudioInputStreamCallback::MaisBufferCopied() callback function is also called when a Stop() is issued, with a
1.273 + pointer to the remaining recorded audio data and the aError parameter of the callback set to indicate recording has finished.
1.274 +
1.275 + @param aData
1.276 + A reference to a buffer to be written into.
1.277 + */
1.278 + IMPORT_C void ReadL(TDes8& aData);
1.279 +
1.280 + /**
1.281 + Stops the recording process.
1.282 +
1.283 + The MMdaAudioInputStreamCallback::MaisRecordComplete() callback function is called when recording has been halted. Just prior
1.284 + to issuing this callback, the FIFO buffers are read and the remaining audio data passed back by a final
1.285 + MMdaAudioInputStreamCallback::MaisBufferCopied() callback with its aError parameter set to KErrAbort.
1.286 +
1.287 + Any remaining FIFO buffers are also passed back, with their aError parameter set to KErrAbort.
1.288 +
1.289 + Stop is immediate and best used for premature stops, for example within destructors.
1.290 + If it is critical to receive all data buffers upto the point that Recording has Stopped,
1.291 + we recommend using RequestStop instead. Otherwise some trailing buffers may be lost from the recording process.
1.292 +
1.293 + If a Stop is issued after a RequestStop, Stop will take precedent.
1.294 +
1.295 + @see CMdaAudioInputStream::RequestStop()
1.296 + */
1.297 + IMPORT_C void Stop();
1.298 +
1.299 + /**
1.300 + Returns the current position within the data stream in microseconds since the start of streaming.
1.301 +
1.302 + @return The current position.
1.303 + */
1.304 + IMPORT_C const TTimeIntervalMicroSeconds& Position();
1.305 +
1.306 + /**
1.307 + Returns the current number of bytes rendered by audio hardware.
1.308 +
1.309 + @return The number of bytes.
1.310 + */
1.311 + IMPORT_C TInt GetBytes();
1.312 +
1.313 +
1.314 + /**
1.315 + Sets the data type. If the data type is not explicitly set it will assumed to be pcm16.
1.316 + If it is set then the hardware must support the data type being set otherwise the
1.317 + function leaves with KErrNotSupported.
1.318 +
1.319 + @param aAudioType The fourCC code used to request the data type of the recorded data.
1.320 +
1.321 + @leave KErrNotSupported
1.322 + Leaves with this for any unsuported data type.
1.323 + */
1.324 + IMPORT_C void SetDataTypeL(TFourCC aAudioType);
1.325 +
1.326 + /**
1.327 + Returns the current data type.
1.328 +
1.329 + @return The ID of the data type.
1.330 + */
1.331 + IMPORT_C TFourCC DataType() const;
1.332 +
1.333 + /**
1.334 + Returns the bit rates supported by the sound device
1.335 +
1.336 + @param aSupportedBitRates
1.337 + @leave KErrNotSupported
1.338 + If the sound device does not support setting the bit rate
1.339 + The supported bit rates, in bits per second, shall be appended to this array. Note that
1.340 + the array shall be reset by this method.
1.341 + */
1.342 + IMPORT_C void GetSupportedBitRatesL(RArray<TInt>& aSupportedBitRates);
1.343 + /**
1.344 + Returns the current bit rate.
1.345 + @return The current bit rate, in bits per second.
1.346 + @leave KErrNotSupported
1.347 + If the sound device does not support returning the current bit rate
1.348 + */
1.349 + IMPORT_C TInt BitRateL() const;
1.350 + /**
1.351 + Sets the bit rate to a new value.
1.352 + @param aBitRate
1.353 + The new bit rate, in bits per second.
1.354 + @leave KErrNotSupported
1.355 + If the sound device does not support returning the current bit rate or the bit rate set is not supported
1.356 + */
1.357 + IMPORT_C void SetBitRateL(TInt aBitRate);
1.358 +
1.359 + /**
1.360 + Retrieves a custom interface to the underlying device.
1.361 +
1.362 + @param aInterfaceId
1.363 + The interface UID, defined with the custom interface.
1.364 +
1.365 + @return A pointer to the interface implementation, or NULL if the device does not
1.366 + implement the interface requested. The return value must be cast to the
1.367 + correct type by the user.
1.368 + */
1.369 + IMPORT_C TAny* CustomInterface(TUid aInterfaceId);
1.370 +
1.371 + /**
1.372 + Indicates that the client wishes to use a single buffer to collect the data.
1.373 + This buffer is passed via the ReadL api.
1.374 +
1.375 + @param aSingleMode
1.376 + ETrue to indicate setting of single buffer mode and the use of a single
1.377 + buffer, EFalse to indicate use of multiple buffers.
1.378 + */
1.379 + IMPORT_C void SetSingleBufferMode(TBool aSingleMode);
1.380 +
1.381 + /**
1.382 + Requests a Stop of the recording process.
1.383 +
1.384 + The device is requested to Stop and does so after all unprocessed buffers are processed and passed
1.385 + back to the input stream. The device is actually Stopped when the final empty buffer indicating
1.386 + buffer process completion is received.
1.387 +
1.388 + @see CMdaAudioInputStream::Stop()
1.389 + */
1.390 + IMPORT_C void RequestStop();
1.391 +
1.392 +private:
1.393 + CMdaAudioInputStream();
1.394 +private:
1.395 + CMMFMdaAudioInputStream* iProperties;
1.396 + };
1.397 +
1.398 +#endif