Collapse all Symbian^3 Application Developer Library

ContentAccess::CAgentData Class Reference

class ContentAccess::CAgentData : public CBase

Defines the agent interface for consumer operations such as reading and seeking within a content object in a file.

Inherits from

ContentAccess::CAgentData
- CBase

Public Member Functions
void	DataSizeL ( TInt &)
TInt	EvaluateIntent ( TIntent )
TInt	ExecuteIntent ( TIntent )
TInt	GetAttribute ( TInt , TInt &)
TInt	GetAttributeSet ( RAttributeSet &)
TInt	GetStringAttribute ( TInt , TDes &)
TInt	GetStringAttributeSet (RStringAttributeSet &)
TInt	Read ( TDes8 &)
TInt	Read ( TDes8 &, TInt )
void	Read ( TDes8 &, TRequestStatus &)
void	Read ( TDes8 &, TInt , TRequestStatus &)
IMPORT_C TInt	Read ( TInt , TDes8 &, TInt , TRequestStatus &)
IMPORT_C void	ReadCancel ( TRequestStatus &)
TInt	Seek ( TSeek , TInt &)
TInt	SetProperty ( TAgentProperty , TInt )

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

Member Functions Documentation

DataSizeL(TInt &)

void

DataSizeL

(

TInt &

aSize

)

[pure virtual]

Gets the data size in bytes.

leave: KErrCASizeNotDetermined Size could not be determined by the managing agent.

leave: ... One of the other CAF error codes defined in caferr.h or one of the system-wide error codes for any other errors.

capability: DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted

Parameters

TInt & aSize

On return this will contain the size of the plaintext data in bytes.

EvaluateIntent(TIntent)

TInt

EvaluateIntent

(

TIntent

aIntent

)

[pure virtual]

Allows a client to verify that the intent is supported by the current rights for the data object.

Doing so may cause subsequent reads (or other accesses) to fail. The result of the agent's evaluation of the intent is returned.

Note:

Since the intent is only evaluated the agent will not decrement any rights-state such as play counts.

capability: DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted

Parameters

TIntent aIntent

The intended way the content will be used.

ExecuteIntent(TIntent)

TInt

ExecuteIntent

(

TIntent

aIntent

)

[pure virtual]

Execute intent allows the application to signal it is about to carry out the specified intent on DRM protected content.The agent will decrement applicable stateful rights such as play counts where necessary.

Applications should be very careful to use this function correctly.

If ExecuteIntent() is never called stateful rights will never be decremented. Users will be able to use the content forever
If ExecuteIntent() is called too often stateful rights may be consumed prematurely.

Usually it would be best to call ExecuteIntent immediately before the content is displayed or the instant playback begins. ExecuteIntent should not be considered a prerequisite for calling the Read functions. It is valid for an application to read from the file before calling ExecuteIntent.

Note:

Since rights are executed here the agent will decrement any rights-state such as play counts that apply.

capability: DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted

Parameters

TIntent aIntent

The intent indicator.

GetAttribute(TInt, TInt &)

TInt	GetAttribute	(	TInt	aAttribute,
			TInt &	aValue
		)	[pure virtual]

Get the value of an attribute for this content object

capability: DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted

Parameters

TInt aAttribute	The attribute to query, from ContentAccess::TAttribute.
TInt & aValue	Used to return the attribute value.

GetAttributeSet(RAttributeSet &)

TInt

GetAttributeSet

(

RAttributeSet &

aAttributeSet

)

[pure virtual]

Get a set of attributes from a content object

capability: DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted

Parameters

RAttributeSet & aAttributeSet

The set of attributes to query and update.

GetStringAttribute(TInt, TDes &)

TInt	GetStringAttribute	(	TInt	aAttribute,
			TDes &	aValue
		)	[pure virtual]

Get text string attributes or meta-data for this content object

capability: DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted

Parameters

TInt aAttribute	The attribute to query, from ContentAccess::TStringAttribute.
TDes & aValue	Returns the value of the attribute.

GetStringAttributeSet(RStringAttributeSet &)

TInt

GetStringAttributeSet

(

RStringAttributeSet &

aStringAttributeSet

)

[pure virtual]

Used to obtain a set of string attributes

capability: DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted.

Parameters

RStringAttributeSet & aStringAttributeSet

The set of attributes to query and update.

Read(TDes8 &)

TInt

Read

(

TDes8 &

aDes

)

[pure virtual]

Reads from a content object up to the maximum length of the descriptor or the end of the content object.

When an attempt is made to read beyond the end of the content, no error is returned. The descriptor s length is set to the number of bytes that were read into it. Therefore, when reading through content, the end has been reached when the descriptor length (given by TDesC::Length() ) is zero.

capability: DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted

Parameters

TDes8 & aDes

Descriptor into which binary data is read. Any existing contents are overwritten. On return, its length is set to the number of bytes read.

