Class CVideoPlayerUtility

class CVideoPlayerUtility : public CBase, public MMMFClientUtility;

Description

Plays sampled video data.

The class offers a simple interface to open, play and obtain information from sampled video data. The video data can be provided using files, descriptors or URLs.

Note: Some video formats also allow the storing of audio data. To accommodate this, this class contains audio functions that can manipulate such data.

While this class is abstract, NewL() constructs, initialises and returns pointers to instances of concrete classes derived from this abstract class. This concrete class is part of the MMF implementation and is private.

Derivation

• MMMFClientUtility - No description.
• CBase - Base class for all classes to be instantiated on the heap

• CVideoPlayerUtility - Plays sampled video data

Members

Defined in CVideoPlayerUtility:
AudioBitRateL(), AudioEnabledL(), AudioTypeL(), Balance(), CancelRegisterAudioResourceNotification(), Close(), ControllerImplementationInformationL(), CustomCommandAsync(), CustomCommandAsync(), CustomCommandSync(), CustomCommandSync(), DurationL(), GetCropRegionL(), GetDRMCustomCommand(), GetFrameL(), GetFrameL(), GetScaleFactorL(), GetVideoLoadingProgressL(), MaxVolume(), MetaDataEntryL(), NewL(), NumberOfMetaDataEntriesL(), OpenDesL(), OpenFileL(), OpenFileL(), OpenFileL(), OpenUrlL(), PauseL(), Play(), Play(), PositionL(), Prepare(), PriorityL(), RefreshFrameL(), RegisterAudioResourceNotification(), RegisterForVideoLoadingNotification(), RotationL(), SetBalanceL(), SetCropRegionL(), SetDisplayWindowL(), SetInitScreenNumber(), SetPositionL(), SetPriorityL(), SetRotationL(), SetScaleFactorL(), SetVideoFrameRateL(), SetVolumeL(), StartDirectScreenAccessL(), Stop(), StopDirectScreenAccessL(), VideoBitRateL(), VideoFormatMimeType(), VideoFrameRateL(), VideoFrameSizeL(), Volume(), WillResumePlay()

Inherited from CBase:
Delete(), Extension_(), operator new()

Capability:

MultimediaDD

A process requesting or using this method that has MultimediaDD capability will always have precedence over a process that does not have MultimediaDD.

static IMPORT_C CVideoPlayerUtility *NewL(MVideoPlayerUtilityObserver &aObserver, TInt aPriority, TMdaPriorityPreference aPref, RWsSession &aWs, CWsScreenDevice &aScreenDevice, RWindowBase &aWindow, const TRect &aScreenRect, const TRect &aClipRect);

Description

Constructs and initialises a new instance of the video player utility.

This function leaves if the video player utility object cannot be created.

Parameters

MVideoPlayerUtilityObserver &aObserver A client class to receive notifications from the video player. TInt aPriority This client's relative priority. This is a value between EMdaPriorityMin and EMdaPriorityMax and represents a relative priority. A higher value indicates a more important request. TMdaPriorityPreference aPref The required behaviour if a higher priority client takes over the sound output device. One of the values defined by TMdaPriorityPreference. RWsSession &aWs The window server session id. CWsScreenDevice &aScreenDevice The software device screen. RWindowBase &aWindow The display window. const TRect &aScreenRect The dimensions of the display window. const TRect &aClipRect The area of the video clip to display in the window.

Return value

CVideoPlayerUtility * A pointer to the new video player utility object.

IMPORT_C void OpenFileL(const TDesC &aFileName, TUid aControllerUid=TUid::Null());

Description

Opens a video clip from a file.

This function opens a video clip from a file using an optionally specified plugin. If no controller plugin is specified, this function searches through a list of all available plugins and attempts to use each one until successful or the end of the list is reached.

Once the opening of the video clip is complete, successfully or otherwise, the callback function MVideoPlayerUtilityObserver::MvpuoOpenComplete() is called.

This function leaves if errors are encountered opening the specified video clip file, or in initialising a specified/unspecified controller plugin.

This function can leave with one of the specified error codes. Most open failures will however be reported through the MVideoPlayerUtilityObserver interface.

