epoc32/include/caf/content.h
author William Roberts <williamr@symbian.org>
Wed, 31 Mar 2010 12:33:34 +0100
branchSymbian3
changeset 4 837f303aceeb
parent 2 2fe1408b6811
permissions -rw-r--r--
Current Symbian^3 public API header files (from PDK 3.0.h)
This is the epoc32/include tree with the "platform" subtrees removed, and
all but a selected few mbg and rsg files removed.
williamr@2
     1
/*
williamr@4
     2
* Copyright (c) 2003-2009 Nokia Corporation and/or its subsidiary(-ies).
williamr@2
     3
* All rights reserved.
williamr@2
     4
* This component and the accompanying materials are made available
williamr@2
     5
* under the terms of the License "Eclipse Public License v1.0"
williamr@2
     6
* which accompanies this distribution, and is available
williamr@2
     7
* at the URL "http://www.eclipse.org/legal/epl-v10.html".
williamr@2
     8
*
williamr@2
     9
* Initial Contributors:
williamr@2
    10
* Nokia Corporation - initial contribution.
williamr@2
    11
*
williamr@2
    12
* Contributors:
williamr@2
    13
*
williamr@2
    14
* Description: 
williamr@2
    15
*
williamr@2
    16
*/
williamr@2
    17
williamr@2
    18
williamr@2
    19
/** 
williamr@2
    20
@file
williamr@2
    21
williamr@4
    22
@publishedAll
williamr@2
    23
@released
williamr@2
    24
*/
williamr@2
    25
williamr@2
    26
williamr@2
    27
#ifndef __CONTENT_H__
williamr@2
    28
#define __CONTENT_H__
williamr@2
    29
williamr@2
    30
#include <e32base.h>
williamr@2
    31
#include <f32file.h>
williamr@2
    32
williamr@2
    33
#include <caf/caftypes.h>
williamr@2
    34
#include <caf/agent.h>
williamr@2
    35
#include <caf/streamableptrarray.h>
williamr@2
    36
#include <caf/virtualpathptr.h>
williamr@2
    37
williamr@2
    38
