CVideoPlayerUtility Class Reference

#include <videoplayer.h>

Link against: mediaclientvideo.lib

class CVideoPlayerUtility : public CBase

Inherits from

CVideoPlayerUtility

Public Member Functions
	~CVideoPlayerUtility()
IMPORT_C TInt	AudioBitRateL()
IMPORT_C TBool	AudioEnabledL()
IMPORT_C TFourCC	AudioTypeL()
IMPORT_C TInt	Balance()
IMPORT_C TInt	CancelRegisterAudioResourceNotification(TUid)
IMPORT_C void	Close()
IMPORT_C const CMMFControllerImplementationInformation &	ControllerImplementationInformationL()
IMPORT_C void	CustomCommandAsync(const TMMFMessageDestinationPckg &, TInt, const TDesC8 &, const TDesC8 &, TDes8 &, TRequestStatus &)
IMPORT_C void	CustomCommandAsync(const TMMFMessageDestinationPckg &, TInt, const TDesC8 &, const TDesC8 &, TRequestStatus &)
IMPORT_C TInt	CustomCommandSync(const TMMFMessageDestinationPckg &, TInt, const TDesC8 &, const TDesC8 &, TDes8 &)
IMPORT_C TInt	CustomCommandSync(const TMMFMessageDestinationPckg &, TInt, const TDesC8 &, const TDesC8 &)
IMPORT_C TTimeIntervalMicroSeconds	DurationL()
IMPORT_C void	GetCropRegionL(TRect &)
IMPORT_C MMMFDRMCustomCommand *	GetDRMCustomCommand()
IMPORT_C void	GetFrameL(TDisplayMode)
IMPORT_C void	GetFrameL(TDisplayMode, ContentAccess::TIntent)
IMPORT_C void	GetPlayRateCapabilitiesL(TVideoPlayRateCapabilities &)
IMPORT_C void	GetScaleFactorL(TReal32 &, TReal32 &, TBool &)
IMPORT_C void	GetVideoLoadingProgressL(TInt &)
IMPORT_C TInt	MaxVolume()
IMPORT_C CMMFMetaDataEntry *	MetaDataEntryL(TInt)
IMPORT_C CVideoPlayerUtility *	NewL(MVideoPlayerUtilityObserver &, TInt, TInt, RWsSession &, CWsScreenDevice &, RWindowBase &, const TRect &, const TRect &)
IMPORT_C TInt	NumberOfMetaDataEntriesL()
IMPORT_C void	OpenDesL(const TDesC8 &, TUid)
IMPORT_C void	OpenFileL(const TDesC &, TUid)
IMPORT_C void	OpenFileL(const RFile &, TUid)
IMPORT_C void	OpenFileL(const TMMSource &, TUid)
IMPORT_C void	OpenUrlL(const TDesC &, TInt, const TDesC8 &, TUid)
IMPORT_C void	PauseL()
IMPORT_C void	Play()
IMPORT_C void	Play(const TTimeIntervalMicroSeconds &, const TTimeIntervalMicroSeconds &)
IMPORT_C TInt	PlayVelocityL()
IMPORT_C TTimeIntervalMicroSeconds	PositionL()
IMPORT_C void	Prepare()
IMPORT_C void	PriorityL(TInt &, TMdaPriorityPreference &)
IMPORT_C void	RefreshFrameL()
IMPORT_C TInt	RegisterAudioResourceNotification(MMMFAudioResourceNotificationCallback &, TUid, const TDesC8 &)
IMPORT_C void	RegisterForVideoLoadingNotification(MVideoLoadingObserver &)
IMPORT_C TVideoRotation	RotationL()
IMPORT_C void	SetAudioEnabledL(TBool)
IMPORT_C void	SetAutoScaleL(TAutoScaleType)
IMPORT_C void	SetAutoScaleL(TAutoScaleType, TInt, TInt)
IMPORT_C void	SetBalanceL(TInt)
IMPORT_C void	SetCropRegionL(const TRect &)
IMPORT_C void	SetDisplayWindowL(RWsSession &, CWsScreenDevice &, RWindowBase &, const TRect &, const TRect &)
IMPORT_C void	SetExternalDisplaySwitchingL(TInt, TBool)
IMPORT_C TInt	SetInitScreenNumber(TInt)
IMPORT_C void	SetPlayVelocityL(TInt)
IMPORT_C void	SetPositionL(const TTimeIntervalMicroSeconds &)
IMPORT_C void	SetPriorityL(TInt, TInt)
IMPORT_C void	SetRotationL(TVideoRotation)
IMPORT_C void	SetScaleFactorL(TReal32, TReal32, TBool)
IMPORT_C void	SetVideoEnabledL(TBool)
IMPORT_C void	SetVideoFrameRateL(TReal32)
IMPORT_C void	SetVolumeL(TInt)
IMPORT_C void	StartDirectScreenAccessL()
IMPORT_C void	StepFrameL(TInt)
IMPORT_C TInt	Stop()
IMPORT_C void	StopDirectScreenAccessL()
IMPORT_C TInt	VideoBitRateL()
IMPORT_C TBool	VideoEnabledL()
IMPORT_C const TDesC8 &	VideoFormatMimeType()
IMPORT_C TReal32	VideoFrameRateL()
IMPORT_C void	VideoFrameSizeL(TSize &)
IMPORT_C TInt	Volume()
IMPORT_C TInt	WillResumePlay()

