|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <concept id="GUID-1B20D403-5FC9-5A61-9D2B-8ACB9D73423C" xml:lang="en"><title>Supplier |
|
13 API Tutorial </title><shortdesc>The Supplier API handles the delivery and transformation of Digital |
|
14 Rights Management (DRM) protected content. It transforms imported DRM content |
|
15 in a device into a secure format for storage. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
16 <p>Supplier API comprises of <xref href="GUID-E6562DDC-C872-3ADA-BF1C-4A04291E8CF9.dita"><apiname>ContentAccess::CSupplier</apiname></xref> and <xref href="GUID-E6562DDC-C872-3ADA-BF1C-4A04291E8CF9.dita"><apiname>ContentAccess::CImportFile</apiname></xref>. </p> |
|
17 <section id="GUID-17D59A99-1491-513C-BC41-BB4ECA22B931"><title>Introduction</title> <p>The |
|
18 Supplier API allows Content Access (CA) agents to publish the supported content |
|
19 MIME types that can be handled by Content Access Framework (CAF). When a file |
|
20 arrive on a device (for example, through a browser), applications check for |
|
21 its MIME types and import the file into CAF. The agent transforms the file |
|
22 into a secure format for using it in the device. </p> <p>The transformation |
|
23 may not be required because the files arrive in a format fit for use in the |
|
24 device. However, some agents might require to protect (encrypt) the content |
|
25 at the moment it arrives, and Supplier API manages this protection. </p> </section> |
|
26 <section><title>Procedure</title><p>The following steps illustrate how to |
|
27 use Supplier API: </p> <ol id="GUID-A2CD1699-28D5-530C-9552-59277385E353"> |
|
28 <li id="GUID-DF9A5E76-B282-568C-A5A1-654A88698B0B"><p><xref href="GUID-1B20D403-5FC9-5A61-9D2B-8ACB9D73423C.dita#GUID-1B20D403-5FC9-5A61-9D2B-8ACB9D73423C/GUID-7501DF89-76B6-52A2-AD3A-6391832F3C5A">Start a new import session</xref> </p> </li> |
|
29 <li id="GUID-2E539668-4A7B-5F55-83D2-1A092ECBCE7E"><p><xref href="GUID-1B20D403-5FC9-5A61-9D2B-8ACB9D73423C.dita#GUID-1B20D403-5FC9-5A61-9D2B-8ACB9D73423C/GUID-74C3F4CF-2D85-568D-B935-B93E1F857F78">Prepare to import a file</xref> </p> </li> |
|
30 <li id="GUID-CAAA7C49-B8FD-51CF-9973-2676B3E01837"><p><xref href="GUID-1B20D403-5FC9-5A61-9D2B-8ACB9D73423C.dita#GUID-1B20D403-5FC9-5A61-9D2B-8ACB9D73423C/GUID-4023F3AD-6CA3-59E3-8148-F9D76480A05E">Import the file</xref> </p> </li> |
|
31 <li id="GUID-5D182213-F5AF-5052-BDB4-D940F61BCDFA"><p><xref href="GUID-1B20D403-5FC9-5A61-9D2B-8ACB9D73423C.dita#GUID-1B20D403-5FC9-5A61-9D2B-8ACB9D73423C/GUID-52D00B05-3EB5-5C10-A3BC-8AC12B968FF0">Transfer the file to the Content Access Agent</xref> </p> </li> |
|
32 <li id="GUID-3078BA87-4D9D-5707-8F7F-107EFD372CD0"><p><xref href="GUID-1B20D403-5FC9-5A61-9D2B-8ACB9D73423C.dita#GUID-1B20D403-5FC9-5A61-9D2B-8ACB9D73423C/GUID-5436E5BC-793C-5373-B9A9-404D6ECC2EBA">Complete the import</xref> </p> </li> |
|
33 <li id="GUID-A74B75B3-3A21-5BC0-A24C-186A915C5EAC"><p><xref href="GUID-1B20D403-5FC9-5A61-9D2B-8ACB9D73423C.dita#GUID-1B20D403-5FC9-5A61-9D2B-8ACB9D73423C/GUID-EDAB286B-FBC9-5DAF-A466-7B07F2A2FC29"> Check the output file, if necessary</xref>. </p> </li> |
|
34 </ol> </section> |
|
35 <section id="GUID-7501DF89-76B6-52A2-AD3A-6391832F3C5A"><title>Start a new |
|
36 import session</title> <p>Use <xref href="GUID-E6562DDC-C872-3ADA-BF1C-4A04291E8CF9.dita"><apiname>ContentAccess::CSupplier</apiname></xref> to |
|
37 import files into CAF. </p> <p>Create an instance of <xref href="GUID-E6562DDC-C872-3ADA-BF1C-4A04291E8CF9.dita"><apiname>CSupplier</apiname></xref> to |
|
38 start an import session and set the output path according to an application's |
|
39 requirements. </p> <codeblock id="GUID-BCD346E6-9077-546A-81DA-E4CE1706CB88" xml:space="preserve">// Create Supplier |
|
40 CSupplier *mySupplier = CSupplier::NewL(); |
|
41 |
|
42 // Set output path for DRM protected content |
|
43 _LIT(KPath,"C:\\myOutputFiles"); |
|
44 mySupplier->SetOutputDirectoryL(KPath());</codeblock><note><ul> |
|
45 <li id="GUID-25C5C79D-B6C9-59FE-82D7-A5A04950D94A"><p>It is not necessary |
|
46 to set the output path if the application provides output file handles to |
|
47 the CA agent. </p> </li> |
|
48 <li id="GUID-B4029DD4-9A76-5647-9DBB-18A2D64E6089"><p> <xref href="GUID-E6562DDC-C872-3ADA-BF1C-4A04291E8CF9.dita"><apiname>ContentAccess::CSupplier</apiname></xref> uses |
|
49 its <xref href="GUID-E6562DDC-C872-3ADA-BF1C-4A04291E8CF9.dita"><apiname>ContentAccess::CAgentResolver</apiname></xref> member |
|
50 to determine which CA agent must be used to import each file. For more information, |
|
51 see <xref href="GUID-9993D750-9116-55B2-812A-7A92C50F467F.dita">Apparc Recognizer |
|
52 for CAF</xref>. </p> </li> |
|
53 </ul></note> </section> |
|
54 <section id="GUID-74C3F4CF-2D85-568D-B935-B93E1F857F78"><title>Prepare to |
|
55 import the file</title> <p>Preparing to import a DRM protected file includes |
|
56 the following steps: </p> <ol id="GUID-5EEA53C8-1B3F-50A9-8C22-8D61B11CE28B"> |
|
57 <li id="GUID-960C7AB2-5241-521C-BBBE-5B09294F43C0"><p>Checking for supported |
|
58 MIME types </p> </li> |
|
59 <li id="GUID-C949EF2E-7B80-5E30-9D0A-AD912579E595"><p>Creating a <xref href="GUID-E6562DDC-C872-3ADA-BF1C-4A04291E8CF9.dita"><apiname>CMetaDataList</apiname></xref> object </p> </li> |
|
60 </ol> <p><b>Checking for supported MIME types</b> </p> <p>Before importing |
|
61 a file into the content access framework, an application must check if the |
|
62 MIME type of the file is supported. Each agent publishes a list of supported |
|
63 MIME types and the list is configured in the agent's resource file. Use <xref href="GUID-E6562DDC-C872-3ADA-BF1C-4A04291E8CF9.dita"><apiname>ContentAccess::CSupplier::IsImportSupported()</apiname></xref> to |
|
64 check the list of supported MIME type of files. </p> <codeblock id="GUID-EB6353F1-D53C-578A-BE4C-B569C4719960" xml:space="preserve">if(!mySupplier->IsImportSupported(myMimeType)) |
|
65 { |
|
66 return; |
|
67 }</codeblock> <p><b>Creating a CMetaDataList object </b> </p> <p>The <xref href="GUID-E6562DDC-C872-3ADA-BF1C-4A04291E8CF9.dita"><apiname>CMetaDataList</apiname></xref> object stores information |
|
68 associated with an import file, and it is passed to the CA agent. For example, |
|
69 OMA DRM 1.0 files might contain HTTP header<codeph> X-Oma-Drm-Separate-Delivery</codeph>, |
|
70 which informs the agent about the time duration within which rights are expected |
|
71 for the content. </p> <p>The following code snippet shows creating a <xref href="GUID-E6562DDC-C872-3ADA-BF1C-4A04291E8CF9.dita"><apiname>CMetaDataList</apiname></xref> object and information |
|
72 about the duration (for example, 12 seconds) in which rights are expected </p> <codeblock id="GUID-A371B670-1E6D-5513-8D5D-D6559170ED1F" xml:space="preserve">// Create meta-data array |
|
73 CMetaDataArray *metaDataArray = new (ELeave) CMetaDataArray(); |
|
74 CleanupStack::PushL(metaDataArray); |
|
75 |
|
76 // Add any useful information we can think of.... |
|
77 metaDataArray->AddL(_L("Content Type"),_L("application/vnd.oma.drm.dm")); |
|
78 metaDataArray->AddL(_L("X-Oma-Drm-Separate-Delivery"),_L("12"));</codeblock> </section> |
|
79 <section id="GUID-4023F3AD-6CA3-59E3-8148-F9D76480A05E"><title>Import a file</title> <ol id="GUID-8FC14D51-FB3B-5FC2-A24D-72AB9244CC93"> |
|
80 <li id="GUID-D1491E70-F9DF-5697-810A-9C91EFF5FF21"><p>Create the <codeph>CImportFile</codeph> object </p> </li> |
|
81 <li id="GUID-F178800B-A2D5-50BC-B2D7-C363FBDDF43E"><p>Generate output files </p> </li> |
|
82 </ol> <p><b>Creating the CImportFile object</b> </p> <p> <xref href="GUID-E6562DDC-C872-3ADA-BF1C-4A04291E8CF9.dita"><apiname>ContentAccess::CImportFile()</apiname></xref> allows |
|
83 to write a file to CAF. Use <xref href="GUID-E6562DDC-C872-3ADA-BF1C-4A04291E8CF9.dita"><apiname>ContentAccess::CSupplier::ImportFileL()</apiname></xref> to |
|
84 create a <xref href="GUID-E6562DDC-C872-3ADA-BF1C-4A04291E8CF9.dita"><apiname>CImportFile</apiname></xref> object |
|
85 for importing a file. The parameters supplied must indicate whether the agent |
|
86 generates the output files or if the application generates the output files |
|
87 for the agents on demand. </p> <codeblock id="GUID-D5A84DF4-6175-5F56-97EE-2EDEA2E772B9" xml:space="preserve">// Create the import object, passing in the metaDataArray created earlier |
|
88 // The application must supply the output files |
|
89 |
|
90 CImportFile *import = mySupplier->ImportFileL(sourceMimeType, *metaDataArray);</codeblock> <p>Applications |
|
91 use the <xref href="GUID-E6562DDC-C872-3ADA-BF1C-4A04291E8CF9.dita"><apiname>CImportFile</apiname></xref> object |
|
92 to transfer the content to CAF. </p> <p> <b>Note</b>: </p> <ul> |
|
93 <li id="GUID-8B63B854-B857-5AC9-90BC-4A777B31A1E5"><p>You must create new <xref href="GUID-E6562DDC-C872-3ADA-BF1C-4A04291E8CF9.dita"><apiname>CImportFile</apiname></xref> objects to import multiple |
|
94 files. </p> </li> |
|
95 <li id="GUID-FC33D732-6026-56DC-9047-A25188E4384A"><p>You can transfer only |
|
96 one file in an instance, even if multiple output files are produced. </p> </li> |
|
97 </ul> <p><b>Generating output files</b> </p> <p>Use <xref href="GUID-E6562DDC-C872-3ADA-BF1C-4A04291E8CF9.dita"><apiname>CSupplier::ImportFileL()</apiname></xref> to |
|
98 generate the output files and specify the appropriate parameters. By default, |
|
99 application generates the output file. Otherwise, the agent or application |
|
100 can generate the output file based on the specified parameters. </p> <p><i>Agents |
|
101 generating output files</i> </p> <p>Applications must specify the following |
|
102 information if they require agents to generate the output files: </p> <ul> |
|
103 <li id="GUID-E5B68249-133C-5C82-97AA-D47EFD73D984"><p>Specify the file name |
|
104 in <xref href="GUID-E6562DDC-C872-3ADA-BF1C-4A04291E8CF9.dita"><apiname>CSupplier::ImportFileL()</apiname></xref> indicating |
|
105 that agent must generate output files. </p> </li> |
|
106 <li id="GUID-3AEBE53D-B67F-58EA-A51E-E608851EA15B"><p>Use <xref href="GUID-E6562DDC-C872-3ADA-BF1C-4A04291E8CF9.dita"><apiname>CSupplier::SetOutputDirectoryL()</apiname></xref> to |
|
107 specify the directory for the files to be generated. Optionally, applications |
|
108 can decide to store the output files in their private directory. </p> </li> |
|
109 <li id="GUID-9A4FA11A-CA72-5D46-89DE-8D086F788892"><p>Check for the number |
|
110 of generated output files and their stored location, when the import operation |
|
111 is complete. </p> </li> |
|
112 </ul> <p><i>Applications generating output files</i></p> <p>If the filename |
|
113 is not passed to the agent, applications provide output files to the agents. |
|
114 This allows applications to open files in their own private directory and |
|
115 ask the CAF agent to store the output in those files. This involves the following |
|
116 considerations: </p> <ul> |
|
117 <li id="GUID-F48701C5-8FAA-5B36-BF87-118B2D7D6784"><p>If an agent requires |
|
118 a new output file handle in order to continue during import, a call to <xref href="GUID-E6562DDC-C872-3ADA-BF1C-4A04291E8CF9.dita"><apiname>CImportFile::WriteData()</apiname></xref> or <xref href="GUID-E6562DDC-C872-3ADA-BF1C-4A04291E8CF9.dita"><apiname>CImportFile::WriteDataComplete()</apiname></xref> returns |
|
119 an error code of <xref href="GUID-E6562DDC-C872-3ADA-BF1C-4A04291E8CF9.dita"><apiname>KErrCANewFileHandleRequired</apiname></xref>. </p> </li> |
|
120 <li id="GUID-CD957292-7438-53D2-9960-9648F07F017C"><p>Applications must open |
|
121 a new output file with write access and call <xref href="GUID-E6562DDC-C872-3ADA-BF1C-4A04291E8CF9.dita"><apiname>CImportFile::ContinueWithNewOutputFile()</apiname></xref> to |
|
122 supply the new handle to the agent. IF handles are required further, <xref href="GUID-E6562DDC-C872-3ADA-BF1C-4A04291E8CF9.dita"><apiname>CImportFile::ContinueWithNewOutputFile()</apiname></xref> returns <xref href="GUID-E6562DDC-C872-3ADA-BF1C-4A04291E8CF9.dita"><apiname>KErrCANewFileHandleRequired</apiname></xref> and the |
|
123 application must repeat this step with another file. </p> <p>The agent must |
|
124 cache its state before returning <xref href="GUID-E6562DDC-C872-3ADA-BF1C-4A04291E8CF9.dita"><apiname>KErrCANewFileHandleRequired</apiname></xref>. </p> </li> |
|
125 <li id="GUID-CC0B5AF5-C1F0-5AFE-ACA9-5365CA3DAA45"><p>The application must |
|
126 not resend the same <xref href="GUID-E6562DDC-C872-3ADA-BF1C-4A04291E8CF9.dita"><apiname>CImportFile::WriteData()</apiname></xref> or <xref href="GUID-E6562DDC-C872-3ADA-BF1C-4A04291E8CF9.dita"><apiname>CImportFile::WriteDataComplete()</apiname></xref> call. </p> </li> |
|
127 </ul><note> At the end of the import operation the output files are listed |
|
128 irrespective of whether they were supplied by the application or the agent.</note> </section> |
|
129 <section id="GUID-52D00B05-3EB5-5C10-A3BC-8AC12B968FF0"><title>Transfer the |
|
130 file to the Content Access Agent</title><p>Use <xref href="GUID-E6562DDC-C872-3ADA-BF1C-4A04291E8CF9.dita"><apiname>ContentAccess::CImportFile</apiname></xref> to |
|
131 write the file data to CAF. <xref href="GUID-E6562DDC-C872-3ADA-BF1C-4A04291E8CF9.dita"><apiname>ContentAccess::CSupplier</apiname></xref> creates <xref href="GUID-E6562DDC-C872-3ADA-BF1C-4A04291E8CF9.dita"><apiname>ContentAccess::CImportFile</apiname></xref> which |
|
132 only imports a single file. An application must call <xref href="GUID-E6562DDC-C872-3ADA-BF1C-4A04291E8CF9.dita"><apiname>WriteData()</apiname></xref> to |
|
133 transfer a field in chunks to the CAF. </p> <p>The following code snippet |
|
134 explains this. </p> <codeblock id="GUID-513744BC-F54A-55F5-A9BD-CA5463CB9DB1" xml:space="preserve">// importing the file data |
|
135 ImportFile *import; |
|
136 TFileName fileName; |
|
137 TPath outputfileName; |
|
138 TBuf8 data <128> |
|
139 _LIT(KDirectoryPath, "C:\\private\\12345678\\"); |
|
140 ... |
|
141 |
|
142 while(!endofsource) |
|
143 { |
|
144 source.read(data); |
|
145 err = import->WriteData(data); |
|
146 |
|
147 // When application supplies file handles it must always check to see if |
|
148 // the agent needs a new file handle |
|
149 |
|
150 while(err == KErrCANewFileHandleRequired) |
|
151 { |
|
152 RFile newFile; |
|
153 import->GetSuggestedOutputFileName(fileName); |
|
154 outputFileName.Copy(KDirectoryPath); |
|
155 outputFileName.Append(fileName); |
|
156 newFile.Open(outputFileName, EFileWrite); |
|
157 err = import->ContinueWithNewOutputFile(newFile, outputFileName); |
|
158 |
|
159 // It is possible that the agent needs yet another file handle |
|
160 newFile.Close(); // agent makes a copy so we don't need to keep our file handle |
|
161 } |
|
162 }</codeblock> </section> |
|
163 <section id="GUID-5436E5BC-793C-5373-B9A9-404D6ECC2EBA"><title>Complete the |
|
164 import</title> <p>When the data is written, use <xref href="GUID-E6562DDC-C872-3ADA-BF1C-4A04291E8CF9.dita"><apiname>ContentAccess::CImportFile::WriteDataComplete()</apiname></xref> to |
|
165 inform the agent that data transfer is complete, allowing it to perform any |
|
166 final processing. </p> <p>The following code snippet explains this step: </p> <codeblock id="GUID-1843B2F1-A862-52DB-998F-AE6224726EFB" xml:space="preserve">err = import->WriteDataComplete(); |
|
167 |
|
168 // When the application supplies file handles it must always check to see if |
|
169 // the agent needs a new file handle |
|
170 while(err == KErrCANewFileHandleRequired) |
|
171 { |
|
172 RFile newFile; |
|
173 import->GetSuggestedOutputFileName(fileName); |
|
174 outputFileName.Copy(KDirectoryPath); |
|
175 outputFileName.Append(fileName); |
|
176 newFile.Open(outputFileName, EFileWrite); |
|
177 err = import->ContinueWithNewOutputFile(newFile, outputFileName); |
|
178 // It is possible that the agent needs yet another file handle |
|
179 newFile.Close(); // agent makes a copy so we don't need to keep our file handle |
|
180 } |
|
181 |
|
182 // Finished |
|
183 //At this stage all the agent's work is done and the CImportFile object can be deleted. </codeblock> </section> |
|
184 <section id="GUID-EDAB286B-FBC9-5DAF-A466-7B07F2A2FC29"><title>Check the output |
|
185 file</title> <p>When import is complete, use <xref href="GUID-E6562DDC-C872-3ADA-BF1C-4A04291E8CF9.dita"><apiname>ContentAccess::CImportFile::OutputFileL()</apiname></xref> to |
|
186 list all the output files produced. The output files can be either content |
|
187 files or receipts for DRM rights. </p> <codeblock id="GUID-A4C87E1E-719D-53CF-9A2F-7EEE8A16919D" xml:space="preserve">// loop over all the output files produced |
|
188 for(TInt I =0; I < import->OutputFileCountL(); I++) |
|
189 { |
|
190 // Can now retrieve filename, type of file (receipt or content) and MIME type for the file produced |
|
191 TPtr filename = import->OutputFileL(I).FileName(); |
|
192 TOutputType type = import->OutputFileL(I).OutputType(); |
|
193 TPtr8 mimetype = import->OutputFileL(I).MimeType(); |
|
194 }</codeblock> <p> <b>Note</b>: </p> <p>The MIME type and the file extension |
|
195 of the output files can be different to the MIME type and file extension of |
|
196 the imported file. </p> </section> |
|
197 </conbody><related-links> |
|
198 <link href="GUID-84B6389A-55CC-53EB-8725-65F753FD7217.dita"><linktext> CAF Overview</linktext> |
|
199 </link> |
|
200 </related-links></concept> |