1 drmaudiosampleplayer.h

     1 /*

     2 * Copyright (c) 2002-2004 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * 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

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  DRM Audio player

    15 *

    16 */

    17 

    18 

    19 

    20 #ifndef DRMAUDIOSAMPLEPLAYER_H

    21 #define DRMAUDIOSAMPLEPLAYER_H

    22 

    23 

    24 

    25 #include <e32base.h>

    26 #include <MdaAudioSamplePlayer.h>

    27 

    28 // FORWARD DECLARATIONS

    29 class CMMFDrmAudioPlayerUtility;

    30 

    31 // CLASS DECLARATION

    32 

    33 /**

    34 *  Interface class for DRM Player callbacks

    35 *

    36 *

    37 *  @lib DRMAudioPlayer.lib

    38 *  @since Series 60 3.0

    39 */

    40 

    41 class MDrmAudioPlayerCallback

    42 	{

    43 public:

    44         /**

    45         * Called by CDrmPlayerUtility when initialization is complete.

    46         * @since Series 60 3.0

    47 		* @param aError The status of the audio sample after initialisation.

    48 	        The following values have the same specific meaning

    49 	        across all EPOC platforms: KErrNone the

    50 	        sample is ready to play. KErrNotSupported

    51 	        the audio format or particular encoding type is not

    52 	        recognised or not supported. KErrNotFound

    53 	        the audio sample cannot be found.

    54 	        KErrNoMemory there is insufficient memory

    55 	        to play this audio sample. Other values are possible

    56 	        indicating a problem opening the audio sample. These

    57 	        values are dependent on the EPOC platform.

    58         * @param aDuration The duration of the audio sample.

    59         */

    60 

    61 	virtual void MdapcInitComplete(TInt aError, const TTimeIntervalMicroSeconds& aDuration) = 0;

    62 

    63         /**

    64         * Called by CDrmPlayerUtility when playing is complete.

    65         * @since Series 60 3.0

    66         * @param aError

    67 		     The status of playback. The following values have the

    68 	         same specific meaning across all EPOC platforms:

    69 	         KErrNone playing of the audio sample is

    70 	         complete. KErrCorrupt the sample data is

    71 	         corrupt. KErrInUse the sound device is in

    72 	         use by another higher priority client. This can happen

    73 	         during playback. KErrNoMemory there is

    74 	         insufficient memory to play this audio sample Other

    75 	         values are possible indicating a problem opening the

    76 	         audio sample. These values are dependent on the EPOC

    77 	         platform.

    78         */

    79 	virtual void MdapcPlayComplete(TInt aError) = 0;

    80 	};

    81 

    82 

    83 

    84 /**

    85 *  Used by third party developers to play sampled audio data.

    86 The class offers a simple interface to open, play and obtain

    87 information from, sampled audio data. The audio data can be supplied

    88 either in a file (file-based), as a descriptor

    89 (descriptor-based) or as a URL reference.

    90 *

    91 *  @lib DRMAudioPlayer.lib

    92 *  @since Series 60 3.0

    93 */

    94 class CDrmPlayerUtility : public CBase

    95 	{

    96 	public:

    97 

    98         /**

    99         * Two-phased constructor.

   100         */

   101 	IMPORT_C static  CDrmPlayerUtility* NewL(MDrmAudioPlayerCallback& aCallback,TInt aPriority,

   102 															  TMdaPriorityPreference aPref);

   103 

   104         /**

   105         * Two-phased constructor.

   106         */

   107 	IMPORT_C static  CDrmPlayerUtility* NewFilePlayerL(const TDesC& aFileName,MDrmAudioPlayerCallback& aCallback,

   108 																		TInt aPriority,

   109 																		TMdaPriorityPreference aPref);

   110 

   111         /**

   112         * Two-phased constructor.

   113         */

   114 	IMPORT_C static  CDrmPlayerUtility* NewDesPlayerL(const TDesC8& aData,

   115 													MDrmAudioPlayerCallback& aCallback,

   116 													TInt aPriority,

   117 													TMdaPriorityPreference aPref

   118 													);

   119 

   120         /**

   121         * Two-phased constructor.

   122         */

   123 	IMPORT_C static  CDrmPlayerUtility* NewDesPlayerReadOnlyL(const TDesC8& aData,

   124 													MDrmAudioPlayerCallback& aCallback,

   125 													TInt aPriority,

   126 													TMdaPriorityPreference aPref

   127 													);

   128 

   129         /**

   130         * Destructor.

   131         */

   132 	IMPORT_C ~CDrmPlayerUtility();

   133 

   134         /**

   135 		* Begins playback of the initialised audio sample at the current volume and priority levels.

   136         *

   137         * @since Series 60 3.0

   138         */

   139 	IMPORT_C void Play();

   140 

   141         /**

   142 		* Stops playback of the audio sample as soon as is possible.

   143 		*

   144         * @since Series 60 3.0

   145         */

   146 	IMPORT_C void Stop();

   147 

   148         /**

   149 		* Pauses playback of the audio clip

   150 		*

   151         * @since Series 60 3.0

   152 		* @return KErrNone on success, otherwise another of the system-wide error codes

   153         */

   154 	IMPORT_C TInt Pause();

   155 

   156         /**

   157 		* Changes the current playback volume to a specified value.

   158 		*

   159         * @since Series 60 3.0

   160         * @param aVolume Any value between 0 (mute) and the maximum volume

   161         */

   162 	IMPORT_C void SetVolume(TInt aVolume

   163 							);

   164 

   165         /**

   166 		* Sets the number of times the audio sample should be repeated during the playback operation

   167 		*

   168         * @since Series 60 3.0

   169 

   170         * @param aRepeatNumberOfTimes

   171 		The number of times to repeat the sample. Use 0 for no repeat,

   172 		KMdaRepeatForever for continuous, any other value for number of times.

   173         * @param aTrailingSilence

   174 		 The duration of silence after the sample has played in microseconds.

   175         */

   176 	IMPORT_C void SetRepeats(TInt aRepeatNumberOfTimes,

   177 							const TTimeIntervalMicroSeconds& aTrailingSilence

   178 							);

   179 

   180         /**

   181 		* Changes the current playback volume to a specified value.

   182 		*

   183         * @since Series 60 3.0

   184         * @param aVolume Any value between 0 (mute) and the maximum volume returned by

   185         */

   186 	IMPORT_C void SetVolumeRamp(const TTimeIntervalMicroSeconds& aRampDuration);

   187 

   188 

   189         /**

   190 		* Returns the duration of the audio sample in microseconds.

   191 		*

   192         * @since Series 60 3.0

   193 		* @return The duration of the sample in microseconds

   194         */

   195 	IMPORT_C const TTimeIntervalMicroSeconds& Duration();

   196 

   197         /**

   198 		* Returns an integer representing the maximum volume that the audio clip can support.

   199 		*

   200         * @since Series 60 3.0

   201 		* @return The maximum permissible volume setting

   202         */

   203 	IMPORT_C TInt MaxVolume();

   204 

   205         /**

   206 		* Opens an audio clip from a file.

   207 		*

   208         * @since Series 60 3.0

   209 		* @param aFileName The file containing the audio clip

   210         */

   211 	IMPORT_C void OpenFileL(const TDesC& aFileName);

   212 

   213         /**

   214 		* Opens an audio clip from a file.

   215 		*

   216         * @since Series 60 3.0

   217 		* @param aFile The file handle of the file containing the clip

   218         */

   219 	IMPORT_C void OpenFileL(const RFile& aFile);

   220 

   221         /**

   222 		* Opens an audio clip from a file.

   223 		*

   224         * @since Series 60 3.0

   225 		* @param aSource The source of the file containing the clip

   226         */

   227 	IMPORT_C void OpenFileL(const TMMSource& aSource);

   228 

   229         /**

   230 		* Opens an audio clip from a descriptor.

   231 		*

   232         * @since Series 60 3.0

   233 		* @param aDescriptor The descriptor containing the audio clip

   234         */

   235 	IMPORT_C void OpenDesL(const TDesC8& aDescriptor);

   236 

   237         /**

   238 		* Opens an audio clip from a URL.

   239 		*

   240         * @since Series 60 3.0

   241 		* @param aUrl The URL of the audio clip.

   242 		* @param aMimeType The mime type associated with the specified URL/audio clip

   243         */

   244 	IMPORT_C void OpenUrlL(const TDesC& aUrl, TInt aIapId = KUseDefaultIap, const TDesC8& aMimeType=KNullDesC8);

   245 

   246         /**

   247 		* Closes the current audio clip.

   248 		*

   249         * @since Series 60 3.0

   250         */

   251 	IMPORT_C void Close();

   252 

   253         /**

   254 		* Returns the current playback position in microseconds from the start of the clip.

   255 		*

   256         * @since Series 60 3.0

   257 		* @param aPosition The number of microseconds from the start of the clip to the current play position

   258 		* @return KErrNone on success, otherwise another of the system-wide error codes

   259         */

   260 	IMPORT_C TInt GetPosition(TTimeIntervalMicroSeconds& aPosition);

   261 

   262         /**

   263 		* Returns the current playback position in microseconds from the start of the clip.

   264 		*

   265         * @since Series 60 3.0

   266 		* @param aPosition The number of microseconds from the start of the clip to the current play position

   267 		* @return KErrNone on success, otherwise another of the system-wide error codes

   268         */

   269 	IMPORT_C void SetPosition(const TTimeIntervalMicroSeconds& aPosition);

   270 

   271         /**

   272 		* Set the priority for playback.

   273 		*

   274         * @since Series 60 3.0

   275 		* @param aPriority

   276 			The priority level to apply, EMdaPriorityMin client can be interrupted by any other client,

   277 			EMdaPriorityNormal client can only be interrupted by a client with a higher priority or

   278 			EMdaPriorityMax client cannot be interrupted by other clients.

   279 		* @param aPref The time and quality preferences to apply.

   280 		* @return KErrNone on success, otherwise another of the system-wide error codes

   281         */

   282 	IMPORT_C TInt SetPriority(TInt aPriority, TMdaPriorityPreference aPref);

   283 

   284         /**

   285 		* Returns the current playback volume.

   286 		*

   287         * @since Series 60 3.0

   288 		* @param aVolume A value between 0 (mute) and the maximum volume setting

   289 		* @return KErrNone on success, otherwise another of the system-wide error codes

   290         */

   291 	IMPORT_C TInt GetVolume(TInt& aVolume);

   292 

   293         /**

   294 		* Gets the number of meta data entries in the current audio clip.

   295 		*

   296         * @since Series 60 3.0

   297 		* @param aNumEntries On return, contains the number of meta data entries

   298 		* @return KErrNone on success, otherwise another of the system-wide error codes

   299         */

   300 	IMPORT_C TInt GetNumberOfMetaDataEntries(TInt& aNumEntries);

   301 

   302        /**

   303 		* Returns a specified meta data entry from the audio clip.

   304 		*

   305         * @since Series 60 3.0

   306 		* @param aMetaDataIndex The index of the meta data entry to return

   307 		* @return The returned meta data entry

   308         */

   309 	IMPORT_C CMMFMetaDataEntry* GetMetaDataEntryL(TInt aMetaDataIndex);

   310 

   311        /**

   312 		* Defines the size of the current playback window.

   313 		*

   314         * @since Series 60 3.0

   315 		* @param aStart

   316 			The position defining the start of the window, measured in microseconds.

   317 			If this value is less than zero, it is set to zero. If this value is

   318 			greater than aEnd, then it is swapped with aEnd.

   319 		* @param aEnd

   320 			The position defining the end of the window, measured in microseconds.

   321 			If this value is greater than the value returned by Duration(), it is

   322 			set to the value of Duration(). If this value is less than aStart, then

   323 			it is swapped with aStart.

   324 		* @return KErrNone on success, otherwise another of the system-wide error codes

   325         */

   326 	IMPORT_C TInt SetPlayWindow(const TTimeIntervalMicroSeconds& aStart,

   327 								const TTimeIntervalMicroSeconds& aEnd);

   328 

   329        /**

   330 		* Clears the current playback window.

   331 		*

   332         * @since Series 60 3.0

   333 		* @return KErrNone on success, otherwise another of the system-wide error codes

   334         */

   335 	IMPORT_C TInt ClearPlayWindow();

   336 

   337        /**

   338 		* Sets the current playback balance.

   339 		*

   340         * @since Series 60 3.0

   341         * @param aBalance The balance value to set

   342 		* @return KErrNone on success, otherwise another of the system-wide error codes

   343         */

   344 	IMPORT_C TInt SetBalance(TInt aBalance = KMMFBalanceCenter);

   345 

   346        /**

   347 		* Returns the current playback balance.

   348 		*

   349         * @since Series 60 3.0

   350         * @param aBalance On return, contains the current balance setting

   351 		* @return KErrNone on success, otherwise another of the system-wide error codes

   352         */

   353 	IMPORT_C TInt GetBalance(TInt& aBalance);

   354 

   355        /**

   356 		* Returns the current bit rate

   357 		*

   358         * @since Series 60 3.0

   359         * @param aBitRate On return, contains the current bit rate

   360 		* @return KErrNone on success, otherwise another of the system-wide error codes

   361         */

   362 	IMPORT_C TInt GetBitRate(TUint& aBitRate);

   363 

   364        /**

   365 		* Allows user to register for audio loading callback

   366 		*

   367         * @since Series 60 3.0

   368         * @param aCallback Reference to the client to be notified

   369         */

   370 	IMPORT_C void RegisterForAudioLoadingNotification(MAudioLoadingObserver& aCallback);

   371 

   372        /**

   373 		* Gets the progress of audio loading

   374 		*

   375         * @since Series 60 3.0

   376         * @param aPercentageProgress Upon return, contains the percentage progress

   377         */

   378 	IMPORT_C void GetAudioLoadingProgressL(TInt& aPercentageProgress);

   379 

   380        /**

   381 		* Returns controller implementation parameters

   382 		*

   383         * @since Series 60 3.0

   384         * @return The controller information

   385         */

   386 	IMPORT_C const CMMFControllerImplementationInformation& ControllerImplementationInformationL();

   387 

   388        /**

   389 		* Sends a custom command synchronously to the controller plugin

   390 		*

   391         * @since Series 60 3.0

   392         * @param aDestination

   393 			The destination of the custom command, consisting of the unique ID of the

   394 			interface of this custom command and a special handle id KMMFObjectHandleController

   395 			to indicate that the custom command is to be handled by the controller plugin

   396         * @param aFunction The function number to indicate which function is to be called

   397 			on the controller's custom command interface.

   398         * @param aDataTo1 A reference to data to be copied to the controller plugin. The exact

   399 			contents of the data are dependent on the custom command interface of the controller. Can be NULL.

   400         * @param aDataTo2

   401 			A reference to data to be copied to the controller plugin. The exact contents of the data

   402 			are dependent on the custom command interface of the controller. Can be NULL

   403         * @param aDataFrom

   404 			A reference to an area of memory to which the controller plugin will write any data

   405 			to be passed back to the client. Cannot be NULL

   406 		* @return KErrNone on success, otherwise another of the system-wide error codes

   407         */

   408 	IMPORT_C TInt CustomCommandSync(const TMMFMessageDestinationPckg& aDestination, TInt aFunction, const TDesC8& aDataTo1, const TDesC8& aDataTo2, TDes8& aDataFrom);

   409 

   410       /**

   411 		* Sends a custom command synchronously to the controller plugin

   412 		*

   413         * @since Series 60 3.0

   414         * @param aDestination

   415 			The destination of the custom command, consisting of the unique ID of the

   416 			interface of this custom command and a special handle id KMMFObjectHandleController

   417 			to indicate that the custom command is to be handled by the controller plugin

   418         * @param aFunction The function number to indicate which function is to be called

   419 			on the controller's custom command interface.

   420         * @param aDataTo1 A reference to data to be copied to the controller plugin. The exact

   421 			contents of the data are dependent on the custom command interface of the controller. Can be NULL.

   422         * @param aDataTo2

   423 			A reference to data to be copied to the controller plugin. The exact contents of the data

   424 			are dependent on the custom command interface of the controller. Can be NULL

   425 		* @return KErrNone on success, otherwise another of the system-wide error codes

   426         */

   427 	IMPORT_C TInt CustomCommandSync(const TMMFMessageDestinationPckg& aDestination, TInt aFunction, const TDesC8& aDataTo1, const TDesC8& aDataTo2);

   428 

   429       /**

   430 		* Sends a custom command asynchronously to the controller plugin

   431 		*

   432         * @since Series 60 3.0

   433         * @param aDestination

   434 			The destination of the custom command, consisting of the unique ID of the

   435 			interface of this custom command and a special handle id KMMFObjectHandleController

   436 			to indicate that the custom command is to be handled by the controller plugin

   437         * @param aFunction The function number to indicate which function is to be called

   438 			on the controller's custom command interface.

   439         * @param aDataTo1 A reference to data to be copied to the controller plugin. The exact

   440 			contents of the data are dependent on the custom command interface of the controller. Can be NULL.

   441         * @param aDataTo2

   442 			A reference to data to be copied to the controller plugin. The exact contents of the data

   443 			are dependent on the custom command interface of the controller. Can be NULL

   444         * @param aDataFrom

   445 			A reference to an area of memory to which the controller plugin will write any data

   446 			to be passed back to the client. Cannot be NULL

   447         * @param aDataFrom

   448 			The TRequestStatus of an active object. This will contain the result of the custom

   449 			command on completion. The exact range of result values is dependent on the custom

   450 			command interface

   451 		* @return KErrNone on success, otherwise another of the system-wide error codes

   452         */

   453 	IMPORT_C void CustomCommandAsync(const TMMFMessageDestinationPckg& aDestination, TInt aFunction, const TDesC8& aDataTo1, const TDesC8& aDataTo2, TDes8& aDataFrom, TRequestStatus& aStatus);

   454 

   455       /**

   456 		* Sends a custom command asynchronously to the controller plugin

   457 		*

   458         * @since Series 60 3.0

   459         * @param aDestination

   460 			The destination of the custom command, consisting of the unique ID of the

   461 			interface of this custom command and a special handle id KMMFObjectHandleController

   462 			to indicate that the custom command is to be handled by the controller plugin

   463         * @param aFunction The function number to indicate which function is to be called

   464 			on the controller's custom command interface.

   465         * @param aDataTo1 A reference to data to be copied to the controller plugin. The exact

   466 			contents of the data are dependent on the custom command interface of the controller. Can be NULL.

   467         * @param aDataTo2

   468 			A reference to data to be copied to the controller plugin. The exact contents of the data

   469 			are dependent on the custom command interface of the controller. Can be NULL

   470         * @param aDataFrom

   471 			A reference to an area of memory to which the controller plugin will write any data

   472 			to be passed back to the client. Cannot be NULL

   473 		* @return KErrNone on success, otherwise another of the system-wide error codes

   474         */

   475 	IMPORT_C void CustomCommandAsync(const TMMFMessageDestinationPckg& aDestination, TInt aFunction, const TDesC8& aDataTo1, const TDesC8& aDataTo2, TRequestStatus& aStatus);

   476 

   477 protected:

   478 	/**

   479 	This member is internal and not intended for use.

   480 	*/

   481 	CMMFDrmAudioPlayerUtility* iProperties;

   482 

   483 	};

   484 

   485 #endif