OMA DRM CAF Agent API Specification

Contents

1 Overview

This API specifies the agent-specific attributes and commands for the OMA DRM CAF Agent. It is an extension to Symbian CAF API


API categorypublic
API typec++
Existed sinceLegacy S60 3.0
Location/sf/mw/drm/drm_pub/oma_drm_caf_agent_api
Buildfiles/sf/mw/drm/drm_pub/oma_drm_caf_agent_api/group/bld.inf


1.1 Description

OMA DRM CAF Agent API is a collection of enumerations and constants that can be used with CAF. It does not contain any classes or function declarations itself.

1.2 Changes

OMA DRM CAF API is available from S60 3.0 and onwards.

1.3 Use Cases

OMA DRM CAF Agent API covers agent-specific commands and attributes. These are handled by invoking the following CAF methods:

All the functions need to be called on an allocated object of the respective class.

1.4 Class Structure

Summary of API classes and header files
ClassesFiles
No classes/epoc32/include/mw/Oma2Agent.h

This API does not contain any classes. All the classes required to use OMA DRM CAF Agent are parts of CAF API.

2 Using The API

The following sections illustrate the most common use cases of OMA DRM CAF Agent API

2.1 Determining the file type 

// allocate a content object, specify that we only want to peek at it
CContent* content = CContent::NewL(fileName, EPeek, EContentShareReadOnly);
TInt value = 0;
if (content->GetAttribute(EFileType, value) == KErrNone)
	{
	if (value == ENoDcf)
		{
		// the file is not an OMA DRM file
		}
	else if (value == EOma1Dcf)
		{
		// the file is an OMA DRM 1.0 file
		}
	else if (value == EOma2Dcf)
		{
		// the file is an OMA DRM 2.0 file
		}
	}
else
	{
	// the file type could not be determined
	}

2.2 Accessing embedded preview parts 

// allocate a data object, specify that we only want to peek at it, and
// that we want the default part of the file
CData* data = CData::NewL(TVirtualPathPtr(fileName, KDefaultContentObject),
		EPeek, EContentShareReadOnly);
TBuf<256> part;
if (data->GetStringAttribute(EInstantPreviewUri, part) == KErrNone &&
	part.Length() > 0)
	{
	delete data;
	// open the part, now with the actual intent
	data = CData::NewL(TVirtualPathPtr(fileName, part), EView,
		EContentShareReadOnly);
	// do something with the data
	…
	}
else
	{
	// no preview part available
	}

2.3 Inserting domain Rights objects 

// allocate a content object, specify that we only want to peek at it,
// but we need to be able to write
CContent* content = CContent::NewL(fileName, EPeek, EContentShareReadWrite);
if (content->AgentSpecificCommand(EEmbedDomainRo, KNullDesC, KNullDesC) ==
	KErrNone)
	{
	// embedding succeeded
	}

2.4 Processing DRM messages 

// Import is handling via the CSupplier class
CSupplier* supplier = CSupplier::NewLC();
CMetaDataArray* metaData = CMetaDataArray::NewLC();
// Set the target for the encrypted file
supplier->SetOutputDirectoryL(KEncryptedDir);
// The agent is selected based on the MIME type of the data to be imported
CImportFile* file = supplier->ImportFileL(KOma1DrmMessageContentType,
        *metaData, KTempDcfName);
file->WriteData(KDMSimple);
file->WriteDataComplete();
CSupplierOutputFile& output = file->OutputFileL(0);

2.5 Encryption of content 

CSupplier* supplier = CSupplier::NewLC();
CMetaDataArray* metaData = CMetaDataArray::NewLC();
// Tell the agent which MIME type to use for the encrypted data
metaData->AddL(KOmaImportMimeTypeField, _L8("image/gif"));
supplier->SetOutputDirectoryL(KEncryptedDir);
// The KOmaImportContentType is a OMA DRM agent specific MIME type which
// indicates that plain content is to be encrypted
CImportFile* file = supplier->ImportFileL(KOmaImportContentType,
        *metaData, KTempDcfName);
file->WriteData(KDMSimple);
file->WriteDataComplete();
CSupplierOutputFile& output = file->OutputFileL(0);

2.6 Error handling

Error handling is defined in relevant CAF operations. In addition to that, the KErrOverflow error indicates that the given output buffer is not large enough to hold the result of the requested operation.

2.7 Memory and Performance Considerations

The methods returning string attribute values and the agent specific commands must be called with enough memory allocated in the output parameters. Otherwise, the function calls fail with the KErrOverflow error code.

2.8 Extensions to the API

CAF API can be extended using agent-specific commands and attributes, and OMA DRM CAF Agent API is such an extension. It is expected that any additional functionality of OMA DRM CAF Agent will be provided by adding new attribute and command enumeration values.

3 Glossary

3.1 Abbreviations

CAF Content Access Framework

3.2 Definitions

DRM Agent A collection of components that allow access to DRM-protected

data.

OMA DRM CAF Agent A DRM Agent, which implements the OMA DRM standard, a

part of S60.

4 References

RFC2630: Cryptographic Message Syntax
http://www.ietf.org/rfc/rfc2630.txt