Inherited Functions
	CBase::CBase()
	CBase::Delete(CBase *)
	CBase::Extension_(TUint,TAny &,TAny )
	CBase::operator new(TUint)
	CBase::operator new(TUint,TAny *)
	CBase::operator new(TUint,TLeave)
	CBase::operator new(TUint,TLeave,TUint)
	CBase::operator new(TUint,TUint)
	CBase::~CBase()

Detailed 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.

Since: 7.0s

Constructor & Destructor Documentation

~CVideoPlayerUtility ( )

~CVideoPlayerUtility

(

)

Destructor. Closes any open video clips and frees any resources held by the Video Player.

Since: 7.0s

Member Function Documentation

AudioBitRateL ( )

IMPORT_C TInt

AudioBitRateL

(

)

const

Returns the audio bit rate in bits/second.

Since: 7.0s

Returns: The audio bit rate (bits/second).

AudioEnabledL ( )

IMPORT_C TBool

AudioEnabledL

(

)

const

Returns whether the current clip has an audio stream and audio playback is enabled. This method will return EFalse if the clip does no have an audio track or if audio playback has been disabled with SetAudioEnabledL().

Since: 7.0s

Returns: ETrue if an audio track is present and audio playback is enabled, otherwise EFalse.

AudioTypeL ( )

IMPORT_C TFourCC

AudioTypeL

(

)

const

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

Since: 7.0s

Returns: The four character code representing the audio codec.

Balance ( )

IMPORT_C TInt

Balance

(

)

const

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

Since: 7.0s

Returns: A balance value between KMMFBalanceMaxLeft and KMMFBalanceMaxRight.

CancelRegisterAudioResourceNotification ( TUid )

IMPORT_C TInt

CancelRegisterAudioResourceNotification

(

TUid

aNotificationEventId

)

Cancels the registration for audio resource notification.

Parameter	Description
aNotificationEventId	The Event to be cancellled.

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

Close ( )

IMPORT_C void

(

)

Closes the video clip.

Since: 7.0s

ControllerImplementationInformationL ( )

IMPORT_C const CMMFControllerImplementationInformation &

ControllerImplementationInformationL

(

)

Returns the controller implementation information associated with the current controller.

Since: 7.0s

Returns: The controller implementation structure associated with the controller.

CustomCommandAsync ( const TMMFMessageDestinationPckg &, TInt, const TDesC8 &, const TDesC8 &, TDes8 &, TRequestStatus & )

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

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.

Since: 7.0s

Parameter	Description
aDestination	The destination of the message, consisting of the uid of the interface of this message.
aFunction	The function number to indicate which function is to be called on the interface defined in the aDestination parameter.
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.
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.
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.
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.

