1 // Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies). |
|
2 // All rights reserved. |
|
3 // This component and the accompanying materials are made available |
|
4 // under the terms of the License "Eclipse Public License v1.0" |
|
5 // which accompanies this distribution, and is available |
|
6 // at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
7 // |
|
8 // Initial Contributors: |
|
9 // Nokia Corporation - initial contribution. |
|
10 // |
|
11 // Contributors: |
|
12 // |
|
13 // Description: |
|
14 // NOTE: For the purpose of clarity we have ommitted full error checking in the |
|
15 // <hr> |
|
16 // The Supplier API allows agents to publicise the MIME types they are |
|
17 // interested in. When those files arrive on the device, message handling |
|
18 // applications can check these MIME types and import the file |
|
19 // into CAF. The agent transforms the file into a different format |
|
20 // for use within the device. |
|
21 // In most cases this won't be necessary, since the files will arrive in the |
|
22 // same format that they will be used in. However, some agents require the device |
|
23 // to protect (encrypt) the content at the moment it arrives; the Supplier |
|
24 // API fulfills that role. |
|
25 // The classes used in the supply operation are: |
|
26 // <code>ContentAccess::CSupplier</code> and instances of <code>ContentAccess::CImportFile</code>. |
|
27 // <hr> |
|
28 // The <code>ContentAccess::CSupplier</code> is designed to allow several unrelated files to be imported |
|
29 // into CAF. It uses its <code>ContentAccess::CAgentResolver</code> member to determine |
|
30 // which CA agent should be used to import each file. The <code>CAgentResolver</code> builds |
|
31 // a list of all agents when it is created and updates the list if new agents |
|
32 // are installed. |
|
33 // A typical import session will start with the creation of a <code>CSupplier</code>, e.g., |
|
34 // //Create Supplier |
|
35 // CSupplier *mySupplier = CSupplier::NewL(); |
|
36 // Most applications will have a preference for the directory where output files |
|
37 // are to be stored. Usually the first thing to do with the new <code>CSupplier</code> instance |
|
38 // is to set the output path. |
|
39 // //Set output path for DRM protected content |
|
40 // _LIT(KPath,"C:\myOutputFiles"); |
|
41 // mySupplier->SetOutputDirectoryL(KPath()); |
|
42 // It is not necessary to set the output path if the application |
|
43 // provides output file handles to the agent. |
|
44 // <hr> |
|
45 // <b> Check that the MIME type is supported </b> |
|
46 // Before importing a file into the content access framework, an application |
|
47 // should check that the MIME type of the file is supported. Each agent publishes a |
|
48 // list of the MIME types it supports. The list is configured in the agent's |
|
49 // resource file and can be checked using <code>ContentAccess::CSupplier::IsImportSupported()</code> |
|
50 // if(!mySupplier->IsImportSupported(myMimeType)) |
|
51 // return; |
|
52 // <b> Create a CMetaDataList object </b> |
|
53 // The <code>CMetaDataList</code> object is used to store any information associated with the import file that |
|
54 // may be useful for the agent. These values will be passed to the agent. |
|
55 // For example OMA DRM 1.0 files sometimes arrive with the HTTP header |
|
56 // <code>X-Oma-Drm-Separate-Delivery</code>. This informs the agent how long before rights are expected |
|
57 // for the content. If the rights were expected in 12 seconds it would be something like |
|
58 // the following: |
|
59 // // Create meta-data array |
|
60 // CMetaDataArray *metaDataArray = new (ELeave) CMetaDataArray(); |
|
61 // CleanupStack::PushL(metaDataArray); |
|
62 // // Add any useful information we can think of.... |
|
63 // metaDataArray->AddL(_L("Content Type"), _L("application/vnd.oma.drm.dm")); |
|
64 // metaDataArray->AddL(_L("X-Oma-Drm-Separate-Delivery"), _L("12")); |
|
65 // The file is 'written' to CAF using a <code>ContentAccess::CImportFile</code> object. |
|
66 // <code>ContentAccess::CSupplier::ImportFile()</code> creates an <code>CImportFile</code> object for importing a file. |
|
67 // The parameters supplied indicate whether the agent will create the output files or whether |
|
68 // the application using CAF will generate output files for the agent on demand. |
|
69 // // Create the import object, passing in the metaDataArray created earlier |
|
70 // // The application will supply the output files |
|
71 // CImportFile *import = mySupplier->ImportFileL(sourceMimeType, *metaDataArray); |
|
72 // The application should now transfer the file to CAF using the <code>CImportFile</code> object. |
|
73 // Only one file can be transferred by each instance although several output files |
|
74 // may be produced. Applications should create new <code>CImportFile</code> objects in order to import more files. |
|
75 // <b> Agents Generating the Output files </b> |
|
76 // If the application wants the agent to generate the output files, it should supply a suggested |
|
77 // file name in the call to <code>CSupplier::ImportFile()</code>. Even if this parameter is a zero length |
|
78 // descriptor, it still indicates that the agent is responsible for generating output files. |
|
79 // Agents will create the output files in a directory nominated by the application when it called |
|
80 // <code>CSupplier::SetOutputDirectoryL()</code> or they may decide to store the output files in their private |
|
81 // directory. |
|
82 // Applications should check at the end of the import to find out how many output files were created |
|
83 // and where they are stored. |
|
84 // <b> Application generating the Output files</b> |
|
85 // If no suggested file name is passed to the agent, the application will provide output files for |
|
86 // the agent to use. This mechanism allows applications to open files in their own private directory and |
|
87 // ask the CAF agent to store the output in those files. |
|
88 // The way it works is the same as an any other import operation, the difference is that the call |
|
89 // to <code>CImportFile::WriteData()</code> or <code>CImportFile::WriteComplete()</code> may return an error code of |
|
90 // <code>KErrCANewFileHandleRequired</code>. |
|
91 // This error code indicates that the agent needs a new output file handle in order to continue. The |
|
92 // application should open a new output file with write access and call <code>CImportFile::ContinueWithNewOutputFile()</code> |
|
93 // to supply the new handle to the agent. It is possible that further handles may be needed, if so |
|
94 // <code>CImportFile::ContinueWithNewOutputFile()</code> will return <code>KErrCANewFileHandleRequired</code> and the application should |
|
95 // repeat the procedure with another file. |
|
96 // The agent must cache its state before returning <code>KErrCANewFileHandleRequired</code>. The application MUST NOT resend |
|
97 // the same <code>WriteData()</code> or <code>WriteComplete()</code> command. |
|
98 // At the end of the import operation the output files will still be listed regardless of whether |
|
99 // they were supplied by the application or the agent. |
|
100 // <hr> |
|
101 // <code>ContentAccess::CImportFile</code> is the class used to write the file data to CAF. |
|
102 // It is created by <code>ContentAccess::CSupplier</code> and can only be used to import a single file. |
|
103 // An application should call <code>WriteData()</code> to transfer a field in 'chunks' to the Content |
|
104 // Access Framework. Usually this would be something like the following: |
|
105 // TFileName fileName; |
|
106 // TBuf8<128> data; |
|
107 // TInt err = KErrNone; |
|
108 // // start importing content |
|
109 // while( (source still has data) && (err==KErrNone) ) |
|
110 // source.read(data); |
|
111 // err = import->WriteData(data); |
|
112 // // need to supply new file to import to ? |
|
113 // while (err == KErrCANewFileHandleRequired) |
|
114 // // supply new file in order to continue writing |
|
115 // RFile newFile; |
|
116 // import->GetSuggestedOutputFileName(fileName); |
|
117 // newFile.Open(fileName, EFileWrite); |
|
118 // err = import->ContinueWithNewOutputFile(newFile, fileName); |
|
119 // newFile.Close(); |
|
120 // <hr> |
|
121 // When all the data is written, the application should call <code>ContentAccess::CImportFile::WriteComplete()</code>, this will |
|
122 // let the agent know that all the data has been transferred and allow it to perform any final processing. |
|
123 // err = import->WriteComplete(); |
|
124 // // When application supplies file handles it must always check to see if |
|
125 // // the agent needs a new file handle |
|
126 // while(err == KErrCANewFileHandleRequired) |
|
127 // RFile newFile; |
|
128 // import->GetSuggestedOutputFileName(fileName); |
|
129 // newFile.Open(fileName, EFileWrite); |
|
130 // err = import->ContinueWithNewOutputFile(newFile, filename); |
|
131 // // It is possible that the agent needs yet another file handle |
|
132 // newFile.Close(); // agent makes a copy so we don't need to keep our file handle |
|
133 // At this stage all the agent's work is done, the <code>CImportFile</code> object can be deleted. |
|
134 // <hr> |
|
135 // When the import is finished the application may wish to check if any output files have |
|
136 // been produced. The list of output files is accessed using <code>ContentAccess::CImportFile::OutputFileL()</code>. |
|
137 // // loop over all the output files produced |
|
138 // for(TInt i =0; i < import->OutputFileCountL(); i++) |
|
139 // // Can now retrieve filename, type of file (receipt or content) and |
|
140 // // MIME type for the file produced |
|
141 // TPtr filename = import->OutputFileL(i).FileName(); |
|
142 // TOutputType type = import->OutputFileL(i).OutputType(); |
|
143 // TPtr8 mimetype = import->OutputFileL(i).MimeType(); |
|
144 // The output files can be either content files or receipts for DRM rights. It is possible that no output |
|
145 // files will be generated and the file will be "absorbed" into the agent. |
|
146 // Also, it is important to remember that the MIME type and most likely the file extension of the output files are |
|
147 // almost certainly different to the MIME type and file extension of the imported file. |
|
148 // <hr> |
|
149 // |
|
150 // |
|
151 |
|
152 /** |
|
153 @page CSupplierAPI Importing files into the Content Access Framework |
|
154 - @ref SupplierAPI |
|
155 - @ref ImportSession |
|
156 - @ref ImportCAF |
|
157 - @ref Importfile |
|
158 - @ref ImportComplete |
|
159 - @ref ImportOutput |
|
160 code examples given below. For examples with error checking see @ref ExampleSupplier2. |
|
161 @section SupplierAPI Supplier API |
|
162 @section ImportSession Starting a new import session |
|
163 @code |
|
164 @endcode |
|
165 @code |
|
166 @endcode |
|
167 @section ImportCAF Preparing to import the file |
|
168 @code |
|
169 @endcode |
|
170 @code |
|
171 @endcode |
|
172 @section ImportFile Creating the CImportFile object |
|
173 @code |
|
174 @endcode |
|
175 @section Importfile Transferring the file to the Content Access Agent |
|
176 @code |
|
177 @endcode |
|
178 @section ImportComplete Completing the Import |
|
179 @code |
|
180 @endcode |
|
181 @section ImportOutput Output files produced |
|
182 @code |
|
183 @endcode |
|
184 */ |
|