|
1 /* |
|
2 * Copyright (c) 2003-2007 Nokia Corporation and/or its subsidiary(-ies). |
|
3 * All rights reserved. |
|
4 * This component and the accompanying materials are made available |
|
5 * under the terms of the License "Eclipse Public License v1.0" |
|
6 * which accompanies this distribution, and is available |
|
7 * at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
8 * |
|
9 * Initial Contributors: |
|
10 * Nokia Corporation - initial contribution. |
|
11 * |
|
12 * Contributors: |
|
13 * |
|
14 * Description: |
|
15 * |
|
16 */ |
|
17 |
|
18 |
|
19 |
|
20 /** |
|
21 @file |
|
22 |
|
23 @publishedPartner |
|
24 @released |
|
25 */ |
|
26 |
|
27 |
|
28 #ifndef __DATA_H__ |
|
29 #define __DATA_H__ |
|
30 |
|
31 #include <e32base.h> |
|
32 #include <f32file.h> |
|
33 #include <caf/caftypes.h> |
|
34 |
|
35 namespace ContentAccess |
|
36 { |
|
37 class CAgentFactory; |
|
38 class CAgentInfo; |
|
39 class TVirtualPathPtr; |
|
40 class CAgentData; |
|
41 class RAttributeSet; |
|
42 class RStringAttributeSet; |
|
43 |
|
44 |
|
45 /** |
|
46 Allows clients to read data from a content object. |
|
47 |
|
48 This class is initialised with an agent implementation that is |
|
49 responsible for this content object. |
|
50 |
|
51 @publishedPartner |
|
52 @released |
|
53 */ |
|
54 class CData : public CBase |
|
55 { |
|
56 public: |
|
57 /** |
|
58 Creates a new CData object. |
|
59 |
|
60 @param aVirtualPath The content object to read |
|
61 @param aIntent The intended use of the content. |
|
62 @param aShareMode The file share mode used to open this content. |
|
63 @return The new CData object. |
|
64 |
|
65 @leave KErrNotFound The content object with the given UniqueId does not exist. |
|
66 @leave KErrCAPendingRights The rights have not yet arrived but are expected soon. |
|
67 @leave KErrCANoPermission Rights exist but the specified intent is not permitted. |
|
68 @leave KErrCANoRights No rights exist for the content object. |
|
69 @leave KErrCANotSupported Unable to open the object with the specified UniqueId, it may be a container object. |
|
70 @leave KErrPermissionDenied The agent does not allow the client to access the content object. |
|
71 @leave KErrAccessDenied The content is already in use. |
|
72 @leave ... One of the other CAF error codes defined in \c caferr.h |
|
73 or one of the other system-wide error codes |
|
74 for any other errors. |
|
75 */ |
|
76 IMPORT_C static CData* NewL(const TVirtualPathPtr& aVirtualPath, |
|
77 TIntent aIntent, TContentShareMode aShareMode); |
|
78 |
|
79 /** |
|
80 Creates a new CData object. |
|
81 |
|
82 @param aVirtualPath The content object to read. |
|
83 @param aShareMode The file share mode used to open this content. |
|
84 @return The new CData object. |
|
85 |
|
86 @leave KErrNotFound The content object with the given UniqueId does not exist. |
|
87 @leave KErrCAPendingRights The rights have not yet arrived but are expected soon. |
|
88 @leave KErrCANoPermission Rights exist but the specified intent is not permitted. |
|
89 @leave KErrCANoRights No rights exist for the content object. |
|
90 @leave KErrCANotSupported Unable to open the object with the specified UniqueId, it may be a container object. |
|
91 @leave KErrPermissionDenied The agent does not allow the client to access the content object. |
|
92 @leave KErrAccessDenied The content is already in use. |
|
93 @leave ... One of the other CAF error codes defined in \c caferr.h |
|
94 or one of the other system-wide error codes for |
|
95 any other errors. |
|
96 */ |
|
97 IMPORT_C static CData* NewL(const TVirtualPathPtr& aVirtualPath, |
|
98 TContentShareMode aShareMode); |
|
99 |
|
100 |
|
101 /** |
|
102 Creates a new CData object |
|
103 |
|
104 @param aVirtualPath The content object to read. |
|
105 @param aIntent The intended use of the content. |
|
106 @param aShareMode The file share mode used to open this content. |
|
107 @return The new CData object. |
|
108 |
|
109 @leave KErrNotFound The content object with the given UniqueId does not exist. |
|
110 @leave KErrCAPendingRights The rights have not yet arrived but are expected soon. |
|
111 @leave KErrCANoPermission Rights exist but the specified intent is not permitted. |
|
112 @leave KErrCANoRights No rights exist for the content object. |
|
113 @leave KErrCANotSupported Unable to open the object with the specified UniqueId, it may be a container object. |
|
114 @leave KErrPermissionDenied The agent does not allow the client to access the content object. |
|
115 @leave KErrAccessDenied The content is already in use. |
|
116 @leave ... One of the other CAF error codes defined in \c caferr.h |
|
117 or one of the other system-wide error codes for |
|
118 any other errors. |
|
119 */ |
|
120 IMPORT_C static CData* NewLC(const TVirtualPathPtr& aVirtualPath, |
|
121 TIntent aIntent, TContentShareMode aShareMode); |
|
122 |
|
123 /** |
|
124 Creates a new CData object |
|
125 |
|
126 @param aVirtualPath The content object to read. |
|
127 @param aShareMode The file share mode used to open this content. |
|
128 @return The new CData object. |
|
129 |
|
130 @leave KErrNotFound The content object with the given UniqueId does not exist. |
|
131 @leave KErrCAPendingRights The rights have not yet arrived but are expected soon. |
|
132 @leave KErrCANoPermission Rights exist but the specified intent is not permitted. |
|
133 @leave KErrCANoRights No rights exist for the content object. |
|
134 @leave KErrCANotSupported Unable to open the object with the specified UniqueId, it may be a container object. |
|
135 @leave KErrPermissionDenied The agent does not allow the client to access the content object. |
|
136 @leave KErrAccessDenied The content is already in use. |
|
137 @leave ... One of the other CAF error codes defined in \c caferr.h |
|
138 or one of the other system-wide error codes for |
|
139 any other errors. |
|
140 */ |
|
141 IMPORT_C static CData* NewLC(const TVirtualPathPtr& aVirtualPath, |
|
142 TContentShareMode aShareMode); |
|
143 |
|
144 |
|
145 /** |
|
146 Creates a new CData object. |
|
147 |
|
148 @param aFile An open RFile handle, the agent will make a duplicate of this handle. |
|
149 The underlying RFs session should be shared for transfer to other processes using RFs::ShareProtected(), since the agent may use transfer this handle to its own or one of the system servers. |
|
150 @param aUniqueId The content object to read. |
|
151 @param aIntent The intended use of the content. |
|
152 @return The new CData object. |
|
153 |
|
154 @leave KErrNotFound The content object with the given UniqueId does not exist. |
|
155 @leave KErrCAPendingRights The rights have not yet arrived but are expected soon. |
|
156 @leave KErrCANoPermission Rights exist but the specified intent is not permitted. |
|
157 @leave KErrCANoRights No rights exist for the content object. |
|
158 @leave KErrCANotSupported Unable to open the object with the specified UniqueId, it may be a container object. |
|
159 @leave KErrPermissionDenied The agent does not allow the client to access the content object. |
|
160 @leave KErrAccessDenied The content is already in use. |
|
161 @leave ... One of the other CAF error codes defined in \c caferr.h |
|
162 or one of the other system-wide error codes for |
|
163 any other errors. |
|
164 */ |
|
165 IMPORT_C static CData* NewL(RFile& aFile, const TDesC& aUniqueId, TIntent aIntent); |
|
166 |
|
167 /** |
|
168 Creates a new CData object. |
|
169 |
|
170 @param aFile An open RFile handle, the agent will make a duplicate of this handle. |
|
171 The underlying RFs session should be shared for transfer to other processes using RFs::ShareProtected(), since the agent may use transfer this handle to its own or one of the system servers. |
|
172 @param aUniqueId The content object to read. |
|
173 @return The new CData object. |
|
174 |
|
175 @leave KErrNotFound The content object with the given UniqueId does not exist. |
|
176 @leave KErrCAPendingRights The rights have not yet arrived but are expected soon. |
|
177 @leave KErrCANoPermission Rights exist but the specified intent is not permitted. |
|
178 @leave KErrCANoRights No rights exist for the content object. |
|
179 @leave KErrCANotSupported Unable to open the object with the specified UniqueId, it may be a container object. |
|
180 @leave KErrPermissionDenied The agent does not allow the client to access the content object. |
|
181 @leave KErrAccessDenied The content is already in use. |
|
182 @leave ... One of the other CAF error codes defined in \c caferr.h |
|
183 or one of the other system-wide error codes for |
|
184 any other errors. |
|
185 */ |
|
186 IMPORT_C static CData* NewL(RFile& aFile, const TDesC& aUniqueId); |
|
187 |
|
188 /** |
|
189 Creates a new CData object. |
|
190 |
|
191 @param aFile An open RFile handle, the agent will make a duplicate of this handle. |
|
192 The underlying RFs session should be shared for transfer to other processes using RFs::ShareProtected(), since the agent may use transfer this handle to its own or one of the system servers. |
|
193 @param aUniqueId The content object to read. |
|
194 @param aIntent The intended use of the content. |
|
195 @return The new CData object. |
|
196 |
|
197 @leave KErrNotFound The content object with the given UniqueId does not exist. |
|
198 @leave KErrCAPendingRights The rights have not yet arrived but are expected soon. |
|
199 @leave KErrCANoPermission Rights exist but the specified intent is not permitted. |
|
200 @leave KErrCANoRights No rights exist for the content object. |
|
201 @leave KErrCANotSupported Unable to open the object with the specified UniqueId, it may be a container object. |
|
202 @leave KErrPermissionDenied The agent does not allow the client to access the content object. |
|
203 @leave KErrAccessDenied The content is already in use. |
|
204 @leave ... One of the other CAF error codes defined in \c caferr.h |
|
205 or one of the other system-wide error codes |
|
206 for any other errors. |
|
207 */ |
|
208 IMPORT_C static CData* NewLC(RFile& aFile, const TDesC& aUniqueId, TIntent aIntent); |
|
209 |
|
210 /** |
|
211 Creates a new CData object. |
|
212 |
|
213 @param aFile An open RFile handle, the agent will make a duplicate of this handle. |
|
214 The underlying RFs session should be shared for transfer to other processes using RFs::ShareProtected(), since the agent may use transfer this handle to its own or one of the system servers. |
|
215 @param aUniqueId The content object to read. |
|
216 @return The new CData object. |
|
217 |
|
218 @leave KErrNotFound The content object with the given UniqueId does not exist. |
|
219 @leave KErrCAPendingRights The rights have not yet arrived but are expected soon. |
|
220 @leave KErrCANoPermission Rights exist but the specified intent is not permitted. |
|
221 @leave KErrCANoRights No rights exist for the content object. |
|
222 @leave KErrCANotSupported Unable to open the object with the specified UniqueId, it may be a container object. |
|
223 @leave KErrPermissionDenied The agent does not allow the client to access the content object. |
|
224 @leave KErrAccessDenied The content is already in use. |
|
225 @leave ... One of the other CAF error codes defined in \c caferr.h |
|
226 or one of the other system-wide error codes |
|
227 for any other errors. |
|
228 */ |
|
229 IMPORT_C static CData* NewLC(RFile& aFile, const TDesC& aUniqueId); |
|
230 |
|
231 /** |
|
232 Creates a new CData object. |
|
233 |
|
234 @param aAgentUid The agent determined to support this content. |
|
235 @param aVirtualPath The content object to read. |
|
236 @param aIntent The intended use of the content. |
|
237 @param aShareMode The file share mode used to open this content. |
|
238 @return The new CData object. |
|
239 |
|
240 @leave KErrNotFound The content object with the given UniqueId does not exist. |
|
241 @leave KErrCAPendingRights The rights have not yet arrived but are expected soon. |
|
242 @leave KErrCANoPermission Rights exist but the specified intent is not permitted. |
|
243 @leave KErrCANoRights No rights exist for the content object. |
|
244 @leave KErrCANotSupported Unable to open the object with the specified UniqueId, it may be a container object. |
|
245 @leave KErrPermissionDenied The agent does not allow the client to access the content object. |
|
246 @leave KErrAccessDenied The content is already in use. |
|
247 @leave ... One of the other CAF error codes defined in \c caferr.h |
|
248 or one of the other system-wide error codes |
|
249 for any other errors. |
|
250 |
|
251 @internalComponent |
|
252 @released |
|
253 */ |
|
254 static CData* NewLC(TUid aAgentUid, const TVirtualPathPtr& aVirtualPath, |
|
255 TIntent aIntent, TContentShareMode aShareMode); |
|
256 |
|
257 /** |
|
258 Creates a new CData object. |
|
259 |
|
260 @param aAgentUid The Uid of the agent who supports this content. |
|
261 @param aFile An open RFile handle, the agent will make a duplicate of this handle. |
|
262 The underlying RFs session should be shared for transfer to other processes using RFs::ShareProtected(), since the agent may use transfer this handle to its own or one of the system servers. |
|
263 @param aUniqueId The content object to read. |
|
264 @param aIntent The intended use of the content. |
|
265 @return The new CData object. |
|
266 |
|
267 @leave KErrNotFound The content object with the given UniqueId does not exist. |
|
268 @leave KErrCAPendingRights The rights have not yet arrived but are expected soon. |
|
269 @leave KErrCANoPermission Rights exist but the specified intent is not permitted. |
|
270 @leave KErrCANoRights No rights exist for the content object. |
|
271 @leave KErrCANotSupported Unable to open the object with the specified UniqueId, it may be a container object. |
|
272 @leave KErrPermissionDenied The agent does not allow the client to access the content object. |
|
273 @leave KErrAccessDenied The content is already in use. |
|
274 @leave ... One of the other CAF error codes defined in \c caferr.h |
|
275 or one of the other system-wide error codes for |
|
276 any other errors. |
|
277 |
|
278 @internalComponent |
|
279 @released |
|
280 */ |
|
281 static CData* NewLC(TUid aAgentUid, RFile& aFile, const TDesC& aUniqueId, TIntent aIntent); |
|
282 |
|
283 /** destructor */ |
|
284 virtual ~CData(); |
|
285 |
|
286 /** |
|
287 Reads from a content object up to the maximum length of the |
|
288 descriptor or the end of the content object. |
|
289 |
|
290 When an attempt is made to read beyond the end of the content, |
|
291 no error is returned. The descriptor’s length is set to the |
|
292 number of bytes that were read into it. Therefore, when reading |
|
293 through content, the end has been reached when the |
|
294 descriptor length (given by TDesC::Length()) is zero. |
|
295 |
|
296 @param aDes Descriptor into which binary data is read. Any existing |
|
297 contents are overwritten. On return, its length is set |
|
298 to the number of bytes read. |
|
299 @return KErrNone if successful. |
|
300 @return One of the CAF error codes defined in \c caferr.h or |
|
301 one of the other system-wide error codes. |
|
302 @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted |
|
303 */ |
|
304 IMPORT_C TInt Read(TDes8& aDes) const; |
|
305 |
|
306 /** |
|
307 Reads from a content object up to the specified length of the |
|
308 descriptor or the end of the content object. |
|
309 |
|
310 @see Read(TDes8& aDes) |
|
311 |
|
312 @param aDes Descriptor into which binary data is read. Any existing |
|
313 contents are overwritten. On return, its length is set |
|
314 to the number of bytes read. |
|
315 @param aLength The number of bytes to read from the file, |
|
316 or to the end of the file, whichever is encountered first. |
|
317 The length of the buffer is set to the number of bytes actually read. |
|
318 @return KErrNone if successful. |
|
319 @return Otherwise one of the CAF error codes defined in \c caferr.h or |
|
320 one of the other system-wide error codes. |
|
321 @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted |
|
322 */ |
|
323 IMPORT_C TInt Read(TDes8& aDes,TInt aLength) const; |
|
324 |
|
325 /** |
|
326 Read content asynchronously up to the maximum length of the descriptor |
|
327 or until the end of the content object is reached. |
|
328 NB: It is important that the descriptor passed to |
|
329 aDes remains in scope until the request has completed. |
|
330 |
|
331 @see Read(TDes8& aDes) |
|
332 |
|
333 @param aDes Descriptor into which binary data is read. Any |
|
334 existing contents are overwritten. On return, |
|
335 its length is set to the number of bytes read. |
|
336 @param aStatus Asynchronous request status. On completion this will contain one |
|
337 of the following error codes: KErrNone if the data was |
|
338 successfully read. Otherwise one of the CAF error codes defined in |
|
339 \c caferr.h or one of the other standard system-wide |
|
340 error codes for any other errors. |
|
341 @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted |
|
342 */ |
|
343 IMPORT_C void Read(TDes8& aDes, TRequestStatus& aStatus) const; |
|
344 |
|
345 /** |
|
346 Read content asynchronously up to the specified length |
|
347 or until the end of the content object is reached. |
|
348 NB: It is important that the descriptor passed to |
|
349 aDes remains in scope until the request has completed. |
|
350 |
|
351 @see Read(TDes8& aDes) |
|
352 |
|
353 @param aDes Descriptor into which binary data is read. Any |
|
354 existing contents are overwritten. On return, |
|
355 its length is set to the number of bytes read. |
|
356 @param aLength The number of bytes to read from the file, |
|
357 or to the end of the file, whichever is encountered first. |
|
358 The length of the buffer is set to the number of bytes actually read. |
|
359 @param aStatus Asynchronous request status. On completion this will contain one |
|
360 of the following error codes: KErrNone if the data was |
|
361 successfully read. Otherwise one of the CAF error codes defined in |
|
362 \c caferr.h or one of the other standard system-wide |
|
363 error codes for any other errors. |
|
364 @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted |
|
365 */ |
|
366 IMPORT_C void Read(TDes8& aDes, TInt aLength, TRequestStatus& aStatus) const; |
|
367 |
|
368 /** |
|
369 Cancels asynchronous read. |
|
370 |
|
371 @param aStatus Asynchronous request status. This parameter should have been supplied earlier to |
|
372 an asynchronous Read call. If it has not been previously supplied to a Read call, |
|
373 this function will not have any effect. |
|
374 @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted |
|
375 */ |
|
376 IMPORT_C void ReadCancel(TRequestStatus &aStatus) const; |
|
377 |
|
378 /** |
|
379 Reads content asynchronously. The data is read from a specified offset |
|
380 up to a specified number of bytes or until the end of the content object |
|
381 is reached. The data is read into the descriptor buffer supplied. |
|
382 NB: It is important that the descriptor passed to |
|
383 aDes remains in scope until the request has completed. |
|
384 |
|
385 @see Read(TDes8& aDes) |
|
386 |
|
387 @param aPos Position of first byte to be read. |
|
388 This is an offset from the start of the file. |
|
389 @param aDes Descriptor into which binary data is read. Any |
|
390 existing contents are overwritten. On return, |
|
391 its length is set to the number of bytes read. |
|
392 @param aLength The number of bytes to read from the file, |
|
393 or to the end of the file, whichever is encountered first. |
|
394 The length of the buffer is set to the number of bytes actually read. |
|
395 @param aStatus Asynchronous request status. On completion this will contain one |
|
396 of the following error codes: KErrNone if the data was |
|
397 successfully read. Otherwise one of the CAF error codes defined in |
|
398 \c caferr.h or one of the other standard system-wide |
|
399 error codes for any other errors. |
|
400 @return KErrNone if the async read request was successfully submitted. |
|
401 @return KErrArgument if a negative offset is supplied. |
|
402 @return KErrCANotSupported if the agent does not support this operation. |
|
403 @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted |
|
404 */ |
|
405 IMPORT_C TInt Read(TInt aPos, TDes8& aDes, TInt aLength, TRequestStatus& aStatus) const; |
|
406 |
|
407 /** |
|
408 Gets the data size in bytes. |
|
409 |
|
410 @param aSize On return this will contain the size of the plaintext data in bytes. |
|
411 @leave KErrCASizeNotDetermined Size could not be determined by the managing agent. |
|
412 @leave ... One of the other CAF error codes defined in \c caferr.h or one of the |
|
413 system-wide error codes for any other errors. |
|
414 @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted |
|
415 */ |
|
416 IMPORT_C void DataSizeL(TInt& aSize); |
|
417 |
|
418 /** |
|
419 Changes or retrieves the location of the file pointer within |
|
420 the content object. |
|
421 |
|
422 NOTE: Some operations may fail if the content data is sourced over a network connection. |
|
423 |
|
424 There are four seek modes used: |
|
425 |
|
426 @li ESeekStart - Sets the file pointer aPos bytes from the start of the |
|
427 content object. aPos is not modified by the call to Seek() |
|
428 @li ESeekEnd - Sets the file pointer aPos bytes from the end of the |
|
429 content object. The aPos parameter supplied should be zero or negative |
|
430 when using ESeekEnd. Upon completion aPos is updated with the current |
|
431 position relative to the start of the content object. |
|
432 @li ESeekCurrent - Moves the file pointer aPos bytes from the current |
|
433 position. Upon completion aPos is updated with the new position relative |
|
434 to the start of the content object. Suppling a zero value for the aPos Parameter can be |
|
435 used to retrieve the current file pointer location |
|
436 @li ESeekAddress Sets the aPos parameter to the address of the byte |
|
437 aPos bytes from the start of the content object |
|
438 |
|
439 @see TSeek |
|
440 |
|
441 @param aMode Seek mode - controls the destination of the |
|
442 seek operation. |
|
443 |
|
444 @param aPos Offset from either the start, end or current position depending upon |
|
445 the seek mode. Negative offsets are used to seek before the current position or |
|
446 relative to the end of the file. |
|
447 |
|
448 @return KErrNone if successful. |
|
449 @return Otherwise one of the CAF error codes defined in \c caferr.h or one |
|
450 of the other system-wide error codes. |
|
451 @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted |
|
452 */ |
|
453 IMPORT_C TInt Seek(TSeek aMode,TInt& aPos) const; |
|
454 |
|
455 |
|
456 /** Request the agent handling this content to set a property value. If the property is set |
|
457 it is only set for this CData session and does not impact other CAF users. |
|
458 |
|
459 For example setting the buffer-size to 256 bytes can be achieved as follows: |
|
460 |
|
461 @code |
|
462 MyData->SetProperty(EAgentPropertyBufferSize, 256); |
|
463 @endcode |
|
464 |
|
465 @see ContentAccess::TAgentProperty |
|
466 |
|
467 @param aProperty The property to set. |
|
468 @param aValue The value of the property. |
|
469 @return Whether or not the property was set. |
|
470 @return KErrNone if the property was set. |
|
471 @return KErrCANotSupported if the agent does not support the property or value. |
|
472 @return KErrAccessDenied if the agent does not permit the property to be changed. |
|
473 @return KErrPermissionDenied if the application does not have the necessary capability to change the property. |
|
474 @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted. |
|
475 */ |
|
476 IMPORT_C TInt SetProperty(TAgentProperty aProperty, TInt aValue); |
|
477 |
|
478 /** |
|
479 Allows a client to verify that the intent is supported by the |
|
480 current rights for the data object. |
|
481 |
|
482 @note Since the intent is only evaluated the agent will not decrement |
|
483 any rights-state such as play counts. |
|
484 |
|
485 @see ContentAccess::TIntent |
|
486 |
|
487 @param aIntent The intended way the content will be used. |
|
488 @return Whether rights exist allowing the content to be used for this intent. |
|
489 @return KErrNone if the intent is permitted. |
|
490 @return KErrNoRights if no rights exist for the specified content object. |
|
491 @return KErrCANoPermission if rights exist but the specified intent is not permitted. |
|
492 @return KErrCAPendingRights if the rights have not yet arrived but are expected soon. |
|
493 @return KErrNoPermission if rights exist but none permit the specified intent. |
|
494 @return KErrPermissionDenied if the client is not allowed to use this content object. |
|
495 @return Otherwise one of the other CAF error codes defined in \c caferr.h or one of the |
|
496 other system-wide error codes for any other errors. |
|
497 @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted |
|
498 */ |
|
499 IMPORT_C TInt EvaluateIntent(TIntent aIntent); |
|
500 |
|
501 /** |
|
502 Execute intent allows the application to signal it is about to carry out |
|
503 the specified intent on protected content.The agent will decrement applicable |
|
504 stateful rights such as play counts where necessary. |
|
505 |
|
506 Applications should be very careful to use this function correctly. |
|
507 @li If ExecuteIntent() is never called stateful rights will never be decremented. Users will be able to use the content forever |
|
508 @li If ExecuteIntent() is called too often stateful rights may be consumed prematurely. |
|
509 |
|
510 Usually it would be best to call ExecuteIntent immediately before the content |
|
511 is displayed or the instant playback begins. ExecuteIntent should not be considered a |
|
512 prerequisite for calling the Read functions. It is valid for an application to read from |
|
513 the file before calling ExecuteIntent. |
|
514 |
|
515 @note Since rights are executed here the agent will decrement any rights-state such as |
|
516 play counts that apply. |
|
517 |
|
518 @param aIntent The intent indicator. |
|
519 @return The result of attempting executing the intent. |
|
520 @return KErrNone if the intent is permitted and stateful rights may have been decremented. |
|
521 @return KErrNoRights if no rights exist for the specified content object. |
|
522 @return KErrCANoPermission if rights exist but the specified intent is not permitted. |
|
523 @return KErrCAPendingRights if the rights have not yet arrived but are expected soon. |
|
524 @return KErrNoPermission if rights exist but none permit the specified intent. |
|
525 @return KErrPermissionDenied if the client is not allowed to use this content object. |
|
526 @return Otherwise one of the other CAF error codes defined in \c caferr.h or one of the. |
|
527 other system-wide error codes for any other errors. |
|
528 @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted |
|
529 */ |
|
530 IMPORT_C TInt ExecuteIntent(TIntent aIntent); |
|
531 |
|
532 /** Get an attribute for the content object |
|
533 |
|
534 @see ContentAccess::TAttribute |
|
535 |
|
536 @code |
|
537 CContent* content = CContent::NewL(uri); |
|
538 CData* data = content->OpenContentL(EPlay, uniqueId); |
|
539 delete content; |
|
540 |
|
541 TInt value = 0; |
|
542 TInt err = data->GetAttribute(EIsProtected, value); |
|
543 if(err == KErrNone && value) |
|
544 { |
|
545 DisplayPadLock(); |
|
546 } |
|
547 |
|
548 delete data; |
|
549 @endcode |
|
550 |
|
551 @param aAttribute The attribute to query, from ContentAccess::TAttribute. |
|
552 @param aValue Used to return the attribute value. |
|
553 @return Whether the attribute was updated. |
|
554 @return KErrNone if the value of the attribute was updated. |
|
555 @return KErrCANotSupported if the requested attribute does not exist. |
|
556 @return KErrPermissionDenied if the access to the protected content is not permitted by the CAF Agent. |
|
557 @return Otherwise one of the other CAF error codes defined in \c caferr.h or one of the |
|
558 other system-wide error codes for any other errors. |
|
559 @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted |
|
560 */ |
|
561 IMPORT_C TInt GetAttribute(TInt aAttribute, TInt& aValue) const; |
|
562 |
|
563 /** Get a set of attributes for the content object |
|
564 |
|
565 @see ContentAccess::TAttribute |
|
566 |
|
567 The following example determines whether the content object |
|
568 is protected and has rights that will enable it to be viewed by the |
|
569 user |
|
570 |
|
571 @code |
|
572 // CData* data = a data object |
|
573 |
|
574 RAttributeSet attributeSet; |
|
575 CleanupClosePushL(attributeSet); |
|
576 attributeSet->AddL(EProtected); |
|
577 attributeSet->AddL(ECanView); |
|
578 |
|
579 User::LeaveIfError(data->GetAttributeSet(attributeSet); |
|
580 |
|
581 TInt err = attributeSet.GetValue(EProtected, value); |
|
582 if(err == KErrNone && value) |
|
583 { |
|
584 // file is DRM protected |
|
585 } |
|
586 |
|
587 err = attributeSet.GetValue(ECanView, value); |
|
588 if(err == KErrNone && value) |
|
589 { |
|
590 // File has rights that allow it to be displayed on screen |
|
591 } |
|
592 |
|
593 // Finished |
|
594 CleanupStack::PopAndDestroy(); // attributeSet.Close() |
|
595 @endcode |
|
596 |
|
597 |
|
598 @param aAttributeSet The set of attributes to query and update. |
|
599 @return Whether the attribute set was updated. |
|
600 @return KErrNone if the attributes were retrieved successfully. |
|
601 @return KErrPermissionDenied if the access to the protected content is not permitted by the CAF Agent. |
|
602 @return Otherwise one of the CAF error codes defined in \c caferr.h or one of the |
|
603 other system-wide error codes for any other errors. |
|
604 @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted |
|
605 */ |
|
606 IMPORT_C TInt GetAttributeSet(RAttributeSet& aAttributeSet) const; |
|
607 |
|
608 |
|
609 /** Get text string attributes or meta-data for the content object |
|
610 |
|
611 @see ContentAccess::TStringAttribute |
|
612 |
|
613 @code |
|
614 CContent* content = CContent::NewLC(uri); |
|
615 CData* data = content->OpenContentLC(EPlay, uniqueId); |
|
616 CleanupStack::PopAndDestroy(content); |
|
617 |
|
618 TBuf <MAX_PATH> previewUri; |
|
619 TInt err = data->GetStringAttribute(EPreviewURI, previewUri); |
|
620 if(err == KErrNone) |
|
621 { |
|
622 DisplayPreview(previewUri); |
|
623 } |
|
624 |
|
625 CleanupStack::PopAndDestroy(data); |
|
626 @endcode |
|
627 |
|
628 @param aAttribute The attribute to query, from ContentAccess::TStringAttribute. |
|
629 @param aValue Returns the value of the attribute. |
|
630 @return Whether the value was updated. |
|
631 @return KErrNone if the attribute was retrieved. |
|
632 @return KErrOverflow if the buffer was not large enough to return the result. |
|
633 @return KErrCANotSupported if the requested attribute does not exist. |
|
634 @return KErrPermissionDenied if the access to the protected content is not permitted by the CAF Agent. |
|
635 @return Otherwise one of the other CAF error codes defined in \c caferr.h or one of the |
|
636 other system-wide error codes for any other errors. |
|
637 @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted |
|
638 */ |
|
639 IMPORT_C TInt GetStringAttribute(TInt aAttribute, TDes& aValue) const; |
|
640 |
|
641 |
|
642 |
|
643 /** Obtain a set of string attributes for the content object |
|
644 |
|
645 @see ContentAccess::TStringAttribute |
|
646 |
|
647 @code |
|
648 CContent* content = CContent::NewLC(uri); |
|
649 CData* data = content->OpenContentLC(EPlay, uniqueId); |
|
650 |
|
651 // create the attribute set, add the attributes we are interested in |
|
652 RStringAttributeSet stringAttributeSet; |
|
653 CleanupClosePushL(stringAttributeSet); |
|
654 stringAttributeSet.AddL(EPreviewURI); |
|
655 stringAttributeSet.AddL(ETitle); |
|
656 |
|
657 User::LeaveIfError(data->GetStringAttributeSet(stringAttributeSet)); |
|
658 |
|
659 // Pass the value of the string attribute to DisplayPreview() |
|
660 TFileName previewUri; |
|
661 TInt err = stringAttributeSet.GetValue(EPreviewURI, previewUri); |
|
662 if(err == KErrNone) |
|
663 { |
|
664 DisplayPreview(previewUri); |
|
665 } |
|
666 |
|
667 CleanupStack::PopAndDestroy(3); // content, data, stringAttributeSet |
|
668 @endcode |
|
669 |
|
670 |
|
671 @param aStringAttributeSet The set of attributes to query and update. |
|
672 @return Whether the string attribute set was updated. |
|
673 @return KErrNone if the attributes were retrieved successfully. |
|
674 @return KErrNotFound if the default content object was not found. |
|
675 @return KErrPermissionDenied if the access to the protected content is not permitted by the CAF Agent. |
|
676 @return Otherwise one of the CAF error codes defined in \c caferr.h or one of the |
|
677 other system-wide error codes for any other errors. |
|
678 @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted |
|
679 */ |
|
680 IMPORT_C TInt GetStringAttributeSet(RStringAttributeSet& aStringAttributeSet) const; |
|
681 |
|
682 #ifndef REMOVE_CAF1 |
|
683 /** Set Qos attribute |
|
684 @param aQosAttr The Qos attribute to set. |
|
685 @param aValue The value of the attribute. |
|
686 @deprecated |
|
687 */ |
|
688 IMPORT_C void SetQosL(TQosAttribute aQosAttr, TInt aValue); |
|
689 |
|
690 /** Get the mime type of the content |
|
691 @param aMimeType Buffer to store the mime type provided by the agent. |
|
692 @return ETrue if the mime type was retrieved successfully. |
|
693 @deprecated |
|
694 */ |
|
695 IMPORT_C TBool GetMimeTypeL(TDes8& aMimeType) const; |
|
696 #endif // REMOVE_CAF1 |
|
697 |
|
698 |
|
699 private: |
|
700 CData(); |
|
701 void ConstructL(RFile& aFile, const TDesC& aUniqueId, TIntent aIntent); |
|
702 void ConstructL(const TVirtualPathPtr& aVirtualPath, TIntent aIntent, TContentShareMode aShareMode); |
|
703 void ConstructL(TUid aAgentUid, RFile& aFile, const TDesC& aUniqueId, TIntent aIntent); |
|
704 void ConstructL(TUid aAgentUid, const TVirtualPathPtr& aVirtualPath, TIntent aIntent, TContentShareMode aShareMode); |
|
705 |
|
706 void ConstructL(RFile& aFile, const TDesC& aUniqueId); |
|
707 void ConstructL(const TVirtualPathPtr& aVirtualPath, TContentShareMode aShareMode); |
|
708 void ConstructL(TUid aAgentUid, RFile& aFile, const TDesC& aUniqueId); |
|
709 void ConstructL(TUid aAgentUid, const TVirtualPathPtr& aVirtualPath, TContentShareMode aShareMode); |
|
710 |
|
711 |
|
712 private: |
|
713 // The agent handling this content |
|
714 CAgentData* iAgentData; |
|
715 |
|
716 // Defacto ECOM session handle |
|
717 CAgentFactory* iAgentFactory; |
|
718 |
|
719 // Uid of the agent |
|
720 TUid iAgentUid; |
|
721 }; |
|
722 |
|
723 } // namespace ContentAccess |
|
724 #endif /* __DATA_H__ */ |
|
725 |