CustomCommandAsync ( const TMMFMessageDestinationPckg &, TInt, const TDesC8 &, const TDesC8 &, TRequestStatus & )

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

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.

Since: 7.0s

Parameter	Description
aDestination	The destination of the message, consisting of the uid of the interface of this message.
aFunction	The function number to indicate which function is to be called on the interface defined in the aDestination parameter.
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.
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.
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.

CustomCommandSync ( const TMMFMessageDestinationPckg &, TInt, const TDesC8 &, const TDesC8 &, TDes8 & )

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

Sends a synchronous custom command to the controller.

Since: 7.0s

Parameter	Description
aDestination	The destination of the message, consisting of the UID of the interface of this message.
aFunction	The function number to indicate which function is to be called on the interface defined in the aDestination parameter.
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.
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.
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.

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

CustomCommandSync ( const TMMFMessageDestinationPckg &, TInt, const TDesC8 &, const TDesC8 & )

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

Sends a synchronous custom command to the controller.

Since: 7.0s

Parameter	Description
aDestination	The destination of the message, consisting of the uid of the interface of this message.
aFunction	The function number to indicate which function is to be called on the interface defined in the aDestination parameter.
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.
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.

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

DurationL ( )

IMPORT_C TTimeIntervalMicroSeconds

DurationL

(

)

const

Returns the duration of video clip in mircoseconds.

Since: 7.0s

Returns: The duration of clip in microseconds.

GetCropRegionL ( TRect & )

IMPORT_C void

GetCropRegionL

(

TRect &

aCropRegion

)

const

Gets the crop region currently applied to the image.

Since: 7.0s

Parameter	Description
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.

GetDRMCustomCommand ( )

IMPORT_C MMMFDRMCustomCommand *

GetDRMCustomCommand

(

)

Gets a controller's DRM custom command implementation.

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

GetFrameL ( TDisplayMode )

IMPORT_C void

GetFrameL

(

TDisplayMode

aDisplayMode

)

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

Since: 7.0s

Parameter	Description
aDisplayMode	The display mode for the retrieved frame.

GetFrameL ( TDisplayMode, ContentAccess::TIntent )

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

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

Parameter	Description
aDisplayMode	The display mode for the retrieved frame.
aIntent	The DRM Intent to pass to the controller.

GetPlayRateCapabilitiesL ( TVideoPlayRateCapabilities & )

IMPORT_C void

GetPlayRateCapabilitiesL

(

TVideoPlayRateCapabilities &

aCapabilities

)

const

Queries the current playback rate capabilities. The capabilities describe whether fast forward, reverse playback, slow motion, or step backward or forward is possible. The capabilities may depend on the controller implementation and the video clip. Additionally, only normal-speed forward playback is typically possible in streamed playback.

This function quits or exits leaving any of the system wide error codes. Common error codes are listed below.

Pre-condition: The video clip has been opened

leave: KErrNotReady The video clip has not yet been opened

Parameter	Description
aCapabilities	Playback rate capabilities

GetScaleFactorL ( TReal32 &, TReal32 &, TBool & )

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

Gets the scale factor currently applied to the video image.

Since: 7.0s

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

GetVideoLoadingProgressL ( TInt & )

IMPORT_C void

GetVideoLoadingProgressL

(

TInt &

aPercentageComplete

)

Gets the progress of video clip loading/rebuffering.

Since: 7.0s

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

MaxVolume ( )

IMPORT_C TInt

MaxVolume

(

)

const

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.

Since: 7.0s

Returns: The naximum playback volume.

MetaDataEntryL ( TInt )

IMPORT_C CMMFMetaDataEntry *

MetaDataEntryL

(

TInt

aIndex

)

const

Returns a meta data entry from the clip.

Since: 7.0s

Parameter	Description
aIndex	The index of the meta data entry to retrieve.

NewL ( MVideoPlayerUtilityObserver &, TInt, TInt, RWsSession &, CWsScreenDevice &, RWindowBase &, const TRect &, const TRect & )

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

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

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

Since: 7.0s

