diff -r deec7e509f66 -r ca9a0fc2f082 contentmgmt/contentaccessfwfordrm/engineering/dox/HowToSupplierAPI.dox --- a/contentmgmt/contentaccessfwfordrm/engineering/dox/HowToSupplierAPI.dox Wed Oct 06 11:09:48 2010 +0530 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,184 +0,0 @@ -// Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies). -// All rights reserved. -// This component and the accompanying materials are made available -// under the terms of the License "Eclipse Public License v1.0" -// which accompanies this distribution, and is available -// at the URL "http://www.eclipse.org/legal/epl-v10.html". -// -// Initial Contributors: -// Nokia Corporation - initial contribution. -// -// Contributors: -// -// Description: -// NOTE: For the purpose of clarity we have ommitted full error checking in the -//
ContentAccess::CSupplier
and instances of ContentAccess::CImportFile
.
-// ContentAccess::CSupplier
is designed to allow several unrelated files to be imported
-// into CAF. It uses its ContentAccess::CAgentResolver
member to determine
-// which CA agent should be used to import each file. The CAgentResolver
builds
-// a list of all agents when it is created and updates the list if new agents
-// are installed.
-// A typical import session will start with the creation of a CSupplier
, e.g.,
-// //Create Supplier
-// CSupplier *mySupplier = CSupplier::NewL();
-// Most applications will have a preference for the directory where output files
-// are to be stored. Usually the first thing to do with the new CSupplier
instance
-// is to set the output path.
-// //Set output path for DRM protected content
-// _LIT(KPath,"C:\myOutputFiles");
-// mySupplier->SetOutputDirectoryL(KPath());
-// It is not necessary to set the output path if the application
-// provides output file handles to the agent.
-// ContentAccess::CSupplier::IsImportSupported()
-// if(!mySupplier->IsImportSupported(myMimeType))
-// return;
-// Create a CMetaDataList object
-// The CMetaDataList
object is used to store any information associated with the import file that
-// may be useful for the agent. These values will be passed to the agent.
-// For example OMA DRM 1.0 files sometimes arrive with the HTTP header
-// X-Oma-Drm-Separate-Delivery
. This informs the agent how long before rights are expected
-// for the content. If the rights were expected in 12 seconds it would be something like
-// the following:
-// // Create meta-data array
-// CMetaDataArray *metaDataArray = new (ELeave) CMetaDataArray();
-// CleanupStack::PushL(metaDataArray);
-// // Add any useful information we can think of....
-// metaDataArray->AddL(_L("Content Type"), _L("application/vnd.oma.drm.dm"));
-// metaDataArray->AddL(_L("X-Oma-Drm-Separate-Delivery"), _L("12"));
-// The file is 'written' to CAF using a ContentAccess::CImportFile
object.
-// ContentAccess::CSupplier::ImportFile()
creates an CImportFile
object for importing a file.
-// The parameters supplied indicate whether the agent will create the output files or whether
-// the application using CAF will generate output files for the agent on demand.
-// // Create the import object, passing in the metaDataArray created earlier
-// // The application will supply the output files
-// CImportFile *import = mySupplier->ImportFileL(sourceMimeType, *metaDataArray);
-// The application should now transfer the file to CAF using the CImportFile
object.
-// Only one file can be transferred by each instance although several output files
-// may be produced. Applications should create new CImportFile
objects in order to import more files.
-// Agents Generating the Output files
-// If the application wants the agent to generate the output files, it should supply a suggested
-// file name in the call to CSupplier::ImportFile()
. Even if this parameter is a zero length
-// descriptor, it still indicates that the agent is responsible for generating output files.
-// Agents will create the output files in a directory nominated by the application when it called
-// CSupplier::SetOutputDirectoryL()
or they may decide to store the output files in their private
-// directory.
-// Applications should check at the end of the import to find out how many output files were created
-// and where they are stored.
-// Application generating the Output files
-// If no suggested file name is passed to the agent, the application will provide output files for
-// the agent to use. This mechanism allows applications to open files in their own private directory and
-// ask the CAF agent to store the output in those files.
-// The way it works is the same as an any other import operation, the difference is that the call
-// to CImportFile::WriteData()
or CImportFile::WriteComplete()
may return an error code of
-// KErrCANewFileHandleRequired
.
-// This error code indicates that the agent needs a new output file handle in order to continue. The
-// application should open a new output file with write access and call CImportFile::ContinueWithNewOutputFile()
-// to supply the new handle to the agent. It is possible that further handles may be needed, if so
-// CImportFile::ContinueWithNewOutputFile()
will return KErrCANewFileHandleRequired
and the application should
-// repeat the procedure with another file.
-// The agent must cache its state before returning KErrCANewFileHandleRequired
. The application MUST NOT resend
-// the same WriteData()
or WriteComplete()
command.
-// At the end of the import operation the output files will still be listed regardless of whether
-// they were supplied by the application or the agent.
-// ContentAccess::CImportFile
is the class used to write the file data to CAF.
-// It is created by ContentAccess::CSupplier
and can only be used to import a single file.
-// An application should call WriteData()
to transfer a field in 'chunks' to the Content
-// Access Framework. Usually this would be something like the following:
-// TFileName fileName;
-// TBuf8<128> data;
-// TInt err = KErrNone;
-// // start importing content
-// while( (source still has data) && (err==KErrNone) )
-// source.read(data);
-// err = import->WriteData(data);
-// // need to supply new file to import to ?
-// while (err == KErrCANewFileHandleRequired)
-// // supply new file in order to continue writing
-// RFile newFile;
-// import->GetSuggestedOutputFileName(fileName);
-// newFile.Open(fileName, EFileWrite);
-// err = import->ContinueWithNewOutputFile(newFile, fileName);
-// newFile.Close();
-// ContentAccess::CImportFile::WriteComplete()
, this will
-// let the agent know that all the data has been transferred and allow it to perform any final processing.
-// err = import->WriteComplete();
-// // When application supplies file handles it must always check to see if
-// // the agent needs a new file handle
-// while(err == KErrCANewFileHandleRequired)
-// RFile newFile;
-// import->GetSuggestedOutputFileName(fileName);
-// newFile.Open(fileName, EFileWrite);
-// err = import->ContinueWithNewOutputFile(newFile, filename);
-// // It is possible that the agent needs yet another file handle
-// newFile.Close(); // agent makes a copy so we don't need to keep our file handle
-// At this stage all the agent's work is done, the CImportFile
object can be deleted.
-// ContentAccess::CImportFile::OutputFileL()
.
-// // loop over all the output files produced
-// for(TInt i =0; i < import->OutputFileCountL(); i++)
-// // Can now retrieve filename, type of file (receipt or content) and
-// // MIME type for the file produced
-// TPtr filename = import->OutputFileL(i).FileName();
-// TOutputType type = import->OutputFileL(i).OutputType();
-// TPtr8 mimetype = import->OutputFileL(i).MimeType();
-// The output files can be either content files or receipts for DRM rights. It is possible that no output
-// files will be generated and the file will be "absorbed" into the agent.
-// Also, it is important to remember that the MIME type and most likely the file extension of the output files are
-// almost certainly different to the MIME type and file extension of the imported file.
-//