Parameters

const TDesC &aFileName The full path name of the file containing the video data. TUid aControllerUid If specified, it will force the video player to use the controller with the given UID.

IMPORT_C void OpenFileL(const RFile &aFileName, TUid aControllerUid=TUid::Null());

Description

Opens a video clip from a file.

This function opens a video clip from a file using an optionally specified plugin. If no controller plugin is specified, this function searches through a list of all available plugins and attempts to use each one until successful or the end of the list is reached.

Once the opening of the video clip is complete, successfully or otherwise, the callback function MVideoPlayerUtilityObserver::MvpuoOpenComplete() is called.

This function leaves if errors are encountered opening the specified video clip file, or in initialising a specified/unspecified controller plugin.

This function can leave with one of the specified error codes. Most open failures will however be reported through the MVideoPlayerUtilityObserver interface.

Parameters

const RFile &aFileName An open handle to a file containing the video clip TUid aControllerUid If specified, it will force the video player to use the controller with the given UID.

IMPORT_C void OpenFileL(const TMMSource &aSource, TUid aControllerUid=TUid::Null());

Description

Opens a video clip from a file.

This function opens a video clip from a file using an optionally specified plugin. If no controller plugin is specified, this function searches through a list of all available plugins and attempts to use each one until successful or the end of the list is reached.

Once the opening of the video clip is complete, successfully or otherwise, the callback function MVideoPlayerUtilityObserver::MvpuoOpenComplete() is called.

This function leaves if errors are encountered opening the specified video clip file, or in initialising a specified/unspecified controller plugin.

This function can leave with one of the specified error codes. Most open failures will however be reported through the MVideoPlayerUtilityObserver interface.

Parameters

const TMMSource &aSource A filename or an open handle to a file containing the video clip TUid aControllerUid If specified, it will force the video player to use the controller with the given UID.

IMPORT_C void OpenDesL(const TDesC8 &aDescriptor, TUid aControllerUid=TUid::Null());

Description

Opens a video clip contained in a descriptor.

This function opens a video clip contained as binary data in a descriptor using an optionally specified plugin. If no controller plugin is specified, this function searches through a list of all available plugins and attempts to use each one until successful or the end of the list is reached.

Once the opening of the video clip is complete, successfully or otherwise, the callback function MVideoPlayerUtilityObserver::MvpuoOpenComplete() is called.

This function can leave with one of the specified error codes. Most open failures will however be reported through the interface.

Parameters

const TDesC8 &aDescriptor The descriptor containing the video clip TUid aControllerUid If specified, it will force the video player to use the controller with the given UID.

IMPORT_C void OpenUrlL(const TDesC &aUrl, TInt aIapId=KUseDefaultIap, const TDesC8 &aMimeType=KNullDesC8, TUid aControllerUid=TUid::Null());

Description

Opens a video clip from a URL.

This function opens a video clip stored at a specified URL and identified by a MIME type. In addition a plugin can be specified if necessary. If no controller plugin is specified, this function searches through a list of all available plugins and attempts to use each one until successful or the end of the list is reached.

Once the opening of the video clip is complete, successfully or otherwise, the callback function MVideoPlayerUtilityObserver::MvpuoOpenComplete() is called.

This function can leave with one of the specified error codes. Most open failures will however be reported through the MVideoPlayerUtilityObserver interface.

Parameters

const TDesC &aUrl The URL of the video clip to open. TInt aIapId The Id of the internet access point to use const TDesC8 &aMimeType The MIME type associated with this video clip. This is used to determine the format of the video clip. TUid aControllerUid If specified, it will force the video player to use the controller with the given Uid.

IMPORT_C void Prepare();

Description

Prepares the video clip to be accessed.

A call to this method tells the loaded controller plugin to finalise its configuration and to prepare to start reading the video clip. It is not possible to play the video clip or query any of its properties (e.g. duration, meta data etc.) until this method has signalled its completion (successful or otherwise) via the callback MvpuoPrepareComplete.

IMPORT_C void Close();

Description

Closes the video clip.

IMPORT_C void Play();

Description

Begins playback of the initialised video sample at the current volume and priority levels.