Note: The Priority Value and Priority Preference are used primarily when deciding what to do when several audio clients attempt to play or record simultaneously. In addition to the Priority Value and Preference, the adaptation may consider other parameters such as the SecureId and Capabilities of the client process. Whatever, the decision as to what to do in such situations is up to the audio adaptation, and may vary between different phones. Portable applications are advised not to assume any specific behaviour.

Parameter	Description
aObserver	A client class to receive notifications from the video player.
aPriority	The Priority Value - 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.
aPref	The Priority Preference - an additional audio policy parameter. The suggested default is EMdaPriorityPreferenceNone. Further values are given by TMdaPriorityPreference, and additional values may be supported by given phones and/or platforms, but should not be depended upon by portable code.
aWs	The window server session id.
aScreenDevice	The software device screen.
aWindow	The display window.
aScreenRect	The dimensions of the display window.
aClipRect	The area of the video clip to display in the window.

Returns: A pointer to the new video player utility object.

NumberOfMetaDataEntriesL ( )

IMPORT_C TInt

NumberOfMetaDataEntriesL

(

)

const

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

Since: 7.0s

Returns: The number of meta data entries.

OpenDesL ( const TDesC8 &, TUid )

IMPORT_C void	OpenDesL	(	const TDesC8 &	aDescriptor,
			TUid	aControllerUid = KNullUid
		)

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.

From Symbian release v9.5 onwards, this function will enable graphics surface use if the controller supports it. If this function is called through an instance of the derived class CVideoPlayerUtility2 and the controller doesn't support graphics surfaces, it fails with KErrNotSupported.

Since: 7.0s

Parameter	Description
aDescriptor	The descriptor containing the video clip
aControllerUid	If specified, it will force the video player to use the controller with the given UID.

OpenFileL ( const TDesC &, TUid )

IMPORT_C void	OpenFileL	(	const TDesC &	aFileName,
			TUid	aControllerUid = KNullUid
		)

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.

Since: 7.0s

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

OpenFileL ( const RFile &, TUid )

IMPORT_C void	OpenFileL	(	const RFile &	aFileName,
			TUid	aControllerUid = KNullUid
		)

Opens a video clip from a file.

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.

Since: 7.0s

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

OpenFileL ( const TMMSource &, TUid )

IMPORT_C void	OpenFileL	(	const TMMSource &	aSource,
			TUid	aControllerUid = KNullUid
		)

Opens a video clip from a file.

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.

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

OpenUrlL ( const TDesC &, TInt, const TDesC8 &, TUid )

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

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.

Since: 7.0s

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

PauseL ( )

IMPORT_C void

PauseL

(

)

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

Since: 7.0s

Play ( )

IMPORT_C void

Play

(

)

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.

Since: 7.0s

Play ( const TTimeIntervalMicroSeconds &, const TTimeIntervalMicroSeconds & )

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

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.

Since: 7.0s

Parameter	Description
aStartPoint	The point at which to start playback.
aEndPoint	The point at which to terminate playback.

PlayVelocityL ( )

IMPORT_C TInt

PlayVelocityL

(

)

const

Returns the current playback velocity. If setting play velocity is not supported or velocity is not set this will return default play velocity 100 corresponding to normal playback.

If implementation is not supporting the velocity set with SetPlayVelocityL it will default to the nearest velocity. In this case this API will return the value it has defaulted to.

If an error occurs, this function leaves with any of the system wide error codes. Common error codes are listed below.

Pre-condition: Playback has been started, but may be paused.

leave: KErrNotReady Playback has not yet been started

Returns: The current playback velocity as a percentage relative to the normal video clip speed.

PositionL ( )

IMPORT_C TTimeIntervalMicroSeconds

PositionL

(

)

const

Returns the current playback position.

Since: 7.0s

Returns: The current position from the start of the clip in microseconds.

Prepare ( )

IMPORT_C void

Prepare

(

)

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.

Since: 7.0s

PriorityL ( TInt &, TMdaPriorityPreference & )

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

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

Since: 7.0s

Parameter	Description
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.
aPref	On return, contains the time and quality preferences, enumerated in TMdaPriorityPreference.

