#include <caf/data.h>
| class ContentAccess::CData : public CBase |
Allows clients to read data from a content object.
This class is initialised with an agent implementation that is responsible for this content object.
| IMPORT_C void | DataSizeL | ( | TInt & | aSize | ) |
Gets the data size in bytes.
| Parameter | Description |
|---|---|
| aSize | On return this will contain the size of the plaintext data in bytes. |
Allows a client to verify that the intent is supported by the current rights for the data object.
Since the intent is only evaluated the agent will not decrement any rights-state such as play counts.
See also: ContentAccess::TIntent
| Parameter | Description |
|---|---|
| aIntent | The intended way the content will be used. |
Returns: Whether rights exist allowing the content to be used for this intent. KErrNone if the intent is permitted. KErrNoRights if no rights exist for the specified content object. KErrCANoPermission if rights exist but the specified intent is not permitted. KErrCAPendingRights if the rights have not yet arrived but are expected soon. KErrNoPermission if rights exist but none permit the specified intent. KErrPermissionDenied if the client is not allowed to use this content object. Otherwise one of the other CAF error codes defined in caferr.h or one of the other system-wide error codes for any other errors.
Execute intent allows the application to signal it is about to carry out the specified intent on protected content.The agent will decrement applicable stateful rights such as play counts where necessary.
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.
Since rights are executed here the agent will decrement any rights-state such as play counts that apply.
| Parameter | Description |
|---|---|
| aIntent | The intent indicator. |
Returns: The result of attempting executing the intent. KErrNone if the intent is permitted and stateful rights may have been decremented. KErrNoRights if no rights exist for the specified content object. KErrCANoPermission if rights exist but the specified intent is not permitted. KErrCAPendingRights if the rights have not yet arrived but are expected soon. KErrNoPermission if rights exist but none permit the specified intent. KErrPermissionDenied if the client is not allowed to use this content object. Otherwise one of the other CAF error codes defined in caferr.h or one of the. other system-wide error codes for any other errors.
Get an attribute for the content object
See also: ContentAccess::TAttribute
CContent* content = CContent::NewL(uri);
CData* data = content->OpenContentL(EPlay, uniqueId);
delete content;
TInt value = 0;
TInt err = data->GetAttribute(EIsProtected, value);
if(err == KErrNone && value)
{
DisplayPadLock();
}
delete data;
| Parameter | Description |
|---|---|
| aAttribute | The attribute to query, from ContentAccess::TAttribute. |
| aValue | Used to return the attribute value. |
Returns: Whether the attribute was updated. KErrNone if the value of the attribute was updated. KErrCANotSupported if the requested attribute does not exist. KErrPermissionDenied if the access to the protected content is not permitted by the CAF Agent. Otherwise one of the other CAF error codes defined in caferr.h or one of the other system-wide error codes for any other errors.
| IMPORT_C TInt | GetAttributeSet | ( | RAttributeSet & | aAttributeSet | ) | const |
Get a set of attributes for the content object
See also: ContentAccess::TAttribute
The following example determines whether the content object is protected and has rights that will enable it to be viewed by the user
// CData* data = a data object
RAttributeSet attributeSet;
CleanupClosePushL(attributeSet);
attributeSet->AddL(EProtected);
attributeSet->AddL(ECanView);
User::LeaveIfError(data->GetAttributeSet(attributeSet);
TInt err = attributeSet.GetValue(EProtected, value);
if(err == KErrNone && value)
{
// file is DRM protected
}
err = attributeSet.GetValue(ECanView, value);
if(err == KErrNone && value)
{
// File has rights that allow it to be displayed on screen
}
// Finished
CleanupStack::PopAndDestroy(); // attributeSet.Close()
| Parameter | Description |
|---|---|
| aAttributeSet | The set of attributes to query and update. |
Returns: Whether the attribute set was updated. KErrNone if the attributes were retrieved successfully. KErrPermissionDenied if the access to the protected content is not permitted by the CAF Agent. Otherwise one of the CAF error codes defined in caferr.h or one of the other system-wide error codes for any other errors.
Get the mime type of the content Deprecated
| Parameter | Description |
|---|---|
| aMimeType | Buffer to store the mime type provided by the agent. |
Returns: ETrue if the mime type was retrieved successfully.
Get text string attributes or meta-data for the content object
See also: ContentAccess::TStringAttribute
CContent* content = CContent::NewLC(uri);
CData* data = content->OpenContentLC(EPlay, uniqueId);
CleanupStack::PopAndDestroy(content);
TBuf <MAX_PATH> previewUri;
TInt err = data->GetStringAttribute(EPreviewURI, previewUri);
if(err == KErrNone)
{
DisplayPreview(previewUri);
}
CleanupStack::PopAndDestroy(data);
| Parameter | Description |
|---|---|
| aAttribute | The attribute to query, from ContentAccess::TStringAttribute. |
| aValue | Returns the value of the attribute. |
Returns: Whether the value was updated. KErrNone if the attribute was retrieved. KErrOverflow if the buffer was not large enough to return the result. KErrCANotSupported if the requested attribute does not exist. KErrPermissionDenied if the access to the protected content is not permitted by the CAF Agent. Otherwise one of the other CAF error codes defined in caferr.h or one of the other system-wide error codes for any other errors.
| IMPORT_C TInt | GetStringAttributeSet | ( | RStringAttributeSet & | aStringAttributeSet | ) | const |
Obtain a set of string attributes for the content object
See also: ContentAccess::TStringAttribute
CContent* content = CContent::NewLC(uri);
CData* data = content->OpenContentLC(EPlay, uniqueId);
// create the attribute set, add the attributes we are interested in
RStringAttributeSet stringAttributeSet;
CleanupClosePushL(stringAttributeSet);
stringAttributeSet.AddL(EPreviewURI);
stringAttributeSet.AddL(ETitle);
User::LeaveIfError(data->GetStringAttributeSet(stringAttributeSet));
// Pass the value of the string attribute to DisplayPreview()
TFileName previewUri;
TInt err = stringAttributeSet.GetValue(EPreviewURI, previewUri);
if(err == KErrNone)
{
DisplayPreview(previewUri);
}
CleanupStack::PopAndDestroy(3); // content, data, stringAttributeSet
| Parameter | Description |
|---|---|
| aStringAttributeSet | The set of attributes to query and update. |
Returns: Whether the string attribute set was updated. KErrNone if the attributes were retrieved successfully. KErrNotFound if the default content object was not found. KErrPermissionDenied if the access to the protected content is not permitted by the CAF Agent. Otherwise one of the CAF error codes defined in caferr.h or one of the other system-wide error codes for any other errors.
| IMPORT_C CData * | NewL | ( | const TVirtualPathPtr & | aVirtualPath, |
| TIntent | aIntent, | |||
| TContentShareMode | aShareMode | |||
| ) | [static] | |||
Creates a new CData object.
| Parameter | Description |
|---|---|
| aVirtualPath | The content object to read |
| aIntent | The intended use of the content. |
| aShareMode | The file share mode used to open this content. |
Returns: The new CData object.
| IMPORT_C CData * | NewL | ( | const TVirtualPathPtr & | aVirtualPath, |
| TContentShareMode | aShareMode | |||
| ) | [static] | |||
Creates a new CData object.
| Parameter | Description |
|---|---|
| aVirtualPath | The content object to read. |
| aShareMode | The file share mode used to open this content. |
Returns: The new CData object.
Creates a new CData object.
| Parameter | Description |
|---|---|
| aFile | An open RFile handle, the agent will make a duplicate of this handle. The underlying RFs session should be shared for transfer to other processes using RFs::ShareProtected(), since the agent may use transfer this handle to its own or one of the system servers. |
| aUniqueId | The content object to read. |
| aIntent | The intended use of the content. |
Returns: The new CData object.
Creates a new CData object.
| Parameter | Description |
|---|---|
| aFile | An open RFile handle, the agent will make a duplicate of this handle. The underlying RFs session should be shared for transfer to other processes using RFs::ShareProtected(), since the agent may use transfer this handle to its own or one of the system servers. |
| aUniqueId | The content object to read. |
Returns: The new CData object.
| IMPORT_C CData * | NewLC | ( | const TVirtualPathPtr & | aVirtualPath, |
| TIntent | aIntent, | |||
| TContentShareMode | aShareMode | |||
| ) | [static] | |||
Creates a new CData object
| Parameter | Description |
|---|---|
| aVirtualPath | The content object to read. |
| aIntent | The intended use of the content. |
| aShareMode | The file share mode used to open this content. |
Returns: The new CData object.
| IMPORT_C CData * | NewLC | ( | const TVirtualPathPtr & | aVirtualPath, |
| TContentShareMode | aShareMode | |||
| ) | [static] | |||
Creates a new CData object
| Parameter | Description |
|---|---|
| aVirtualPath | The content object to read. |
| aShareMode | The file share mode used to open this content. |
Returns: The new CData object.
Creates a new CData object.
| Parameter | Description |
|---|---|
| aFile | An open RFile handle, the agent will make a duplicate of this handle. The underlying RFs session should be shared for transfer to other processes using RFs::ShareProtected(), since the agent may use transfer this handle to its own or one of the system servers. |
| aUniqueId | The content object to read. |
| aIntent | The intended use of the content. |
Returns: The new CData object.
Creates a new CData object.
| Parameter | Description |
|---|---|
| aFile | An open RFile handle, the agent will make a duplicate of this handle. The underlying RFs session should be shared for transfer to other processes using RFs::ShareProtected(), since the agent may use transfer this handle to its own or one of the system servers. |
| aUniqueId | The content object to read. |
Returns: The new CData object.
| CData * | NewLC | ( | TUid | aAgentUid, |
| const TVirtualPathPtr & | aVirtualPath, | |||
| TIntent | aIntent, | |||
| TContentShareMode | aShareMode | |||
| ) | [static] | |||
Creates a new CData object.
| Parameter | Description |
|---|---|
| aAgentUid | The agent determined to support this content. |
| aVirtualPath | The content object to read. |
| aIntent | The intended use of the content. |
| aShareMode | The file share mode used to open this content. |
Returns: The new CData object.
Creates a new CData object.
| Parameter | Description |
|---|---|
| aAgentUid | The Uid of the agent who supports this content. |
| aFile | An open RFile handle, the agent will make a duplicate of this handle. The underlying RFs session should be shared for transfer to other processes using RFs::ShareProtected(), since the agent may use transfer this handle to its own or one of the system servers. |
| aUniqueId | The content object to read. |
| aIntent | The intended use of the content. |
Returns: The new CData object.
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.
| Parameter | Description |
|---|---|
| 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. |
Returns: KErrNone if successful. One of the CAF error codes defined in caferr.h or one of the other system-wide error codes.
Reads from a content object up to the specified length of the descriptor or the end of the content object.
See also: Read(TDes8& aDes)
| Parameter | Description |
|---|---|
| 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. |
| 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. |
Returns: KErrNone if successful. Otherwise one of the CAF error codes defined in caferr.h or one of the other system-wide error codes.
| IMPORT_C void | Read | ( | TDes8 & | aDes, |
| TRequestStatus & | aStatus | |||
| ) | const | |||
Read content asynchronously up to the maximum length of the descriptor or until the end of the content object is reached. NB: It is important that the descriptor passed to aDes remains in scope until the request has completed.
See also: Read(TDes8& aDes)
| Parameter | Description |
|---|---|
| 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. |
| 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. |
| IMPORT_C void | Read | ( | TDes8 & | aDes, |
| TInt | aLength, | |||
| TRequestStatus & | aStatus | |||
| ) | const | |||
Read content asynchronously up to the specified length or until the end of the content object is reached. NB: It is important that the descriptor passed to aDes remains in scope until the request has completed.
See also: Read(TDes8& aDes)
| Parameter | Description |
|---|---|
| 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. |
| 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. |
| 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. |
| IMPORT_C TInt | Read | ( | TInt | aPos, |
| TDes8 & | aDes, | |||
| TInt | aLength, | |||
| TRequestStatus & | aStatus | |||
| ) | const | |||
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.
See also: Read(TDes8& aDes)
| Parameter | Description |
|---|---|
| aPos | Position of first byte to be read. This is an offset from the start of the file. |
| 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. |
| 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. |
| 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. |
Returns: KErrNone if the async read request was successfully submitted. KErrArgument if a negative offset is supplied. KErrCANotSupported if the agent does not support this operation.
| IMPORT_C void | ReadCancel | ( | TRequestStatus & | aStatus | ) | const |
Cancels asynchronous read.
| Parameter | Description |
|---|---|
| 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. |
Changes or retrieves the location of the file pointer within the content object.
NOTE: Some operations may fail if the content data is sourced over a network connection.
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
See also: TSeek
| Parameter | Description |
|---|---|
| aMode | Seek mode - controls the destination of the seek operation. |
| 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. |
Returns: KErrNone if successful. Otherwise one of the CAF error codes defined in caferr.h or one of the other system-wide error codes.
| IMPORT_C TInt | SetProperty | ( | TAgentProperty | aProperty, |
| TInt | aValue | |||
| ) | ||||
Request the agent handling this content to set a property value. If the property is set it is only set for this CData session and does not impact other CAF users.
For example setting the buffer-size to 256 bytes can be achieved as follows:
MyData->SetProperty(EAgentPropertyBufferSize, 256);
See also: ContentAccess::TAgentProperty
| Parameter | Description |
|---|---|
| aProperty | The property to set. |
| aValue | The value of the property. |
Returns: Whether or not the property was set. KErrNone if the property was set. KErrCANotSupported if the agent does not support the property or value. KErrAccessDenied if the agent does not permit the property to be changed. KErrPermissionDenied if the application does not have the necessary capability to change the property.
| IMPORT_C void | SetQosL | ( | TQosAttribute | aQosAttr, |
| TInt | aValue | |||
| ) | ||||
Set Qos attribute Deprecated
| Parameter | Description |
|---|---|
| aQosAttr | The Qos attribute to set. |
| aValue | The value of the attribute. |