Read(TDes8 &, TInt)

TInt	Read	(	TDes8 &	aDes,
			TInt	aLength
		)	[pure virtual]

Reads a specified number of bytes of content.

Read(TDes8& aDes)

capability: DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted

Parameters

TDes8 & aDes	Descriptor into which binary data is read. Any existing contents are overwritten. On return, its length is set to the number of bytes read.
TInt aLength	The number of bytes to read from the file, or to the end of the file, whichever is encountered first. The length of the buffer is set to the number of bytes actually read.

Read(TDes8 &, TRequestStatus &)

void	Read	(	TDes8 &	aDes,
			TRequestStatus &	aStatus
		)	[pure virtual]

Reads content asynchronously.

Read(TDes8& aDes)

capability: DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted

Parameters

TDes8 & aDes	Descriptor into which binary data is read. Any existing contents are overwritten. On return, its length is set to the number of bytes read.
TRequestStatus & aStatus	Asynchronous request status. On completion this will contain one of the following error codes: KErrNone if the data was successfully read. Otherwise one of the CAF error codes defined in caferr.h or one of the other standard system-wide error codes for any other errors.

Read(TDes8 &, TInt, TRequestStatus &)

void	Read	(	TDes8 &	aDes,
			TInt	aLength,
			TRequestStatus &	aStatus
		)	[pure virtual]

Reads content asynchronously (up to a specified maximum number of bytes)

Read(TDes8& aDes)

capability: DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted

Parameters

TDes8 & aDes	Descriptor into which binary data is read. Any existing contents are overwritten. On return, its length is set to the number of bytes read.
TInt aLength	The number of bytes to read from the file, or to the end of the file, whichever is encountered first. The length of the buffer is set to the number of bytes actually read.
TRequestStatus & aStatus	Asynchronous request status. On completion this will contain one of the following error codes: KErrNone if the data was successfully read. Otherwise one of the CAF error codes defined in caferr.h or one of the other standard system-wide error codes for any other errors.

Read(TInt, TDes8 &, TInt, TRequestStatus &)

IMPORT_C TInt	Read	(	TInt	aPos,
			TDes8 &	aDes,
			TInt	aLength,
			TRequestStatus &	aStatus
		)	[virtual]

Reads content asynchronously. The data is read from a specified offset up to a specified number of bytes or until the end of the content object is reached. The data is read into the descriptor buffer supplied.

Read(TDes8& aDes)

capability: DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted

Parameters

TInt aPos	Position of first byte to be read. This is an offset from the start of the file.
TDes8 & aDes	Descriptor into which binary data is read. Any existing contents are overwritten. On return, its length is set to the number of bytes read.
TInt aLength	The number of bytes to read from the file, or to the end of the file, whichever is encountered first. The length of the buffer is set to the number of bytes actually read.
TRequestStatus & aStatus	Asynchronous request status. On completion this will contain one of the following error codes: KErrNone if the data was successfully read. Otherwise one of the CAF error codes defined in caferr.h or one of the other standard system-wide error codes for any other errors.

ReadCancel(TRequestStatus &)

IMPORT_C void

ReadCancel

(

TRequestStatus &

aStatus

)

[virtual]

Cancels asynchronous read.

capability: DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted

Parameters

TRequestStatus & aStatus

Asynchronous request status. This parameter should have been supplied earlier to an asynchronous Read call. If it has not been previously supplied to a Read call, this function will not have any effect.

Seek(TSeek, TInt &)

TInt	Seek	(	TSeek	aMode,
			TInt &	aPos
		)	[pure virtual]

Changes or retrieves the location of the file pointer within the content object

There are four seek modes used:

ESeekStart - Sets the file pointer aPos bytes from the start of the content object. aPos is not modified by the call to Seek()
ESeekEnd - Sets the file pointer aPos bytes from the end of the content object. The aPos parameter supplied should be zero or negative when using ESeekEnd. Upon completion aPos is updated with the current position relative to the start of the content object.
ESeekCurrent - Moves the file pointer aPos bytes from the current position. Upon completion aPos is updated with the new position relative to the start of the content object. Suppling a zero value for the aPos Parameter can be used to retrieve the current file pointer location
ESeekAddress Sets the aPos parameter to the address of the byte aPos bytes from the start of the content object

TSeek

capability: DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted

Parameters

TSeek aMode	Seek mode - controls the destination of the seek operation.
TInt & aPos	Offset from either the start, end or current position depending upon the seek mode. Negative offsets are used to seek before the current position or relative to the end of the file.

SetProperty(TAgentProperty, TInt)

TInt	SetProperty	(	TAgentProperty	aProperty,
			TInt	aValue
		)	[pure virtual]

Allows an application to request the modification of a property within the agent handling this content. The agent may or may not permit the property to be changed

capability: DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted

Parameters

TAgentProperty aProperty	The property to set.
TInt aValue	The value of the property.