RefreshFrameL ( )

IMPORT_C void

RefreshFrameL

(

)

Requests the video controller to redraw the current frame.

Since: 7.0s

RegisterAudioResourceNotification ( MMMFAudioResourceNotificationCallback &, TUid, const TDesC8 & )

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

Registers for notification, when audio resource is available.

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

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

RegisterForVideoLoadingNotification ( MVideoLoadingObserver & )

IMPORT_C void

RegisterForVideoLoadingNotification

(

MVideoLoadingObserver &

aCallback

)

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().

Since: 7.0s

Parameter	Description
aCallback	The object to receive video loading notifications.

RotationL ( )

IMPORT_C TVideoRotation

RotationL

(

)

const

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

Since: 7.0s

SetAudioEnabledL ( TBool )

IMPORT_C void

SetAudioEnabledL

(

TBool

aAudioEnabled

)

Enables or disables audio playback. This function is used to disable audio playback in a video clip to play only the video track. By default audio playback is always enabled if the clip has an audio track.

This method can be called after the video clip has been opened, but only before calling Prepare().

This function quits or exits leaving any of the system wide error codes. Common error codes are listed below.

Pre-condition: The video clip has been opened by the client and Prepare() has not been called.

leave: KErrNotSupported This method is not supported -- audio playback is always enabled

leave: KErrNotReady The clip has not been opened or the client has already called Prepare().

Parameter	Description
aAudioEnabled	ETrue to enable audio playback, EFalse to disable

SetAutoScaleL ( TAutoScaleType )

IMPORT_C void

SetAutoScaleL

(

TAutoScaleType

aScaleType

)

Set video automatic scaling. When automatic scaling is active, the video picture is scaled automatically to match the video window, based on the scaling type. This variant of SetAutoScaleL() will always center the picture in the window.

Calling SetAutoScaleL() will override any scaling factors set with SetScaleFactorL(). Calling SetScaleFactorL() will disable automatic scaling.

Not all video controllers support automatic scaling.

This function quits or exits leaving any of the system wide error codes. Common error codes are listed below.

Pre-condition: The video clip has been opened by the client

leave: KErrNotSupported Automatic scaling is not supported

Parameter	Description
aScaleType	Automatic scaling type

SetAutoScaleL ( TAutoScaleType, TInt, TInt )

IMPORT_C void	SetAutoScaleL	(	TAutoScaleType	aScaleType,
			TInt	aHorizPos,
			TInt	aVertPos
		)

Set video automatic scaling. When automatic scaling is active, the video picture is scaled automatically to match the video window, based on the scaling type, and positioned according to the parameters.

Calling SetAutoScaleL() will override any scaling factors set with SetScaleFactorL(). Calling SetScaleFactorL() will disable automatic scaling.

Not all video controller support automatic scaling.

This function quits or exits leaving any of the system wide error codes. Common error codes are listed below.

Pre-condition: The video clip has been opened by the client.

leave: KErrNotSupported Automatic scaling is not supported

Parameter	Description
aScaleType	Automatic scaling type
aHorizPos	Video picture horizontal position, relative to the video window. The value can be either a pixel offset (positive or negative) from the top left corner of the window to the top left corner of the picture, or an alignment constant from enum THorizontalAlign.
aVertPos	Video picture vertical position, relative to the video window. The value can be either a pixel offset (positive or negative) from the top left corner of the window to the top left corner of the picture, or an alignment constant from enum TVerticalAlign.

SetBalanceL ( TInt )

IMPORT_C void

SetBalanceL

(

TInt

aBalance

)

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.

Since: 7.0s

Parameter	Description
aBalance	The balance value to set.

SetCropRegionL ( const TRect & )

IMPORT_C void

SetCropRegionL

(

const TRect &

aCropRegion

)

Selects a region of the video image to be displayed.

Since: 7.0s

SetDisplayWindowL ( RWsSession &, CWsScreenDevice &, RWindowBase &, const TRect &, const TRect & )

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

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

From Symbian release 9.5 onwards this method is not supported when called on an instance of CVideoPlayerUtility2, and will always leave with KErrNotSupported.

