epoc32/include/caf/data.h
author William Roberts <williamr@symbian.org>
Tue, 16 Mar 2010 16:12:26 +0000
branchSymbian2
changeset 2 2fe1408b6811
child 4 837f303aceeb
permissions -rw-r--r--
Final list of Symbian^2 public API header files
     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