When playing of the video sample is complete, successfully or otherwise, the callback function MVideoPlayerUtilityObserver::MvpuoPlayComplete() is called.

IMPORT_C void Play(const TTimeIntervalMicroSeconds &aStartPoint, const TTimeIntervalMicroSeconds &aEndPoint);

Description

Begins playback of the initialised video sample at the specified start and end points.

When playing of the video sample is complete, successfully or otherwise, the callback function MVideoPlayerUtilityObserver::MvpuoPlayComplete() is called.

Parameters

const TTimeIntervalMicroSeconds &aStartPoint The point at which to start playback. const TTimeIntervalMicroSeconds &aEndPoint The point at which to terminate playback.

IMPORT_C TInt Stop();

Description

Stops playback of the video sample as soon as is possible.

If the video sample is playing, playback is stopped as soon as possible and the callback function MVideoPlayerUtilityObserver::MvpuoPlayComplete() is called.

If playback is already complete, this function has no effect. In addition, under these circumstances the callback function MVideoPlayerUtilityObserver::MvpuoPlayComplete() is not called either.

The position is reset to the beginning of the file.

Return value

TInt An error code indicating if the function call was successful. KErrNone on success, otherwise another of the system-wide error codes.

IMPORT_C void PauseL();

Description

Video playback is paused. The current position is maintained and playback can be resumed by calling Play.

Capability:

MultimediaDD

A process requesting or using this method that has MultimediaDD capability will always have precedence over a process that does not have MultimediaDD.

IMPORT_C void SetPriorityL(TInt aPriority, TMdaPriorityPreference aPref);

Description

Sets the playback priority.

This is used to arbitrate between multiple objects simultaneously trying to accesses the sound hardware.

Parameters

TInt aPriority The priority level to apply, EMdaPriorityMin client can be interrupted by any other client, EMdaPriorityNormal client can only be interrupted by a client with a higher priority or EMdaPriorityMax client cannot be interrupted by other clients. TMdaPriorityPreference aPref The time and quality preferences to apply, enumerated in TMdaPriorityPreference.

IMPORT_C void PriorityL(TInt &aPriority, TMdaPriorityPreference &aPref) const;

Description

Get the current playback priority. This is used to arbitrate between simultaneous accesses of the sound hardware.

Parameters

TInt &aPriority On return, contains the priority level, EMdaPriorityMin client can be interrupted by any other client, EMdaPriorityNormal client can only be interrupted by a client with a higher priority or EMdaPriorityMax client cannot be interrupted by other clients. TMdaPriorityPreference &aPref On return, contains the time and quality preferences, enumerated in TMdaPriorityPreference.

IMPORT_C void SetDisplayWindowL(RWsSession &aWs, CWsScreenDevice &aScreenDevice, RWindowBase &aWindow, const TRect &aWindowRect, const TRect &aClipRect);

Description

Sets the display window. This is used to provide the video controller with an area of the display to render the current video frame.

Parameters

RWsSession &aWs The window server session ID. CWsScreenDevice &aScreenDevice The software device screen. RWindowBase &aWindow The window to display. const TRect &aWindowRect The dimensions of the display window. const TRect &aClipRect The area of the video clip to display in the window.

IMPORT_C void RegisterForVideoLoadingNotification(MVideoLoadingObserver &aCallback);

Description

Register to receive notifications of video clip loading/rebuffering.

When a video clip is being streamed in, it may require rebuffering from time to time. This function "switches on" callbacks that report the status of the rebuffering.

The two callbacks that can be sent are MVideoLoadingObserver::MvloLoadingStarted() and MVideoLoadingObserver::MvloLoadingComplete().

Parameters

MVideoLoadingObserver &aCallback The object to receive video loading notifications.

IMPORT_C void GetVideoLoadingProgressL(TInt &aPercentageComplete);

Description

Gets the progress of video clip loading/rebuffering.

Parameters

TInt &aPercentageComplete The percentage of loading/rebuffering complete. The parameter is zero if loading has not begun and 100 if loading has already completed.

IMPORT_C void GetFrameL(TDisplayMode aDisplayMode);

Description