Since: 7.0s

Parameter	Description
aWs	The window server session ID.
aScreenDevice	The software device screen.
aWindow	The window to display.
aWindowRect	The dimensions of the display window.
aClipRect	The area of the video clip to display in the window.

SetExternalDisplaySwitchingL ( TInt, TBool )

IMPORT_C void	SetExternalDisplaySwitchingL	(	TInt	aDisplay,
			TBool	aControl
		)

When enabled sets automatic switching of surface to/from external display when it is connected/disconnected from the device.

Automatic switching is enabled by default, but only if the client thread that created this utility has an Active Scheduler installed and the device supports external display switching.

To use this function the client thread must have an Active Scheduler installed otherwise it will leave with KErrNotReady.

leave: KErrNotSupported Device does not support external displays

leave: KErrNotReady CActiveScheduler is not installed

Parameter	Description
aDisplay	Display id of display to enable external switching for.
aControl	ETrue to enable. EFalse to disable.

SetInitScreenNumber ( TInt )

IMPORT_C TInt

SetInitScreenNumber

(

TInt

aScreenNumber

)

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

From Symbian release 9.5 onwards this method is not supported when called on an instance of CVideoPlayerUtility2, and will always leave with KErrNotSupported.

Parameter	Description
aScreenNumber	The screen number of the device.

Returns: KErrNotSupported if the secondary screen display is not supported in Multimedia Framework or from Symbian release 9.5 onwards when called on an instance of CVideoPlayerUtility2. KErrNone on success.

SetPlayVelocityL ( TInt )

IMPORT_C void

SetPlayVelocityL

(

TInt

aVelocity

)

Set video playback velocity relative to the normal video clip speed. This method can be used for fast forward, rewind, and slow-motion playback, depending on the capabilities of the underlying play-controller implementation and the characteristics of the video clip. Velocity set in this call will take effect immediately. Additionally, playback velocity cannot be changed for streamed video. Use GetPlayRateCapabilitiesL() to determine what playback modes are available.

Note that due to performance reasons, it may not be possible to perform fast forward or rewind at the requested speed. If that happens, the play-controller will use the nearest available velocity. This is not considered an error and the method will not leave. User can query velocity in effect by calling PlayVelocityL().

The default playback velocity is 100. Play velocity is persistent across stop play calls on utility. That is SetPlayVelocityL(),call StopL(),then PlayL() will play with the velocity set in most recent call. On opening different file the velocity will default to 100.

This function quits or exits leaving any of the system wide error codes. Common error codes are listed below.

Pre-condition: Playback has been started, but may be paused.

leave: KErrNotSupported The requested playback velocity is not supported.

leave: KErrNotReady Playback has not yet been started

Parameter	Description
aVelocity	Playback velocity as a percentage relative to the normal video clip speed. Use 100 for normal-speed forward playback and negative value for reverse. Values above 100 and below 0 correspond to fast forward and rewind respectively, while values 1 to 100 represent slow-motioned playback.

SetPositionL ( const TTimeIntervalMicroSeconds & )

IMPORT_C void

SetPositionL

(

const TTimeIntervalMicroSeconds &

aPosition

)

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

Since: 7.0s

Parameter	Description
aPosition	Position from start of clip in microseconds.

SetPriorityL ( TInt, TInt )

IMPORT_C void	SetPriorityL	(	TInt	aPriority,
			TInt	aPref
		)

Sets the playback priority.

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

SetRotationL ( TVideoRotation )

IMPORT_C void

SetRotationL

(

TVideoRotation

aRotation

)

Rotates the video image on the screen.

SetScaleFactorL ( TReal32, TReal32, TBool )

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

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

Since: 7.0s

SetVideoEnabledL ( TBool )

IMPORT_C void

SetVideoEnabledL

(

TBool

aVideoEnabled

)

Enables or disables video playback. This function is used to disable video playback in a video clip to play only the audio track. By default video playback is always enabled if the clip has a video track.

This method can be called after the video clip has been opened, but only before calling Prepare().

