os/security/contentmgmt/contentaccessfwfordrm/engineering/dox/HowToSupplierAPI.dox
1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/security/contentmgmt/contentaccessfwfordrm/engineering/dox/HowToSupplierAPI.dox Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,184 @@
1.4 +// Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies).
1.5 +// All rights reserved.
1.6 +// This component and the accompanying materials are made available
1.7 +// under the terms of the License "Eclipse Public License v1.0"
1.8 +// which accompanies this distribution, and is available
1.9 +// at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.10 +//
1.11 +// Initial Contributors:
1.12 +// Nokia Corporation - initial contribution.
1.13 +//
1.14 +// Contributors:
1.15 +//
1.16 +// Description:
1.17 +// NOTE: For the purpose of clarity we have ommitted full error checking in the
1.18 +// <hr>
1.19 +// The Supplier API allows agents to publicise the MIME types they are
1.20 +// interested in. When those files arrive on the device, message handling
1.21 +// applications can check these MIME types and import the file
1.22 +// into CAF. The agent transforms the file into a different format
1.23 +// for use within the device.
1.24 +// In most cases this won't be necessary, since the files will arrive in the
1.25 +// same format that they will be used in. However, some agents require the device
1.26 +// to protect (encrypt) the content at the moment it arrives; the Supplier
1.27 +// API fulfills that role.
1.28 +// The classes used in the supply operation are:
1.29 +// <code>ContentAccess::CSupplier</code> and instances of <code>ContentAccess::CImportFile</code>.
1.30 +// <hr>
1.31 +// The <code>ContentAccess::CSupplier</code> is designed to allow several unrelated files to be imported
1.32 +// into CAF. It uses its <code>ContentAccess::CAgentResolver</code> member to determine
1.33 +// which CA agent should be used to import each file. The <code>CAgentResolver</code> builds
1.34 +// a list of all agents when it is created and updates the list if new agents
1.35 +// are installed.
1.36 +// A typical import session will start with the creation of a <code>CSupplier</code>, e.g.,
1.37 +// //Create Supplier
1.38 +// CSupplier *mySupplier = CSupplier::NewL();
1.39 +// Most applications will have a preference for the directory where output files
1.40 +// are to be stored. Usually the first thing to do with the new <code>CSupplier</code> instance
1.41 +// is to set the output path.
1.42 +// //Set output path for DRM protected content
1.43 +// _LIT(KPath,"C:\myOutputFiles");
1.44 +// mySupplier->SetOutputDirectoryL(KPath());
1.45 +// It is not necessary to set the output path if the application
1.46 +// provides output file handles to the agent.
1.47 +// <hr>
1.48 +// <b> Check that the MIME type is supported </b>
1.49 +// Before importing a file into the content access framework, an application
1.50 +// should check that the MIME type of the file is supported. Each agent publishes a
1.51 +// list of the MIME types it supports. The list is configured in the agent's
1.52 +// resource file and can be checked using <code>ContentAccess::CSupplier::IsImportSupported()</code>
1.53 +// if(!mySupplier->IsImportSupported(myMimeType))
1.54 +// return;
1.55 +// <b> Create a CMetaDataList object </b>
1.56 +// The <code>CMetaDataList</code> object is used to store any information associated with the import file that
1.57 +// may be useful for the agent. These values will be passed to the agent.
1.58 +// For example OMA DRM 1.0 files sometimes arrive with the HTTP header
1.59 +// <code>X-Oma-Drm-Separate-Delivery</code>. This informs the agent how long before rights are expected
1.60 +// for the content. If the rights were expected in 12 seconds it would be something like
1.61 +// the following:
1.62 +// // Create meta-data array
1.63 +// CMetaDataArray *metaDataArray = new (ELeave) CMetaDataArray();
1.64 +// CleanupStack::PushL(metaDataArray);
1.65 +// // Add any useful information we can think of....
1.66 +// metaDataArray->AddL(_L("Content Type"), _L("application/vnd.oma.drm.dm"));
1.67 +// metaDataArray->AddL(_L("X-Oma-Drm-Separate-Delivery"), _L("12"));
1.68 +// The file is 'written' to CAF using a <code>ContentAccess::CImportFile</code> object.
1.69 +// <code>ContentAccess::CSupplier::ImportFile()</code> creates an <code>CImportFile</code> object for importing a file.
1.70 +// The parameters supplied indicate whether the agent will create the output files or whether
1.71 +// the application using CAF will generate output files for the agent on demand.
1.72 +// // Create the import object, passing in the metaDataArray created earlier
1.73 +// // The application will supply the output files
1.74 +// CImportFile *import = mySupplier->ImportFileL(sourceMimeType, *metaDataArray);
1.75 +// The application should now transfer the file to CAF using the <code>CImportFile</code> object.
1.76 +// Only one file can be transferred by each instance although several output files
1.77 +// may be produced. Applications should create new <code>CImportFile</code> objects in order to import more files.
1.78 +// <b> Agents Generating the Output files </b>
1.79 +// If the application wants the agent to generate the output files, it should supply a suggested
1.80 +// file name in the call to <code>CSupplier::ImportFile()</code>. Even if this parameter is a zero length
1.81 +// descriptor, it still indicates that the agent is responsible for generating output files.
1.82 +// Agents will create the output files in a directory nominated by the application when it called
1.83 +// <code>CSupplier::SetOutputDirectoryL()</code> or they may decide to store the output files in their private
1.84 +// directory.
1.85 +// Applications should check at the end of the import to find out how many output files were created
1.86 +// and where they are stored.
1.87 +// <b> Application generating the Output files</b>
1.88 +// If no suggested file name is passed to the agent, the application will provide output files for
1.89 +// the agent to use. This mechanism allows applications to open files in their own private directory and
1.90 +// ask the CAF agent to store the output in those files.
1.91 +// The way it works is the same as an any other import operation, the difference is that the call
1.92 +// to <code>CImportFile::WriteData()</code> or <code>CImportFile::WriteComplete()</code> may return an error code of
1.93 +// <code>KErrCANewFileHandleRequired</code>.
1.94 +// This error code indicates that the agent needs a new output file handle in order to continue. The
1.95 +// application should open a new output file with write access and call <code>CImportFile::ContinueWithNewOutputFile()</code>
1.96 +// to supply the new handle to the agent. It is possible that further handles may be needed, if so
1.97 +// <code>CImportFile::ContinueWithNewOutputFile()</code> will return <code>KErrCANewFileHandleRequired</code> and the application should
1.98 +// repeat the procedure with another file.
1.99 +// The agent must cache its state before returning <code>KErrCANewFileHandleRequired</code>. The application MUST NOT resend
1.100 +// the same <code>WriteData()</code> or <code>WriteComplete()</code> command.
1.101 +// At the end of the import operation the output files will still be listed regardless of whether
1.102 +// they were supplied by the application or the agent.
1.103 +// <hr>
1.104 +// <code>ContentAccess::CImportFile</code> is the class used to write the file data to CAF.
1.105 +// It is created by <code>ContentAccess::CSupplier</code> and can only be used to import a single file.
1.106 +// An application should call <code>WriteData()</code> to transfer a field in 'chunks' to the Content
1.107 +// Access Framework. Usually this would be something like the following:
1.108 +// TFileName fileName;
1.109 +// TBuf8<128> data;
1.110 +// TInt err = KErrNone;
1.111 +// // start importing content
1.112 +// while( (source still has data) && (err==KErrNone) )
1.113 +// source.read(data);
1.114 +// err = import->WriteData(data);
1.115 +// // need to supply new file to import to ?
1.116 +// while (err == KErrCANewFileHandleRequired)
1.117 +// // supply new file in order to continue writing
1.118 +// RFile newFile;
1.119 +// import->GetSuggestedOutputFileName(fileName);
1.120 +// newFile.Open(fileName, EFileWrite);
1.121 +// err = import->ContinueWithNewOutputFile(newFile, fileName);
1.122 +// newFile.Close();
1.123 +// <hr>
1.124 +// When all the data is written, the application should call <code>ContentAccess::CImportFile::WriteComplete()</code>, this will
1.125 +// let the agent know that all the data has been transferred and allow it to perform any final processing.
1.126 +// err = import->WriteComplete();
1.127 +// // When application supplies file handles it must always check to see if
1.128 +// // the agent needs a new file handle
1.129 +// while(err == KErrCANewFileHandleRequired)
1.130 +// RFile newFile;
1.131 +// import->GetSuggestedOutputFileName(fileName);
1.132 +// newFile.Open(fileName, EFileWrite);
1.133 +// err = import->ContinueWithNewOutputFile(newFile, filename);
1.134 +// // It is possible that the agent needs yet another file handle
1.135 +// newFile.Close(); // agent makes a copy so we don't need to keep our file handle
1.136 +// At this stage all the agent's work is done, the <code>CImportFile</code> object can be deleted.
1.137 +// <hr>
1.138 +// When the import is finished the application may wish to check if any output files have
1.139 +// been produced. The list of output files is accessed using <code>ContentAccess::CImportFile::OutputFileL()</code>.
1.140 +// // loop over all the output files produced
1.141 +// for(TInt i =0; i < import->OutputFileCountL(); i++)
1.142 +// // Can now retrieve filename, type of file (receipt or content) and
1.143 +// // MIME type for the file produced
1.144 +// TPtr filename = import->OutputFileL(i).FileName();
1.145 +// TOutputType type = import->OutputFileL(i).OutputType();
1.146 +// TPtr8 mimetype = import->OutputFileL(i).MimeType();
1.147 +// The output files can be either content files or receipts for DRM rights. It is possible that no output
1.148 +// files will be generated and the file will be "absorbed" into the agent.
1.149 +// Also, it is important to remember that the MIME type and most likely the file extension of the output files are
1.150 +// almost certainly different to the MIME type and file extension of the imported file.
1.151 +// <hr>
1.152 +//
1.153 +//
1.154 +
1.155 +/**
1.156 + @page CSupplierAPI Importing files into the Content Access Framework
1.157 + - @ref SupplierAPI
1.158 + - @ref ImportSession
1.159 + - @ref ImportCAF
1.160 + - @ref Importfile
1.161 + - @ref ImportComplete
1.162 + - @ref ImportOutput
1.163 + code examples given below. For examples with error checking see @ref ExampleSupplier2.
1.164 + @section SupplierAPI Supplier API
1.165 + @section ImportSession Starting a new import session
1.166 + @code
1.167 + @endcode
1.168 + @code
1.169 + @endcode
1.170 + @section ImportCAF Preparing to import the file
1.171 + @code
1.172 + @endcode
1.173 + @code
1.174 + @endcode
1.175 + @section ImportFile Creating the CImportFile object
1.176 + @code
1.177 + @endcode
1.178 + @section Importfile Transferring the file to the Content Access Agent
1.179 + @code
1.180 + @endcode
1.181 + @section ImportComplete Completing the Import
1.182 + @code
1.183 + @endcode
1.184 + @section ImportOutput Output files produced
1.185 + @code
1.186 + @endcode
1.187 +*/