Gets the current frame. The current frame is requested, and will be sent to the client asynchrynously via the MvpuoFrameReady callback.

Parameters

TDisplayMode aDisplayMode The display mode for the retrieved frame.

IMPORT_C void GetFrameL(TDisplayMode aDisplayMode, ContentAccess::TIntent aIntent);

Description

Gets the current frame. The current frame is requested, and will be sent to the client asynchrynously via the MvpuoFrameReady callback.

Parameters

TDisplayMode aDisplayMode The display mode for the retrieved frame. ContentAccess::TIntent aIntent The DRM Intent to pass to the controller.

IMPORT_C void RefreshFrameL();

Description

Requests the video controller to redraw the current frame.

IMPORT_C TReal32 VideoFrameRateL() const;

Description

Returns the video frame rate in frames/second.

Return value

TReal32 The video frame rate (frames/second).

IMPORT_C void SetVideoFrameRateL(TReal32 aFramesPerSecond);

Description

Sets the video frame rate.

Parameters

TReal32 aFramesPerSecond The number of frames per second to request.

IMPORT_C void VideoFrameSizeL(TSize &aSize) const;

Description

Gets the video frame size.

Parameters

TSize &aSize The video frame size

IMPORT_C const TDesC8 &VideoFormatMimeType() const;

Description

Returns the video format's MIME type.

Return value

const TDesC8 & The video clip's MIME type.

IMPORT_C TInt VideoBitRateL() const;

Description

Returns the video bit rate.

Return value

TInt The video bit rate in bits/second.

IMPORT_C TInt AudioBitRateL() const;

Description

Returns the audio bit rate in bits/second.

Return value

TInt The audio bit rate (bits/second).

IMPORT_C TFourCC AudioTypeL() const;

Description

Returns the codec used for the audio component of the video clip.

Return value

TFourCC The four character code representing the audio codec.

IMPORT_C TBool AudioEnabledL() const;

Description

Returns whether the current clip has an audio stream.

Return value

TBool Boolean indication the presence of an audio stream. ETrue if an audio track is present, otherwise EFalse.

IMPORT_C void SetPositionL(const TTimeIntervalMicroSeconds &aPosition);

Description

Sets the position within the video clip from where to start playback.

Parameters

const TTimeIntervalMicroSeconds &aPosition Position from start of clip in microseconds.

IMPORT_C TTimeIntervalMicroSeconds PositionL() const;

Description

Returns the current playback position.

Return value

TTimeIntervalMicroSeconds The current position from the start of the clip in microseconds.

IMPORT_C TTimeIntervalMicroSeconds DurationL() const;

Description

Returns the duration of video clip in mircoseconds.

Return value

TTimeIntervalMicroSeconds The duration of clip in microseconds.

IMPORT_C void SetVolumeL(TInt aVolume);

Description

Sets the playback volume for the audio track of the video clip.

The volume can be changed before or during playback and is effective immediately. The volume can be set to any value between zero (mute) and the maximum permissible volume (determined using MaxVolume()).

To determine if the current video clip contains an audio track, use AudioEnabledL().

Parameters

TInt aVolume The volume, between 0 and MaxVolume().

IMPORT_C TInt Volume() const;

Description

Returns the current playback volume for the audio track of the video clip.

Return value

TInt A value between 0 (mute) and the maximum volume returned by MaxVolume().

IMPORT_C TInt MaxVolume() const;

Description

Returns an integer representing the maximum volume that the audio track can support.

This is the maximum value that can be passed to SetVolumeL(). This value is platform independent, but is always greater than or equal to one.

Return value

TInt The naximum playback volume.

IMPORT_C void SetBalanceL(TInt aBalance);

Description

Sets the current playback balance for the audio track of the video clip.

The balance can be any value between KMMFBalanceMaxLeft and KMMFBalanceMaxRight, the default value being KMMFBalanceCenter.

Parameters

TInt aBalance The balance value to set.

IMPORT_C TInt Balance() const;

Description

Returns the current balance setting for the audio track of the video clip.

Return value

TInt A balance value between KMMFBalanceMaxLeft and KMMFBalanceMaxRight.