This function quits or exits leaving any of the system wide error codes. Common error codes are listed below.

Pre-condition: The video clip has been opened by the client and Prepare() has not been called.

leave: KErrNotSupported This method is not supported -- video playback is always enabled.

leave: KErrNotReady The clip has not been opened or the client has already called Prepare().

Parameter	Description
aVideoEnabled	ETrue to enable video playback, EFalse to disable

SetVideoFrameRateL ( TReal32 )

IMPORT_C void

SetVideoFrameRateL

(

TReal32

aFramesPerSecond

)

Sets the video frame rate.

Since: 7.0s

Parameter	Description
aFramesPerSecond	The number of frames per second to request.

SetVolumeL ( TInt )

IMPORT_C void

SetVolumeL

(

TInt

aVolume

)

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().

Since: 7.0s

Parameter	Description
aVolume	The volume, between 0 and MaxVolume().

StartDirectScreenAccessL ( )

IMPORT_C void

StartDirectScreenAccessL

(

)

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

From Symbian release 9.5 onwards this method is not supported when called on an instance of CVideoPlayerUtility2, and will always leave with KErrNotSupported.

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

StepFrameL ( TInt )

IMPORT_C void

StepFrameL

(

TInt

aStep

)

Steps the current video playback position forward or backward by a number of frames. Frame step is only available when playback is paused.

Support for frame stepping may depend on the underlying play-controller implementation and the video clip open. Additionally, frame step is typically not available in streamed playback. Use GetPlayRateCapabilitiesL() to query if frame step is currently possible. Application may check the value of the current positon after stepping through several frames by calling PositionL() API.

Implementations may not be able to step exactly the number of frames requested, especially when stepping backwards. If this happens, the play-controller will step to a frame close to the one requested. This is not considered an error.

This function quits or exits leaving any of the system wide error codes. Common error codes are listed below.

Pre-condition: Playback has been started and is currently paused. That means this API can be called only in paused state.

leave: KErrNotSupported Frame step is not supported. Note that some implementations may support step forward but not step backward.

leave: KErrNotReady Playback has not yet been started or is not in paused state.

Parameter	Description
aStep	The number of frames to step. Use positive values for stepping forward and negative values for stepping back.

Stop ( )

IMPORT_C TInt

Stop

(

)

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

If the video sample is playing, playback is stopped as soon as possible.

If playback is already complete, this function has no effect.

The position is reset to the beginning of the file.

Since: 7.0s

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

StopDirectScreenAccessL ( )

IMPORT_C void

StopDirectScreenAccessL

(

)

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

From Symbian release 9.5 onwards this method is not supported when called on an instance of CVideoPlayerUtility2, and will always leave with KErrNotSupported.

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

VideoBitRateL ( )

IMPORT_C TInt

VideoBitRateL

(

)

const

Returns the video bit rate.

Since: 7.0s

Returns: The video bit rate in bits/second.

VideoEnabledL ( )

IMPORT_C TBool

VideoEnabledL

(

)

const

Queries whether video playback is currently enabled or not. If an error occurs, this function leaves with any of the system wide error codes. Common error codes are listed below.

Returns: ETrue if video playback is enabled, EFalse if not.

VideoFormatMimeType ( )

IMPORT_C const TDesC8 &

VideoFormatMimeType

(

)

const

Returns the video format's MIME type.

Since: 7.0s

VideoFrameRateL ( )

IMPORT_C TReal32

VideoFrameRateL

(

)

const

Returns the video frame rate in frames/second.

Since: 7.0s

Returns: The video frame rate (frames/second).

VideoFrameSizeL ( TSize & )

IMPORT_C void

VideoFrameSizeL

(

TSize &

aSize

)

const

Gets the video frame size.

Since: 7.0s

Parameter	Description
aSize	The video frame size

Volume ( )

IMPORT_C TInt

Volume

(

)

const

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

Since: 7.0s

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

WillResumePlay ( )

IMPORT_C TInt

WillResumePlay

(

)

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.

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

Parameter	Description
aWidthPercentage	The percentage (100 = original size) to be used to scale the width of the video image
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.
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.