namespace ContentAccess
williamr@2
    39
	{
williamr@2
    40
	class CAgentResolver;
williamr@2
    41
	class CAgentFactory;
williamr@2
    42
	class CAgentContent;
williamr@2
    43
	class CData;
williamr@2
    44
	class CEmbeddedObject;
williamr@2
    45
	class RAttributeSet;
williamr@2
    46
	class RStringAttributeSet;
williamr@2
    47
williamr@2
    48
	
williamr@2
    49
williamr@2
    50
#ifndef REMOVE_CAF1
williamr@2
    51
	class CAttribute;
williamr@2
    52
#endif
williamr@2
    53
	
williamr@2
    54
williamr@2
    55
/**
williamr@2
    56
   CContent allows applications to browse the content objects contained within a 
williamr@2
    57
   single file and construct a CData object for reading that content.
williamr@2
    58
 
williamr@2
    59
  Applications will use an object of this type rather than the traditional 
williamr@2
    60
  RFile mechanisms. They will, however, be  required to indicate 
williamr@2
    61
  <i>DRM Intent</i> - something that determines whether (and how) access to
williamr@2
    62
  the content should be permitted by a Content-Access agent.
williamr@2
    63
 
williamr@2
    64
  CContent allows direct access to meta-data such as the attributes of 
williamr@2
    65
  the content and indirect access to the plaintext data itself through 
williamr@2
    66
  the CData class. 
williamr@2
    67
  
williamr@2
    68
  Applications can use CContent to browse the hierarchy of content objects 
williamr@2
    69
  within a file containing several content objects.
williamr@2
    70
   
williamr@2
    71
  During construction CContent loads the correct CAF Agent plugin to handle 
williamr@2
    72
  the file specified by the URI.
williamr@2
    73
 */
williamr@2
    74
	class CContent :  public CBase
williamr@2
    75
		{
williamr@2
    76
	public:
williamr@2
    77
williamr@2
    78
		/**
williamr@2
    79
		 Constructs a new CContent object with a given URI. The URI can be in the same format as a virtual path for more information see CVirtualPath and TVirtualPathPtr
williamr@2
    80
williamr@2
    81
		 @param aURI	The filename, URI or virtual path of the DRM file.
williamr@2
    82
		 @return a new CContent object.
williamr@2
    83
		 @leave KErrNotFound If the file at the given URI does not exist or if an invalid URI or virtual path have been supplied.
williamr@2
    84
		 @leave KErrPermissionDenied If the access to the protected content is not permitted by the CAF Agent.
williamr@2
    85
		 @leave ...		One of the CAF error codes defined in \c caferr.h  or one of the 
williamr@2
    86
						other system-wide error codes for any other errors.
williamr@2
    87
		 @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted 
williamr@2
    88
		 */
williamr@2
    89
		IMPORT_C static CContent* NewLC(const TDesC& aURI);
williamr@2
    90
williamr@2
    91
		/**
williamr@2
    92
		 Constructs a new CContent object with a given URI. The URI can be in the same format as a virtual path for more information see CVirtualPath and TVirtualPathPtr
williamr@2
    93
williamr@2
    94
		 @param aURI	The filename, URI or virtual path of the DRM file.
williamr@2
    95
		 @return a new CContent object.
williamr@2
    96
		 @leave KErrNotFound If the file at the given URI does not exist or if an invalid URI or virtual path have been supplied.
williamr@2
    97
		 @leave KErrPermissionDenied If the access to the protected content is not permitted by the CAF Agent.
williamr@2
    98
		 @leave ...			One of the CAF error codes defined in \c caferr.h  or one of the 
williamr@2
    99
							other system-wide error codes for any other errors.
williamr@2
   100
		 @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted 
williamr@2
   101
		 */
williamr@2
   102
		IMPORT_C static CContent* NewL(const TDesC& aURI);
williamr@2
   103
		
williamr@2
   104
		/**
williamr@2
   105
		 Constructs a new CContent object with a given URI. The URI can be in the same format as a virtual path for more information see CVirtualPath and TVirtualPathPtr
williamr@2
   106
williamr@2
   107
		 @param aURI	The filename, URI or virtual path of the DRM file.
williamr@2
   108
		 @param aShareMode The sharing mode used when accessing the content.
williamr@2
   109
		 @return a new CContent object.
williamr@2
   110
		 @leave KErrNotFound If the file at the given URI does not exist or if an invalid URI or virtual path have been supplied.
williamr@2
   111
		 @leave KErrAccessDenied If the file is already open with a different share mode.
williamr@2
   112
		 @leave KErrPermissionDenied If the access to the protected content is not permitted by the CAF Agent.
williamr@2
   113
		 @leave ...			One of the CAF error codes defined in \c caferr.h  or one of the 
williamr@2
   114
							other system-wide error codes for any other errors.
williamr@2
   115
		 @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted 
williamr@2
   116
		 */
williamr@2
   117
		IMPORT_C static CContent* NewLC(const TDesC& aURI, TContentShareMode aShareMode);
williamr@2
   118
		
williamr@2
   119
		/** 
williamr@2
   120
		Constructs a new CContent object with a given URI. The URI can be in the same format as a virtual path for more information see CVirtualPath and TVirtualPathPtr
williamr@2
   121
williamr@2
   122
		@param aURI	The filename, URI or virtual path of the DRM file.
williamr@2
   123
		@param aShareMode The sharing mode used when accessing the content.
williamr@2
   124
		@return a new CContent object.
williamr@2
   125
		@leave KErrNotFound If the file at the given URI does not exist or if an invalid URI or virtual path have been supplied.
williamr@2
   126
		@leave KErrAccessDenied If the file is already open with a different share mode.
williamr@2
   127
		@leave KErrPermissionDenied If the access to the protected content is not permitted by the CAF Agent.
williamr@2
   128
		@leave ...			One of the CAF error codes defined in \c caferr.h  or one of the 
williamr@2
   129
							other system-wide error codes for any other errors.
williamr@2
   130
		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted 
williamr@2
   131
		*/
williamr@2
   132
		IMPORT_C static CContent* NewL(const TDesC& aURI, TContentShareMode aShareMode);
williamr@2
   133
williamr@2
   134
		/**
williamr@2
   135
		 Constructs a new CContent object with an open file handle.
williamr@2
   136
williamr@2
   137
  		 CContent will use a duplicate of this file handle, the client is 
williamr@2
   138
		 free to close its file handle any time after creating the CContent 
williamr@2
   139
		 object.
williamr@2
   140
williamr@2
   141
		 @param aFile The file handle. The file must already be open before calling NewLC. 
williamr@2
   142
		 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.
williamr@2
   143
		 @return a new CContent object.
williamr@2
   144
		 @leave KErrPermissionDenied If the access to the protected content is not permitted by the CAF Agent.
williamr@2
   145
		 @leave ...			One of the CAF error codes defined in \c caferr.h  or one of the 
williamr@2
   146
							other system-wide error codes for any other errors.
williamr@2
   147
		 @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted 
williamr@2
   148
		 */
williamr@2
   149
		IMPORT_C static CContent* NewLC(RFile& aFile);
williamr@2
   150
		
williamr@2
   151
		/** 
williamr@2
   152
		 Constructs a new CContent object with an open file handle.
williamr@2
   153
williamr@2
   154
  		 CContent will use a duplicate of this file handle, the client is 
williamr@2
   155
		 free to close its file handle any time after creating the CContent 
williamr@2
   156
		 object.
williamr@2
   157
williamr@2
   158
		 @param aFile The file handle. The file must already be open before calling this method. 
williamr@2
   159
		 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.
williamr@2
   160
		 @return a new CContent object.
williamr@2
   161
		 @leave KErrPermissionDenied If the access to the protected content is not permitted by the CAF Agent.	 
williamr@2
   162
		 @leave ...			One of the CAF error codes defined in \c caferr.h  or one of the 
williamr@2
   163
							other system-wide error codes for any other errors.
williamr@2
   164
		 @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted 
williamr@2
   165
		*/
williamr@2
   166
		IMPORT_C static CContent* NewL(RFile& aFile);
williamr@2
   167
williamr@4
   168
#ifdef SYMBIAN_ENABLE_SDP_WMDRM_SUPPORT		
williamr@4
   169
		/** 
williamr@4
   170
		 Constructs a new CContent object.
williamr@4
   171
williamr@4
   172
  		 @param aHeaderData	Header data of WMDRM file/stream content. 
williamr@4
   173
		 @return 			CContent object.
williamr@4
   174
		 @leave 			KErrMissingHeaderData if the header data is NULL or one of the CAF error codes defined in caferr.h  
williamr@4
   175
		 					or one of the system-wide error codes for any other errors.
williamr@4
   176
		 @capability DRM 	Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted 
williamr@4
   177
	 	 */
williamr@4
   178
		IMPORT_C static CContent* NewL(const TDesC8& aHeaderData);
williamr@4
   179
		
williamr@4
   180
		/** 
williamr@4
   181
		 Constructs a new CContent object.
williamr@4
   182
  		 
williamr@4
   183
  		 @param aHeaderData	Header data of WMDRM file/stream content.  
williamr@4
   184
		 @return 			CContent object.
williamr@4
   185
		 @leave 			KErrMissingHeaderData if the header data is NULL or one of the CAF error codes defined in caferr.h  or one of the 
williamr@4
   186
							system-wide error codes for any other errors.
williamr@4
   187
		 @capability DRM 	Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted 
williamr@4
   188
		 */
williamr@4
   189
		IMPORT_C static CContent* NewLC(const TDesC8& aHeaderData);
williamr@4
   190
		
williamr@4
   191
#endif //#ifdef SYMBIAN_ENABLE_SDP_WMDRM_SUPPORT
williamr@4
   192
williamr@2
   193
		/** destructor */
williamr@2
   194
		virtual ~CContent();
williamr@2
   195
williamr@2
   196
 		/** Open a Container object within the file.
williamr@2
   197
 		
williamr@2
   198
 		Allows an application to access the content objects and 
williamr@2
   199
 		any nested container objects within the specified container.
williamr@2
   200
  		
williamr@2
   201
 		@param aUniqueId The container object's unique ID.
williamr@2
   202
		@return Whether the container was opened.
williamr@2
   203
 		@return KErrNone if the container was opened successfully.
williamr@2
   204
 		@return KErrNotFound if the container does not exist.
williamr@2
   205
		@return KErrPermissionDenied if the access to the protected content is not permitted by the CAF Agent.		 
williamr@2
   206
		@return Otherwise one of the CAF error codes defined in \c caferr.h  or one of the 
williamr@2
   207
				other system-wide error codes for any other errors.
williamr@2
   208
 		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted 
williamr@2
   209
 		*/
williamr@2
   210
 		IMPORT_C TInt OpenContainer(const TDesC& aUniqueId);
williamr@2
   211
williamr@2
   212
 		/** Close the current container object and go back to previous enclosing
williamr@2
   213
 		container within the file.
williamr@2
   214
 		
williamr@2
   215
 		Allows an application to access the content objects and 
williamr@2
   216
 		any nested container objects within parent container.
williamr@2
   217
  		
williamr@2
   218
		@return Whether the container was closed.
williamr@2
   219
  		@return KErrNone if the container was closed.
williamr@2
   220
  		@return KErrNotFound if there is no enclosing container.
williamr@2
   221
  		@return KErrPermissionDenied if the access to the protected content is not permitted by the CAF Agent.		 		
williamr@2
   222
  		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted 
williamr@2
   223
 		*/
williamr@2
   224
		IMPORT_C TInt CloseContainer();
williamr@2
   225
williamr@2
   226
		/** List all the embedded container objects and content objects within the 
williamr@2
   227
		current container
williamr@2
   228
 		 		
williamr@2
   229
		The UniqueId() member of CEmbeddedObject can be used to refer directly to 
williamr@2
   230
		a particular object within the file.
williamr@2
   231
		
williamr@2
   232
		@code
williamr@2
   233
		// Create a ccontent object for the file of interest
williamr@2
   234
		CContent* content = CContent::NewLC(uri);
williamr@2
   235
		
williamr@2
   236
		// Define an array to store the results
williamr@2
   237
		RStreamablePtrArray <CEmbeddedObject> array;
williamr@2
   238
		CleanupClosePushL(array);
williamr@2
   239
		
williamr@2
   240
		// Find all the content and container objects within the current container
williamr@2
   241
		content->GetEmbeddedObjectsL(array);
williamr@2
   242
		
williamr@2
   243
		// Do something with the array
williamr@2
   244
		....
williamr@2
   245
		
williamr@2
   246
		// Finished
williamr@2
   247
		CleanupStack::PopAndDestroy(2);
williamr@2
   248
		@endcode
williamr@2
   249
		
williamr@2
   250
		@param aArray The array to be populated with the embedded objects. 
williamr@2
   251
		@leave KErrPermissionDenied if the access to the protected content is not permitted by the CAF Agent.		 
williamr@2
   252
		@leave ...			One of the CAF error codes defined in \c caferr.h  or one of the 
williamr@2
   253
							other system-wide error codes for any other errors.
williamr@2
   254
  		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted 
williamr@2
   255
 		*/
williamr@2
   256
		IMPORT_C void GetEmbeddedObjectsL(RStreamablePtrArray<CEmbeddedObject>& aArray) const;
williamr@2
   257
williamr@2
   258
		/** List all the embedded objects within the current container that
williamr@2
   259
		are of the specified type
williamr@2
   260
williamr@2
   261
		@code
williamr@2
   262
		// Create a ccontent object for the file of interest
williamr@2
   263
		CContent* content = CContent::NewLC(uri);
williamr@2
   264
		
williamr@2
   265
		// Define an array to store the results
williamr@2
   266
		RStreamablePtrArray <CEmbeddedObject> array;
williamr@2
   267
		CleanupClosePushL(array);
williamr@2
   268
		
williamr@2
   269
		// Find all the content objects within the current container
williamr@2
   270
		content->GetEmbeddedObjectsL(array, EContentObject);
williamr@2
   271
		
williamr@2
   272
		// Do something with the array
williamr@2
   273
		....
williamr@2
   274
		
williamr@2
   275
		// Finished
williamr@2
   276
		CleanupStack::PopAndDestroy(2);
williamr@2
   277
		@endcode
williamr@2
   278
 		 		
williamr@2
   279
		@param aArray The array to be populated with the embedded objects. 
williamr@2
   280
		@param aType The type of objects to list.
williamr@2
   281
		@leave KErrPermissionDenied If the access to the protected content is not permitted by the CAF Agent.		 
williamr@2
   282
		@leave ...			One of the CAF error codes defined in \c caferr.h  or one of the 
williamr@2
   283
							other system-wide error codes for any other errors.
williamr@2
   284
  		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted 
williamr@2
   285
 		*/
williamr@2
   286
		IMPORT_C void GetEmbeddedObjectsL(RStreamablePtrArray<CEmbeddedObject>& aArray, TEmbeddedType aType) const;
williamr@2
   287
		
williamr@2
   288
		/** Search the current container for content objects with a particular mime type
williamr@2
   289
williamr@2
   290
		@code
williamr@2
   291
		_LIT8(KTextPlainMimeType, "text/plain");
williamr@2
   292
		
williamr@2
   293
		// Create a ccontent object for the file of interest
williamr@2
   294
		CContent* content = CContent::NewLC(uri);
williamr@2
   295
		
williamr@2
   296
		// Define an array to store the results
williamr@2
   297
		RStreamablePtrArray <CEmbeddedObject> array;
williamr@2
   298
		CleanupClosePushL(array);
williamr@2
   299
		
williamr@2
   300
		// Recursively search for all the content objects with the 
williamr@2
   301
		// specified mime type
williamr@2
   302
		User::LeaveIfError(content->Search(array, KTextPlainMimeType(), ETrue));
williamr@2
   303
		
williamr@2
   304
		// Do something with the array
williamr@2
   305
		....
williamr@2
   306
		
williamr@2
   307
		// Finished
williamr@2
   308
		CleanupStack::PopAndDestroy(2);
williamr@2
   309
		@endcode
williamr@2
   310
williamr@2
   311
  		@param aArray The array to store the results of the search. The agent will add CEmbeddedObject objects to the supplied array.
williamr@2
   312
		@param aMimeType The mime type to search for.
williamr@2
   313
		@param aRecursive ETrue to search inside containers embedded within the current container, EFalse to search only the current container.
williamr@2
   314
		@return The result of the search.
williamr@2
   315
		@return KErrNone if the search was successful, even if no content objects were found.
williamr@2
   316
		@return KErrPermissionDenied if the access to the protected content is not permitted by the CAF Agent.		 
williamr@2
   317
		@return Otherwise one of the CAF error codes defined in \c caferr.h  or one of the 
williamr@2
   318
				other system-wide error codes for any other errors.
williamr@2
   319
		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted 
williamr@2
   320
		*/
williamr@2
   321
		IMPORT_C TInt Search(RStreamablePtrArray<CEmbeddedObject>& aArray, const TDesC8& aMimeType, TBool aRecursive);
williamr@2
   322
williamr@2
   323
williamr@2
   324
		/**  Get an attribute for the default content object within the file
williamr@2
   325
williamr@2
   326
  		@see ContentAccess::TAttribute
williamr@2
   327
williamr@2
   328
		@code
williamr@2
   329
		TInt value = 0;
williamr@2
   330
		CContent* c = CContent::NewL(uri);
williamr@2
   331
		TInt err =c->GetAttribute(EIsProtected, value);
williamr@2
   332
		if(err == KErrNone && value)
williamr@2
   333
			{
williamr@2
   334
			DisplayPadLock();
williamr@2
   335
			}
williamr@2
   336
		@endcode
williamr@2
   337
williamr@2
   338
		@param aAttribute The attribute to query, from ContentAccess::TAttribute.
williamr@2
   339
		@param aValue Used to return the attribute value.
williamr@2
   340
		@return Whether the attribute value was updated.
williamr@2
   341
		@return KErrNone if the value of the attribute was updated.
williamr@2
   342
		@return KErrNotFound if the object with the given UniqueId was not found.
williamr@2
   343
		@return KErrCANotSupported if the requested attribute does not exist.
williamr@2
   344
		@return KErrPermissionDenied if the access to the protected content is not permitted by the CAF Agent.	 
williamr@2
   345
		@return Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 
williamr@2
   346
				other system-wide error codes for any other errors.
williamr@2
   347
		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted. 
williamr@2
   348
		*/
williamr@2
   349
		IMPORT_C TInt GetAttribute(TInt aAttribute, TInt& aValue) const;		
williamr@2
   350
williamr@2
   351
		/**  Get an attribute for an object within the file
williamr@2
   352
williamr@2
   353
		@see ContentAccess::TAttribute
williamr@2
   354
williamr@2
   355
		@code
williamr@2
   356
		TInt value = 0;
williamr@2
   357
		CContent* c = CContent::NewL(uri);
williamr@2
   358
		TInt err =c->GetAttribute(EIsProtected, value, uniqueId);
williamr@2
   359
		if(err == KErrNone && value)
williamr@2
   360
			{
williamr@2
   361
			DisplayPadLock();
williamr@2
   362
			}
williamr@2
   363
		@endcode
williamr@2
   364
williamr@2
   365
		@param aAttribute The attribute to query, from ContentAccess::TAttribute.
williamr@2
   366
		@param aValue Used to return the attribute value.
williamr@2
   367
		@param aUniqueId The UniqueId of the object within the file.
williamr@2
   368
		@return Whether the attribute value was updated.
williamr@2
   369
		@return KErrNone if the value of the attribute was updated.
williamr@2
   370
		@return KErrNotFound if the object with the given UniqueId was not found.
williamr@2
   371
		@return KErrCANotSupported if the requested attribute does not exist.
williamr@2
   372
		@return KErrPermissionDenied if the access to the protected content is not permitted by the CAF Agent.	 
williamr@2
   373
		@return Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 
williamr@2
   374
				other system-wide error codes for any other errors.
williamr@2
   375
		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted. 
williamr@2
   376
		*/
williamr@2
   377
		IMPORT_C TInt GetAttribute(TInt aAttribute, TInt& aValue, const TDesC& aUniqueId) const;
williamr@2
   378
		
williamr@2
   379
williamr@2
   380
		/** Get a set of attributes for the default content object within the file
williamr@2
   381
williamr@2
   382
		@see ContentAccess::TAttribute
williamr@2
   383
williamr@2
   384
		The following example determines whether the default content object 
williamr@2
   385
		is protected and has rights that will enable it to be viewed by the 
williamr@2
   386
		user
williamr@2
   387
williamr@2
   388
		@code
williamr@2
   389
		CContent* content = CContent::NewLC(uri);
williamr@2
   390
				
williamr@2
   391
		RAttributeSet attributeSet;
williamr@2
   392
		CleanupClosePushL(attributeSet);
williamr@2
   393
		attributeSet->AddL(EProtected);
williamr@2
   394
		attributeSet->AddL(ECanView);
williamr@2
   395
williamr@2
   396
		User::LeaveIfError(content->GetAttributeSet(attributeSet);
williamr@2
   397
williamr@2
   398
		TInt err = attributeSet.GetValue(EProtected, value);
williamr@2
   399
		if(err == KErrNone && value)
williamr@2
   400
				{
williamr@2
   401
				// file is DRM protected
williamr@2
   402
				}
williamr@2
   403
williamr@2
   404
		err = attributeSet.GetValue(ECanView, value);
williamr@2
   405
		if(err == KErrNone && value)
williamr@2
   406
				{
williamr@2
   407
				// File has rights that allow it to be displayed on screen
williamr@2
   408
				}
williamr@2
   409
		
williamr@2
   410
		// Finished
williamr@2
   411
		CleanupStack::PopAndDestroy(2); // content, attributeSet.Close()
williamr@2
   412
		@endcode
williamr@2
   413
williamr@2
   414
williamr@2
   415
		@param aAttributeSet The set of attributes to query and update.
williamr@2
   416
		@return Whether the attribute set was updated.
williamr@2
   417
		@return KErrNone if the attributes were retrieved successfully.
williamr@2
   418
		@return KErrNotFound if the default content object was not found.
williamr@2
   419
		@return KErrPermissionDenied if the access to the protected content is not permitted by the CAF Agent.		 
williamr@2
   420
		@return Otherwise one of the CAF error codes defined in \c caferr.h  or one of the 
williamr@2
   421
				other system-wide error codes for any other errors.
williamr@2
   422
		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted. 
williamr@2
   423
		*/
williamr@2
   424
		IMPORT_C TInt GetAttributeSet(RAttributeSet& aAttributeSet) const;		
williamr@2
   425
		
williamr@2
   426
		/** Get a set of attributes from an object within the file
williamr@2
   427
williamr@2
   428
		@see ContentAccess::TAttribute
williamr@2
   429
williamr@2
   430
		The following example determines whether the default content object 
williamr@2
   431
		is protected and has rights that will enable it to be viewed by the 
williamr@2
   432
		user
williamr@2
   433
williamr@2
   434
		@code
williamr@2
   435
		CContent* content = CContent::NewLC(uri);
williamr@2
   436
				
williamr@2
   437
		RAttributeSet attributeSet;
williamr@2
   438
		CleanupClosePushL(attributeSet);
williamr@2
   439
		attributeSet->AddL(EProtected);
williamr@2
   440
		attributeSet->AddL(ECanView);
williamr@2
   441
williamr@2
   442
		User::LeaveIfError(content->GetAttributeSet(attributeSet, uniqueId);
williamr@2
   443
williamr@2
   444
		TInt err = attributeSet.GetValue(EProtected, value);
williamr@2
   445
		if(err == KErrNone && value)
williamr@2
   446
				{
williamr@2
   447
				// file is DRM protected
williamr@2
   448
				}
williamr@2
   449
williamr@2
   450
		err = attributeSet.GetValue(ECanView, value);
williamr@2
   451
		if(err == KErrNone && value)
williamr@2
   452
				{
williamr@2
   453
				// File has rights that allow it to be displayed on screen
williamr@2
   454
				}
williamr@2
   455
		
williamr@2
   456
		// Finished
williamr@2
   457
		CleanupStack::PopAndDestroy(2); // content, attributeSet.Close()
williamr@2
   458
		@endcode
williamr@2
   459
williamr@2
   460
williamr@2
   461
		@param aAttributeSet The set of attributes to query and update.
williamr@2
   462
		@param aUniqueId The unique ID of the object within the file.
williamr@2
   463
		@return Whether that attribute set was updated.
williamr@2
   464
		@return KErrNone if the attributes were retrieved successfully.
williamr@2
   465
		@return KErrNotFound if the default content object was not found.
williamr@2
   466
		@return KErrPermissionDenied if the access to the protected content is not permitted by the CAF Agent.		 
williamr@2
   467
		@return Otherwise one of the CAF error codes defined in \c caferr.h  or one of the 
williamr@2
   468
				other system-wide error codes for any other errors.
williamr@2
   469
		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted. 
williamr@2
   470
		*/
williamr@2
   471
		IMPORT_C TInt GetAttributeSet(RAttributeSet& aAttributeSet, const TDesC& aUniqueId) const;
williamr@2
   472
		
williamr@2
   473
		/**  Get text string attributes or meta-data for the default content object within the file
williamr@2
   474
	
williamr@2
   475
		@see ContentAccess::TStringAttribute
williamr@2
   476
williamr@2
   477
		@code
williamr@2
   478
		TInt err = KErrNone;
williamr@2
   479
		
williamr@2
   480
		CContent* c = CContent::NewL(uri);
williamr@2
   481
		TBuf <MAX_PATH> previewUri;
williamr@2
   482
		err = c->GetStringAttribute(EPreviewURI, previewUri);
williamr@2
   483
		if(err == KErrNone)
williamr@2
   484
			{
williamr@2
   485
			DisplayPreview(previewUri);
williamr@2
   486
			}
williamr@2
   487
		@endcode
williamr@2
   488
williamr@2
   489
		@param aAttribute The attribute to query, from ContentAccess::TStringAttribute.
williamr@2
   490
		@param aValue Returns the value of the attribute.
williamr@2
   491
		@return Whether the attribute value was updated.
williamr@2
   492
		@return KErrNone if the attribute was retrieved.
williamr@2
   493
		@return KErrNotFound if the default content object was not found.
williamr@2
   494
		@return KErrOverflow if the buffer was not large enough to return the result.
williamr@2
   495
		@return KErrCANotSupported if the requested attribute does not exist.
williamr@2
   496
		@return KErrPermissionDenied if the access to the protected content is not permitted by the CAF Agent.		 
williamr@2
   497
		@return Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 
williamr@2
   498
				other system-wide error codes for any other errors.
williamr@2
   499
		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted. 
williamr@2
   500
		*/
williamr@2
   501
		IMPORT_C TInt GetStringAttribute(TInt aAttribute, TDes& aValue) const;
williamr@2
   502
		
williamr@2
   503
		/** Get text string attributes or meta-data for an object within the file
williamr@2
   504
williamr@2
   505
		@see ContentAccess::TStringAttribute
williamr@2
   506
williamr@2
   507
		@code
williamr@2
   508
		TInt err = KErrNone;
williamr@2
   509
		
williamr@2
   510
		CContent* c = CContent::NewL(uri);
williamr@2
   511
		TBuf <MAX_PATH> previewUri;
williamr@2
   512
		err = c->GetStringAttribute(EPreviewURI, previewUri, uniqueId);
williamr@2
   513
		if(err == KErrNone)
williamr@2
   514
			{
williamr@2
   515
			DisplayPreview(previewUri);
williamr@2
   516
			}
williamr@2
   517
		@endcode
williamr@2
   518
williamr@2
   519
		@param aAttribute The attribute to query, from ContentAccess::TStringAttribute.
williamr@2
   520
		@param aValue Returns the value of the attribute.
williamr@2
   521
		@param aUniqueId The UniqueId of the object within the file. 
williamr@2
   522
		@return Whether the attribute value was updated.
williamr@2
   523
		@return KErrNone if the attribute was retrieved.
williamr@2
   524
		@return KErrNotFound if the object with the given UniqueId was not found.
williamr@2
   525
		@return KErrOverflow if the buffer was not large enough to return the result.
williamr@2
   526
		@return KErrCANotSupported if the requested attribute does not exist.
williamr@2
   527
		@return KErrPermissionDenied if the access to the protected content is not permitted by the CAF Agent.	 
williamr@2
   528
		@return Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 
williamr@2
   529
				other system-wide error codes for any other errors.
williamr@2
   530
		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted. 
williamr@2
   531
		*/
williamr@2
   532
		IMPORT_C TInt GetStringAttribute(TInt aAttribute, TDes& aValue, const TDesC& aUniqueId) const;
williamr@2
   533
		
williamr@2
   534
		/** Obtain a set of string attributes for the default content object within the file
williamr@2
   535
williamr@2
   536
		@see ContentAccess::TStringAttribute
williamr@2
   537
	  
williamr@2
   538
		@code
williamr@2
   539
		CContent* content = CContent::NewLC(uri);
williamr@2
   540
		
williamr@2
   541
		// create the attribute set, add the attributes we are interested in
williamr@2
   542
		RStringAttributeSet stringAttributeSet;
williamr@2
   543
		CleanupClosePushL(stringAttributeSet);
williamr@2
   544
		stringAttributeSet.AddL(EPreviewURI);
williamr@2
   545
		stringAttributeSet.AddL(ETitle);
williamr@2
   546
		
williamr@2
   547
		User::LeaveIfError(content->GetStringAttributeSet(stringAttributeSet));
williamr@2
   548
	
williamr@2
   549
		// Pass the value of the string attribute to DisplayPreview()
williamr@2
   550
		TFileName previewUri;		
williamr@2
   551
		TInt err = stringAttributeSet.GetValue(EPreviewURI, previewUri);
williamr@2
   552
		if(err == KErrNone)
williamr@2
   553
			{
williamr@2
   554
			DisplayPreview(previewUri);
williamr@2
   555
			}
williamr@2
   556
		
williamr@2
   557
		CleanupStack::PopAndDestroy(2); // content, stringAttributeSet.Close()
williamr@2
   558
		@endcode
williamr@2
   559
	
williamr@2
   560
williamr@2
   561
		@param aStringAttributeSet The set of attributes to query and update.
williamr@2
   562
		@return Whether the attribute set was updated.
williamr@2
   563
		@return KErrNone if the attributes were retrieved successfully.
williamr@2
   564
		@return KErrNotFound if the default content object was not found.
williamr@2
   565
		@return KErrPermissionDenied if the access to the protected content is not permitted by the CAF Agent.		 
williamr@2
   566
		@return Otherwise one of the CAF error codes defined in \c caferr.h  or one of the 
williamr@2
   567
				other system-wide error codes for any other errors.
williamr@2
   568
		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted. 
williamr@2
   569
		*/
williamr@2
   570
		IMPORT_C TInt GetStringAttributeSet(RStringAttributeSet& aStringAttributeSet) const;
williamr@2
   571
	
williamr@2
   572
		/** Used to obtain a set of string attributes for an object within the file
williamr@2
   573
williamr@2
   574
		@see ContentAccess::TStringAttribute
williamr@2
   575
	
williamr@2
   576
		@code
williamr@2
   577
		CContent* content = CContent::NewLC(uri);
williamr@2
   578
		
williamr@2
   579
		// create the attribute set, add the attributes we are interested in
williamr@2
   580
		RStringAttributeSet stringAttributeSet;
williamr@2
   581
		CleanupClosePushL(stringAttributeSet);
williamr@2
   582
		stringAttributeSet.AddL(EPreviewURI);
williamr@2
   583
		stringAttributeSet.AddL(ETitle);
williamr@2
   584
		
williamr@2
   585
		User::LeaveIfError(content->GetStringAttributeSet(stringAttributeSet, uniqueId));
williamr@2
   586
	
williamr@2
   587
		// Pass the value of the string attribute to DisplayPreview()
williamr@2
   588
		TFileName previewUri;		
williamr@2
   589
		TInt err = stringAttributeSet.GetValue(EPreviewURI, previewUri);
williamr@2
   590
		if(err == KErrNone)
williamr@2
   591
			{
williamr@2
   592
			DisplayPreview(previewUri);
williamr@2
   593
			}
williamr@2
   594
		
williamr@2
   595
		CleanupStack::PopAndDestroy(2); // content, stringAttributeSet.Close()
williamr@2
   596
		@endcode
williamr@2
   597
	
williamr@2
   598
williamr@2
   599
		@param aStringAttributeSet The set of attributes to query and update.
williamr@2
   600
		@param aUniqueId The UniqueId of the container or content. 
williamr@2
   601
		@return Whether the attribute set was updated.
williamr@2
   602
		@return KErrNone if the attributes were retrieved successfully.
williamr@2
   603
		@return KErrNotFound if the object with the given UniqueId was not found.
williamr@2
   604
		@return KErrPermissionDenied if the access to the protected content is not permitted by the CAF Agent.		 
williamr@2
   605
		@return Otherwise one of the CAF error codes defined in \c caferr.h  or one of the 
williamr@2
   606
				other system-wide error codes for any other errors.
williamr@2
   607
		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted. 
williamr@2
   608
		*/
williamr@2
   609
		IMPORT_C TInt GetStringAttributeSet(RStringAttributeSet& aStringAttributeSet, const TDesC& aUniqueId) const;
williamr@2
   610
williamr@2
   611
		/** Allows extended synchronous calls to the CAF agent handling this file
williamr@2
   612
		
williamr@2
   613
		Applications familiar with the agent can pass objects in and out using serialization.
williamr@2
   614
williamr@2
   615
		@param aCommand The agent defined command.
williamr@2
   616
		@param aInputBuffer Non modifyable input data buffer.
williamr@2
   617
		@param aOutputBuffer Modifyable output buffer to hold the result of the command.
williamr@2
   618
		@return The outcome of the agent specific command.
williamr@2
   619
		@return KErrCANotSupported if the agent does not recognize the command.
williamr@2
   620
		@return KErrOverflow if the output buffer supplied is too small.
williamr@2
   621
		@return KErrPermissionDenied if the agent does not allow the client to execute the command.
williamr@2
   622
		@return Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 
williamr@2
   623
				other system-wide error codes for any other errors.
williamr@2
   624
		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted 
williamr@2
   625
		*/
williamr@2
   626
		IMPORT_C TInt AgentSpecificCommand(TInt aCommand, const TDesC8& aInputBuffer, TDes8& aOutputBuffer);
williamr@2
   627
williamr@2
   628
		/** Allows extended synchronous calls to the CAF agent handling this file
williamr@2
   629
		Applications familiar with the agent can pass objects in and out using serialization.
williamr@2
   630
		NB: It is important that the descriptor passed to 
williamr@2
   631
		aOutputBuffer remains in scope until the request has completed.		
williamr@2
   632
williamr@2
   633
		@param aCommand The agent defined command.
williamr@2
   634
		@param aInputBuffer Non modifyable input data buffer.
williamr@2
   635
		@param aOutputBuffer Modifyable output buffer to hold the result of the command.
williamr@2
   636
		@param aStatus Asynchronous request status. On completion this will contain 
williamr@2
   637
						one of the following error codes:
williamr@2
   638
						KErrNone if the command was successfully executed.
williamr@2
   639
						KErrCANotSupported  if the agent does not recognize the command.
williamr@2
   640
						KErrOverflow if the output buffer supplied is too small.
williamr@2
   641
						KErrPermissionDenied if the agent does not allow the client 
williamr@2
   642
						to execute the command. Otherwise one of the other CAF error codes defined 
williamr@2
   643
						in \c caferr.h  or one of the other system-wide error codes 
williamr@2
   644
						for any other errors.
williamr@2
   645
		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted 
williamr@2
   646
		*/
williamr@2
   647
		IMPORT_C void AgentSpecificCommand(TInt aCommand, const TDesC8& aInputBuffer, TDes8& aOutputBuffer, TRequestStatus& aStatus);
williamr@2
   648
williamr@2
   649
williamr@2
   650
		/** Request notification for an event for the default content object within the file
williamr@2
   651
williamr@2
   652
		@see ContentAccess::TEventMask
williamr@2
   653
williamr@2
   654
		@param aMask Bitmask of events the caller is interested in.	
williamr@2
   655
		@param aStatus The TRequestStatus object to complete if the event occurs.
williamr@2
   656
		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted 
williamr@2
   657
		*/
williamr@2
   658
		IMPORT_C void NotifyStatusChange(TEventMask aMask, TRequestStatus& aStatus);
williamr@2
   659
williamr@2
   660
		/** Request notification for an event for an object within the file
williamr@2
   661
williamr@2
   662
		@see ContentAccess::TEventMask
williamr@2
   663
williamr@2
   664
		@param aMask Bitmask of events the caller is interested in.
williamr@2
   665
		@param aStatus The TRequestStatus object to complete if the event occurs.
williamr@2
   666
		@param aUniqueId The UniqueId of the container or content. 						 
williamr@2
   667
		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted 
williamr@2
   668
		*/
williamr@2
   669
		IMPORT_C void NotifyStatusChange(TEventMask aMask, TRequestStatus& aStatus, const TDesC& aUniqueId);
williamr@2
   670
williamr@2
   671
		/** Cancel a previous notification request for the default content object
williamr@2
   672
williamr@2
   673
		@param aStatus The TRequestStatus supplied in the call to NotifyStatusChange().
williamr@2
   674
		@return The outcome of the cancel request.
williamr@2
   675
		@return KErrNone if the request was cancelled.
williamr@2
   676
		@return KErrNotFound if there was no matching request outstanding.
williamr@2
   677
		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted 
williamr@2
   678
		*/
williamr@2
   679
		IMPORT_C TInt CancelNotifyStatusChange(TRequestStatus& aStatus);
williamr@2
   680
williamr@2
   681
		/** Cancel a previous notification request
williamr@2
   682
williamr@2
   683
		@param aStatus The TRequestStatus supplied in the call to NotifyStatusChange().
williamr@2
   684
		@param aUniqueId The UniqueId of the content object within the file.
williamr@2
   685
		@return The outcome of the cancel request.
williamr@2
   686
		@return KErrNone if the request was cancelled.
williamr@2
   687
		@return KErrNotFound if there was no matching request outstanding.
williamr@2
   688
		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted 
williamr@2
   689
		*/
williamr@2
   690
		IMPORT_C TInt CancelNotifyStatusChange(TRequestStatus& aStatus, const TDesC& aUniqueId);
williamr@2
   691
		
williamr@2
   692
		/** Request the agent to obtain rights for the default content object
williamr@2
   693
williamr@2
   694
		This request may be handled differently by different agents. 
williamr@2
   695
		Some agents may open a browser and direct the user to a URL. Others may 
williamr@2
   696
		download and install the rights in the background.
williamr@2
   697
williamr@2
   698
		The call should not block execution, applications can wait for a notification 
williamr@2
   699
		if they are interested in the outcome.
williamr@2
   700
williamr@2
   701
		@param aStatus Asynchronous request status. On completion this will contain 
williamr@2
   702
						one of the following error codes:
williamr@2
   703
						KErrNone if the rights request was successful.
williamr@2
   704
						KErrCANotSupported  if the agent does not allow rights requests.
williamr@2
   705
						Otherwise one of the other CAF error codes defined in \c caferr.h  
williamr@2
   706
						or one of the other system-wide error codes 
williamr@2
   707
						for any other errors.
williamr@2
   708
		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted. 
williamr@2
   709
		*/
williamr@2
   710
		IMPORT_C void RequestRights(TRequestStatus& aStatus);
williamr@2
   711
williamr@2
   712
		/** Request the agent to obtain rights for a protected content object
williamr@2
   713
williamr@2
   714
		This request may be handled differently by different agents. 
williamr@2
   715
		Some agents may open a browser and direct the user to a URL. Others may 
williamr@2
   716
		download and install the rights in the background.
williamr@2
   717
williamr@2
   718
		The call should not block execution, applications can wait for a notification 
williamr@2
   719
		if they are interested in the outcome.
williamr@2
   720
williamr@2
   721
		@param aStatus Asynchronous request status. On completion this will contain 
williamr@2
   722
						one of the following error codes:
williamr@2
   723
						KErrNone if the rights request was successful.
williamr@2
   724
						KErrCANotSupported  if the agent does not allow rights requests.
williamr@2
   725
						Otherwise one of the other CAF error codes defined in \c caferr.h  
williamr@2
   726
						or one of the other system-wide error codes 
williamr@2
   727
						for any other errors.
williamr@2
   728
williamr@2
   729
		@param aUniqueId The unique id of the object within the file.					
williamr@2
   730
		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted. 
williamr@2
   731
		*/
williamr@2
   732
		IMPORT_C void RequestRights(TRequestStatus& aStatus, const TDesC& aUniqueId);
williamr@2
   733
williamr@2
   734
williamr@2
   735
		/** Cancel a previous RequestRights() request for the default content object
williamr@2
   736
williamr@2
   737
		@param aStatus The TRequestStatus that was supplied to the RequestRights() function.
williamr@2
   738
		@return The result of the cancel rights request.
williamr@2
   739
		@return KErrNone if the rights request was cancelled.
williamr@2
   740
		@return KErrNotFound if there was no matching rights request outstanding.
williamr@2
   741
		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted 
williamr@2
   742
		*/
williamr@2
   743
		IMPORT_C TInt CancelRequestRights(TRequestStatus& aStatus);
williamr@2
   744
williamr@2
   745
		/** Cancel a previous RequestRights() request
williamr@2
   746
williamr@2
   747
		@param aStatus The TRequestStatus that was supplied to the RequestRights() function.
williamr@2
   748
		@param aUniqueId The objects Unique Id that was supplied to the RequestRights() function.
williamr@2
   749
		@return The result of the cancel rights request.
williamr@2
   750
		@return KErrNone if the rights request was cancelled.
williamr@2
   751
		@return KErrNotFound if there was no matching rights request outstanding.
williamr@2
   752
		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted 
williamr@2
   753
		*/
williamr@2
   754
		IMPORT_C TInt CancelRequestRights(TRequestStatus& aStatus, const TDesC& aUniqueId);
williamr@2
   755
williamr@2
   756
		/** View information associated with the default content object
williamr@2
   757
	
williamr@2
   758
		This call blocks execution and only returns once the display is dismissed 
williamr@2
   759
		by the user.
williamr@2
   760
williamr@2
   761
		@see ContentAccess::TDisplayInfo
williamr@2
   762
williamr@2
   763
		@param aInfo The information to display.
williamr@2
   764
		@leave KErrCANotSupported if information cannot be displayed or does not exist.
williamr@2
   765
		@leave ...			One of the other CAF error codes defined in \c caferr.h  
williamr@2
   766
							or one of the system-wide error codes for 
williamr@2
   767
							any other errors.
williamr@2
   768
		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted. 
williamr@2
   769
		*/
williamr@2
   770
		IMPORT_C void DisplayInfoL(TDisplayInfo aInfo) const;
williamr@2
   771
		
williamr@2
   772
		/** View information associated with a single content object
williamr@2
   773
		
williamr@2
   774
		This call blocks execution and only returns once the display is dismissed 
williamr@2
   775
		by the user.
williamr@2
   776
williamr@2
   777
		@see ContentAccess::TDisplayInfo
williamr@2
   778
williamr@2
   779
		@param aInfo The information to display.
williamr@2
   780
		@param aUniqueId The unique id of the object within the file.
williamr@2
   781
		@leave KErrCANotSupported if information cannot be displayed or does not exist.
williamr@2
   782
		@leave ...			One of the other CAF error codes defined in \c caferr.h  
williamr@2
   783
							or one of the system-wide error codes for 
williamr@2
   784
							any other errors.
williamr@2
   785
		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted. 
williamr@2
   786
		*/
williamr@2
   787
		IMPORT_C void DisplayInfoL(TDisplayInfo aInfo, const TDesC& aUniqueId) const;
williamr@2
   788
williamr@2
   789
williamr@2
   790
		/** Request the agent handling this content to set a property value. If 
williamr@2
   791
		the property is set it is only set for this CContent session and does not 
williamr@2
   792
		impact other CAF users and is not set for CData products created by the 
williamr@2
   793
		CContent.
williamr@2
   794
williamr@2
   795
  		@see ContentAccess::TAgentProperty
williamr@2
   796
williamr@2
   797
		@param aProperty The property to set.
williamr@2
   798
		@param aValue The value of the property.
williamr@2
   799
		@return Whether the property was set.
williamr@2
   800
		@return KErrNone if the property was set.
williamr@2
   801
		@return KErrCANotSupported if the agent does not support the property or value.
williamr@2
   802
		@return KErrAccessDenied if the agent does not permit the property to be changed.
williamr@2
   803
		@return KErrPermissionDenied if the application does not have the necessary capability to change the property.
williamr@2
   804
		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted 
williamr@2
   805
		*/
williamr@2
   806
		IMPORT_C TInt SetProperty(TAgentProperty aProperty, TInt aValue);
williamr@2
   807
		
williamr@2
   808
		/** 
williamr@2
   809
		 Grants read access to the default content object based on 
williamr@2
   810
		 evaluation of the supplied intent information. 
williamr@2
   811
		 
williamr@2
   812
		 Note that the intent is simply evaluated and not executed. 
williamr@2
   813
		 To force the intent to be executed, clients must use the call
williamr@2
   814
		 ContentAccess::CData::ExecuteIntent(). 
williamr@2
   815
		 
williamr@2
   816
		 A CData object can be obtained as follows:
williamr@2
   817
		 @code
williamr@2
   818
		 CData* MyData = myContent->OpenContentL(ChosenIntent);
williamr@2
   819
		 ...
williamr@2
   820
		 delete MyData; // when finished accessing plaintext content
williamr@2
   821
		 @endcode
williamr@2
   822
williamr@2
   823
		 @see ContentAccess::TIntent
williamr@2
   824
williamr@2
   825
		 @param aIntent	The intent indicator.
williamr@2
   826
		 @return A CData instance. The caller gets ownership of this object.
williamr@2
   827
		 
williamr@2
   828
		 @leave KErrNotFound		The content object with the given UniqueId does not exist.
williamr@2
   829
		 @leave KErrCAPendingRights The rights have not yet arrived but are expected soon.
williamr@2
   830
		 @leave KErrCANoPermission	Rights exist but the specified intent is not permitted.
williamr@2
   831
		 @leave KErrCANoRights		No rights exist for the content object.
williamr@2
   832
		 @leave KErrCANotSupported	Unable to open the object with the specified UniqueId, it may be a container object.
williamr@2
   833
		 @leave KErrPermissionDenied The agent does not allow the client to access the content object.
williamr@2
   834
		 @leave KErrAccessDenied	The content is already in use.
williamr@2
   835
		 @leave ...				One of the other CAF error codes defined in \c caferr.h  
williamr@2
   836
		 						or one of the other system-wide error codes for any other 
williamr@2
   837
								errors.		 
williamr@2
   838
 		 @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted
williamr@2
   839
		 */
williamr@2
   840
		IMPORT_C CData* OpenContentL(TIntent aIntent);
williamr@2
   841
williamr@2
   842
		/** 
williamr@2
   843
		 Grants read access to the default content object based on 
williamr@2
   844
		 evaluation of the supplied intent information. 
williamr@2
   845
	
williamr@2
   846
		 Note that the intent is simply evaluated and not executed. 
williamr@2
   847
		 To force the intent to be executed, clients must use the call
williamr@2
   848
		 ContentAccess::CData::ExecuteIntent(). 
williamr@2
   849
		 
williamr@2
   850
		 A CData object can be obtained as follows:
williamr@2
   851
		 @code
williamr@2
   852
		 CData* myData = myContent->OpenContentLC(ChosenIntent);
williamr@2
   853
		 ...
williamr@2
   854
		 // when finished accessing plaintext content
williamr@2
   855
		 CleanupStack::PopAndDestroy(myData); 
williamr@2
   856
		 @endcode
williamr@2
   857
williamr@2
   858
		 @see ContentAccess::TIntent
williamr@2
   859
williamr@2
   860
		 @param aIntent	The intent indicator.
williamr@2
   861
		 @return A CData instance. The caller gets ownership of this object.
williamr@2
   862
		 
williamr@2
   863
		 @leave KErrNotFound			The content object with the given UniqueId does not exist.
williamr@2
   864
		 @leave KErrCAPendingRights		The rights have not yet arrived but are expected soon.
williamr@2
   865
		 @leave KErrCANoPermission		Rights exist but the specified intent is not permitted.
williamr@2
   866
		 @leave KErrCANoRights			No rights exist for the content object.
williamr@2
   867
		 @leave KErrCANotSupported		Unable to open the object with the specified UniqueId, it may be a container object.
williamr@2
   868
		 @leave KErrPermissionDenied	The agent does not allow the client to access the content object.
williamr@2
   869
		 @leave KErrAccessDenied		The content is already in use.
williamr@2
   870
		 @leave ...				One of the other CAF error codes defined in \c caferr.h  
williamr@2
   871
		 						or one of the other system-wide error codes for any other 
williamr@2
   872
								errors.		 
williamr@2
   873
 		 @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted.
williamr@2
   874
		 */
williamr@2
   875
		IMPORT_C CData* OpenContentLC(TIntent aIntent);
williamr@2
   876
		
williamr@2
   877
		/** 
williamr@2
   878
		 Grants read access to the content object based on evaluation of the
williamr@2
   879
		 supplied intent information. 
williamr@2
   880
		 
williamr@2
   881
		 Note that the intent is simply evaluated and not executed. 
williamr@2
   882
		 To force the intent to be executed, clients must use the call
williamr@2
   883
		 ContentAccess::CData::ExecuteIntent(). 
williamr@2
   884
		 
williamr@2
   885
		 A CData object can be obtained as follows:
williamr@2
   886
		 @code
williamr@2
   887
		 CData* MyData = myContent->OpenContentL(ChosenIntent, uniqueId);
williamr@2
   888
		 ...
williamr@2
   889
		 delete MyData; // when finished accessing plaintext content
williamr@2
   890
		 @endcode
williamr@2
   891
		 	
williamr@2
   892
		 @see ContentAccess::TIntent
williamr@2
   893
williamr@2
   894
		 @param aIntent	The intent indicator.
williamr@2
   895
		 @param aUniqueId The object to open for reading. If the UniqueId is set to KNullDesC16() the entire file will be opened for reading with no transformation.
williamr@2
   896
		 @return A CData instance. The caller gets ownership of this object.
williamr@2
   897
		 
williamr@2
   898
		 @leave KErrNotFound		The content object with the given UniqueId does not exist.
williamr@2
   899
		 @leave KErrCAPendingRights The rights have not yet arrived but are expected soon.
williamr@2
   900
		 @leave KErrCANoPermission	Rights exist but the specified intent is not permitted.
williamr@2
   901
		 @leave KErrCANoRights		No rights exist for the content object.
williamr@2
   902
		 @leave KErrCANotSupported	Unable to open the object with the specified UniqueId, it may be a container object.
williamr@2
   903
		 @leave KErrPermissionDenied The agent does not allow the client to access the content object.
williamr@2
   904
		 @leave KErrAccessDenied	The content is already in use.
williamr@2
   905
		 @leave ...				One of the other CAF error codes defined in \c caferr.h  
williamr@2
   906
		 						or one of the other system-wide error codes for any other 
williamr@2
   907
								errors.		 
williamr@2
   908
 		 @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted
williamr@2
   909
		 */
williamr@2
   910
		IMPORT_C CData* OpenContentL(TIntent aIntent, const TDesC& aUniqueId);
williamr@2
   911
williamr@2
   912
williamr@2
   913
		/** 
williamr@2
   914
		 Grants read access to the content object based on evaluation of the
williamr@2
   915
		 supplied intent information. 
williamr@2
   916
		 
williamr@2
   917
		 Note that the intent is simply evaluated and not executed. 
williamr@2
   918
		 To force the intent to be executed, clients must use the call
williamr@2
   919
		 ContentAccess::CData::ExecuteIntent(). 
williamr@2
   920
		 
williamr@2
   921
		 A CData object can be obtained as follows:
williamr@2
   922
		 @code
williamr@2
   923
		 CData* MyData = myContent->OpenContentLC(ChosenIntent, uniqueId);
williamr@2
   924
		 ...
williamr@2
   925
		 PopAndDestroy(MyData); // when finished accessing plaintext content
williamr@2
   926
		 @endcode
williamr@2
   927
		 	
williamr@2
   928
		 @see ContentAccess::TIntent
williamr@2
   929
williamr@2
   930
		 @param aIntent	The intent indicator.
williamr@2
   931
		 @param aUniqueId The object to open for reading. If the UniqueId is set to KNullDesC16() the entire file will be opened for reading with no transformation.
williamr@2
   932
		 @return A CData instance. The caller gets ownership of this object.
williamr@2
   933
		 
williamr@2
   934
		 @leave KErrNotFound		The content object with the given UniqueId does not exist.
williamr@2
   935
		 @leave KErrCAPendingRights The rights have not yet arrived but are expected soon.
williamr@2
   936
		 @leave KErrCANoPermission	Rights exist but the specified intent is not permitted.
williamr@2
   937
		 @leave KErrCANoRights		No rights exist for the content object.
williamr@2
   938
		 @leave KErrCANotSupported	Unable to open the object with the specified UniqueId, it may be a container object.
williamr@2
   939
		 @leave KErrPermissionDenied The agent does not allow the client to access the content object.
williamr@2
   940
		 @leave KErrAccessDenied	The content is already in use.
williamr@2
   941
		 @leave ...				One of the other CAF error codes defined in \c caferr.h  
williamr@2
   942
		 						or one of the other system-wide error codes for any other 
williamr@2
   943
								errors.		 
williamr@2
   944
 		 @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted
williamr@2
   945
		 */
williamr@2
   946
		IMPORT_C CData* OpenContentLC(TIntent aIntent, const TDesC& aUniqueId);
williamr@2
   947
williamr@2
   948
williamr@2
   949
		/** Find out which agent is handling this file
williamr@2
   950
		@return The agent handling the File
williamr@2
   951
		*/
williamr@2
   952
		IMPORT_C const TAgent& Agent() const;
williamr@2
   953
		
williamr@4
   954
		/** Indicates the mode in which the content is shared.
williamr@4
   955
			@return The content sharing mode
williamr@4
   956
		*/
williamr@4
   957
		inline TContentShareMode ShareMode() const;
williamr@4
   958
		
williamr@2
   959
#ifndef REMOVE_CAF1
williamr@2
   960
		/** Create a CData object for reading the content 
williamr@2
   961
williamr@2
   962
		@see ContentAccess::TIntent
williamr@2
   963
		@param aIntent The intended use of the content
williamr@2
   964
		@param aShareMode The mode used to open the file. If EContentShareExclusive is required, use CData::NewL() instead
williamr@2
   965
		@return A new CData object
williamr@2
   966
		@leave One of the CAF error codes defined in \c caferr.h  or one of the system-wide error codes for any errors.
williamr@2
   967
		@capability DRM Access to DRM agents is not permitted for processes without DRM capability
williamr@2
   968
		@deprecated
williamr@2
   969
		*/
williamr@2
   970
		IMPORT_C CData* OpenContentL(TIntent aIntent, TContentShareMode aShareMode);
williamr@2
   971
williamr@2
   972
		/** Create a CAttribute object to determine the attributes of the default content object
williamr@2
   973
		
williamr@2
   974
		@return The agent handling the File
williamr@2
   975
		@capability DRM Access to DRM agents is not permitted for processes without DRM capability
williamr@2
   976
		@deprecated 
williamr@2
   977
		*/
williamr@2
   978
		IMPORT_C CAttribute* NewAttributeL(TBool aPreloaded);
williamr@2
   979
williamr@2
   980
		/** Create a CAttribute object to determine the attributes of the default content object
williamr@2
   981
		
williamr@2
   982
		@return The agent handling the File
williamr@2
   983
		@capability DRM Access to DRM agents is not permitted for processes without DRM capability
williamr@2
   984
		@deprecated 
williamr@2
   985
		*/
williamr@2
   986
		IMPORT_C CAttribute* NewAttributeL(TBool aPreloaded, TContentShareMode aShareMode);
williamr@2
   987
williamr@2
   988
#endif  // REMOVE_CAF1
williamr@2
   989
		
williamr@2
   990
	private:
williamr@2
   991
		CContent(); 
williamr@2
   992
		void ConstructL(RFile& aFile); 
williamr@2
   993
		void ConstructL(const TDesC& aURI, TContentShareMode aShareMode); 
williamr@2
   994
		
williamr@4
   995
#ifdef SYMBIAN_ENABLE_SDP_WMDRM_SUPPORT
williamr@4
   996
		void ConstructL(const TDesC8& aHeaderData);
williamr@4
   997
williamr@4
   998
		/**
williamr@4
   999
		Create a CData object for reading WMDRM content.
williamr@4
  1000
		
williamr@4
  1001
		@param	aIntent		The intended use of the content.
williamr@4
  1002
		@param	aHeaderData	Header data of WMDRM file/stream content.
williamr@4
  1003
		@return				CData object.
williamr@4
  1004
		@leave 				One of the CAF error codes defined in caferr.h  or one of the system-wide error codes for any errors.
williamr@4
  1005
		@capability DRM 	Access to DRM agents is not permitted for processes without DRM capability.
williamr@4
  1006
		*/
williamr@4
  1007
		
williamr@4
  1008
		CData* OpenContentL(TIntent aIntent, const TDesC8& aHeaderData);
williamr@4
  1009
		
williamr@4
  1010
		/**
williamr@4
  1011
		Create a CData object for reading WMDRM content.
williamr@4
  1012
		
williamr@4
  1013
		@param	aIntent		The intended use of the content.
williamr@4
  1014
		@param	aHeaderData	Header data of WMDRM file/stream content.
williamr@4
  1015
		@return				CData object.
williamr@4
  1016
		@leave 				One of the CAF error codes defined in caferr.h  or one of the system-wide error codes for any errors.
williamr@4
  1017
		@capability DRM 	Access to DRM agents is not permitted for processes without DRM capability.
williamr@4
  1018
		*/
williamr@4
  1019
		CData* OpenContentLC(TIntent aIntent, const TDesC8& aHeaderData);
williamr@4
  1020
		
williamr@4
  1021
#endif //#ifdef SYMBIAN_ENABLE_SDP_WMDRM_SUPPORT
williamr@4
  1022
williamr@2
  1023
	private:	
williamr@2
  1024
	
williamr@2
  1025
		/** CAgentFactory object is effectively the	ECOM session handle */
williamr@2
  1026
		CAgentFactory* iAgentFactory;
williamr@2
  1027
williamr@2
  1028
		/** 
williamr@2
  1029
		 Agent object used for browsing the contents of a file
williamr@2
  1030
		 */
williamr@2
  1031
		CAgentContent* iAgentContent;
williamr@2
  1032
williamr@2
  1033
		/** Points to the default content object if the file is opened by name */
williamr@2
  1034
		CVirtualPath* iVirtualPath;
williamr@2
  1035
williamr@2
  1036
		/** The content object referred to by CContent, either points to iVirtualPath
williamr@2
  1037
		or points to (KNullDesC(), KDefaultContentObject()) 
williamr@2
  1038
		*/
williamr@2
  1039
		TVirtualPathPtr iDefaultVirtualPath;
williamr@2
  1040
williamr@2
  1041
		/* Stores the name and UID of the agent
williamr@2
  1042
		*/
williamr@2
  1043
		TAgent iAgent;
williamr@2
  1044
		
williamr@2
  1045
		/** The share mode used to open the content file*/
williamr@2
  1046
		TContentShareMode iShareMode;
williamr@2
  1047
williamr@2
  1048
		/** Reference to the file handle if the content was opened with a file handle */
williamr@4
  1049
#ifdef SYMBIAN_ENABLE_64_BIT_FILE_SERVER_API
williamr@4
  1050
		RFile64 iFile;
williamr@4
  1051
#else
williamr@2
  1052
		RFile iFile;
williamr@4
  1053
#endif //SYMBIAN_ENABLE_64_BIT_FILE_SERVER_API
williamr@4
  1054
williamr@4
  1055
#ifdef SYMBIAN_ENABLE_SDP_WMDRM_SUPPORT
williamr@4
  1056
		HBufC8* iHeaderData;
williamr@4
  1057
#endif //#ifdef SYMBIAN_ENABLE_SDP_WMDRM_SUPPORT
williamr@4
  1058
williamr@2
  1059
		};
williamr@2
  1060
williamr@4
  1061
#include <caf/content.inl>
williamr@2
  1062
	} // namespace ContentAccess
williamr@4
  1063
williamr@4
  1064
#endif // __CONTENT_H__ 
williamr@4
  1065