IMPORT_C void SetRotationL(TVideoRotation aRotation);

Description

Rotates the video image on the screen.

Parameters

TVideoRotation aRotation The desired rotation to apply in 90 degree increments.

IMPORT_C TVideoRotation RotationL() const;

Description

Query the rotation that is currently applied to the video image.

Return value

TVideoRotation The applied rotation

IMPORT_C void SetScaleFactorL(TReal32 aWidthPercentage, TReal32 aHeightPercentage, TBool aAntiAliasFiltering);

Description

Scales the video image to a specified percentage of its original size.

Parameters

TReal32 aWidthPercentage The percentage (100 = original size) to be used to scale the width of the video image TReal32 aHeightPercentage The percentage (100 = original size) to be used to scale the height of the video image. If this is not equal to aWidthPercentage then the image may be distorted. TBool aAntiAliasFiltering A boolean specifying if anti-aliasing should be used. True if anti-aliasing filtering should be used. If the plugin does not support this kind of processing, this value will be ignored.

IMPORT_C void GetScaleFactorL(TReal32 &aWidthPercentage, TReal32 &aHeightPercentage, TBool &aAntiAliasFiltering) const;

Description

Gets the scale factor currently applied to the video image.

Parameters

TReal32 &aWidthPercentage On function return, contains the current scaling percentage applied to the width of the video image (100 = original size). TReal32 &aHeightPercentage On function return, contains the current scaling percentage applied to the height of the of the video image (100 = original size). TBool &aAntiAliasFiltering The boolean specifying if anit-aliasing is being used.

IMPORT_C void SetCropRegionL(const TRect &aCropRegion);

Description

Selects a region of the video image to be displayed.

Parameters

const TRect &aCropRegion The dimensions of the crop region, relative to the video image.

IMPORT_C void GetCropRegionL(TRect &aCropRegion) const;

Description

Gets the crop region currently applied to the image.

Parameters

TRect &aCropRegion The dimensions of the crop region, relative to the video image. If no crop region has been applied, the full dimensions of the video image will be returned.

IMPORT_C TInt NumberOfMetaDataEntriesL() const;

Description

Returns the number of meta data entries associated with this clip.

Return value

TInt The number of meta data entries.

IMPORT_C CMMFMetaDataEntry *MetaDataEntryL(TInt aIndex) const;

Description

Returns a meta data entry from the clip.

Parameters

TInt aIndex The index of the meta data entry to retrieve.

Return value

CMMFMetaDataEntry * The metadata entry requested.

IMPORT_C const CMMFControllerImplementationInformation &ControllerImplementationInformationL();

Description

Returns the controller implementation information associated with the current controller.

Return value

const CMMFControllerImplementationInformation & The controller implementation structure associated with the controller.

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

Description

Sends a synchronous custom command to the controller.

Parameters

const TMMFMessageDestinationPckg &aDestination The destination of the message, consisting of the UID of the interface of this message. TInt aFunction The function number to indicate which function is to be called on the interface defined in the aDestination parameter. const TDesC8 &aDataTo1 A reference to the first chunk of data to be copied to the controller framework. The exact contents of the data are dependent on the interface being called. Can be KNullDesC8. const TDesC8 &aDataTo2 A reference to the second chunk of data to be copied to the controller framework. The exact contents of the data are dependent on the interface being called. Can be KNullDesC8. TDes8 &aDataFrom A reference to an area of memory to which the controller framework will write any data to be passed back to the client. Can't be KNullDesC8.

Return value

TInt The result of the request. The exact range of values is dependent on the interface.

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

Description

Sends a synchronous custom command to the controller.

Parameters

const TMMFMessageDestinationPckg &aDestination The destination of the message, consisting of the uid of the interface of this message. TInt aFunction The function number to indicate which function is to be called on the interface defined in the aDestination parameter. const TDesC8 &aDataTo1 A reference to the first chunk of data to be copied to the controller framework. The exact contents of the data are dependent on the interface being called. Can be KNullDesC8. const TDesC8 &aDataTo2 A reference to the second chunk of data to be copied to the controller framework. The exact contents of the data are dependent on the interface being called. Can be KNullDesC8.

Return value

TInt The result of the request. The exact range of values is dependent on the interface.

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

Description

Sends an asynchronous custom command to the controller.

Note: This method will return immediately. The RunL of the active object owning the aStatus parameter will be called when the command is completed by the controller framework.

Parameters

const TMMFMessageDestinationPckg &aDestination The destination of the message, consisting of the uid of the interface of this message. TInt aFunction The function number to indicate which function is to be called on the interface defined in the aDestination parameter. const TDesC8 &aDataTo1 A reference to the first chunk of data to be copied to the controller framework. The exact contents of the data are dependent on the interface being called. Can be KNullDesC8. const TDesC8 &aDataTo2 A reference to the second chunk of data to be copied to the controller framework. The exact contents of the data are dependent on the interface being called. Can be KNullDesC8. TDes8 &aDataFrom A reference to an area of memory to which the controller framework will write any data to be passed back to the client. Can't be KNullDesC8. TRequestStatus &aStatus The TRequestStatus of an active object. This will contain the result of the request on completion. The exact range of result values is dependent on the interface.

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

Description

Send a asynchronous custom command to the controller.

Note: This method will return immediately. The RunL of the active object owning the aStatus parameter will be called when the command is completed by the controller framework.

Parameters

const TMMFMessageDestinationPckg &aDestination The destination of the message, consisting of the uid of the interface of this message. TInt aFunction The function number to indicate which function is to be called on the interface defined in the aDestination parameter. const TDesC8 &aDataTo1 A reference to the first chunk of data to be copied to the controller framework. The exact contents of the data are dependent on the interface being called. Can be KNullDesC8. const TDesC8 &aDataTo2 A reference to the second chunk of data to be copied to the controller framework. The exact contents of the data are dependent on the interface being called. Can be KNullDesC8. TRequestStatus &aStatus The TRequestStatus of an active object. This will contain the result of the request on completion. The exact range of result values is dependent on the interface.

IMPORT_C MMMFDRMCustomCommand *GetDRMCustomCommand();

Description

Gets a controller's DRM custom command implementation.

Return value

MMMFDRMCustomCommand * A pointer to a controller's DRM custom command implementation, or NULL if the controller does not support it.

IMPORT_C void StopDirectScreenAccessL();

Description

Enables a client application to stop the video player from using direct screen access (DSA).

This function leaves if errors are encountered when trying to stop DSA.

IMPORT_C void StartDirectScreenAccessL();

Description

Enables a client application to start the video player using direct screen access (DSA).

This function leaves if errors are encountered when trying to start DSA.

IMPORT_C TInt RegisterAudioResourceNotification(MMMFAudioResourceNotificationCallback &aCallback, TUid aNotificationEventUid, const TDesC8 &aNotificationRegistrationData=KNullDesC8);

Description

Registers for notification, when audio resource is available.

Parameters

MMMFAudioResourceNotificationCallback &aCallback Observer interface for audio resource notification event TUid aNotificationEventUid The Event for which the client registers. const TDesC8 &aNotificationRegistrationData Data specific to notification registration.This has been reserved for future use and its value should be NULL.

Return value

TInt An error code indicating if the registration is successful. KErrNone on success, otherwise another of the system-wide error codes.

IMPORT_C TInt CancelRegisterAudioResourceNotification(TUid aNotificationEventId);

Description

Cancels the registration for audio resource notification.

Parameters

TUid aNotificationEventId The Event to be cancellled.

Return value

TInt An error code indicating if the cancellation is successful. KErrNone on success, otherwise another of the system-wide error codes.

IMPORT_C TInt WillResumePlay();

Description

Waits for the client to resume the play even after the default timer expires. Unless the client completes the play no other client gets notification.

Return value

TInt An error code indicating if the function call is successful. KErrNone on success, otherwise another of the system-wide error codes.

IMPORT_C TInt SetInitScreenNumber(TInt aScreenNumber);

Description

Sets the initial screen to be used for the video display.

Parameters

TInt aScreenNumber The screen number of the device.

Return value

TInt KErrNotSupported if the secondary screen display is not supported in Multimedia Framework. KErrNone on success.