1 /*

     2 * Copyright (c) 2003-2008 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 #ifndef __AGENTINTERFACE_H__

    28 #define __AGENTINTERFACE_H__

    29 

    30 #include <e32base.h>

    31 #include <ecom/ecom.h>

    32 

    33 #include <caf/caftypes.h>

    34 #include <caf/streamableptrarray.h>

    35 #include <caf/caferr.h>

    36 

    37 class RStringPool;

    38 class RHTTPHeaders;

    39 

    40 namespace ContentAccess

    41 {

    42 	class CEmbeddedObject;

    43 	class CSupplierOutputFile;

    44 	class RAttributeSet;

    45 	class RStringAttributeSet;

    46 	class TVirtualPathPtr;

    47 	class CRightsInfo;

    48 	class CVirtualPath;

    49 	class MAgentRightsBase;

    50 	class CImportFile;

    51 	class CMetaDataArray;

    52 	class CDirStreamable;

    53 

    54 	/**

    55 	 Defines the agent interface for consumer operations such as 

    56 	 reading and seeking within a content object in a file.

    57 

    58 	 @publishedPartner

    59 	 @released

    60      */

    61 	class CAgentData : public CBase

    62 		{

    63 	public:

    64 		/**

    65 		 Gets the data size in bytes.

    66 		 

    67 		 @param aSize	On return this will contain the size of the plaintext data in bytes.

    68 		 @leave KErrCASizeNotDetermined	Size could not be determined by the managing agent.

    69 		 @leave ...		One of the other CAF error codes defined in \c caferr.h  or one of the 

    70 						system-wide error codes for any other errors.		 

    71 		 @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted

    72 		 */

    73 		virtual void DataSizeL(TInt &aSize) = 0;

    74 		

    75 		/**

    76 		 Allows a client to verify that the intent is supported by the

    77 		 current rights for the data object. 

    78 		 

    79 		 Doing so may cause subsequent reads (or other accesses)

    80 		 to fail. The result of the agent's evaluation

    81 		 of the intent is returned.

    82 		 

    83 		 @note Since the intent is only evaluated the agent will not decrement 

    84 		 any rights-state such as play counts.

    85 		  

    86 		 @param aIntent	The intended way the content will be used.

    87 		 @return Whether rights exist allowing the content to be used for this intent.

    88 		 @return KErrNone if the intent is permitted.

    89 		 @return KErrNoRights if no rights exist for the specified content object.

    90 		 @return KErrCANoPermission	if rights exist but the specified intent is not permitted.

    91 		 @return KErrCAPendingRights if the rights have not yet arrived but are expected soon.

    92 		 @return KErrNoPermission if rights exist but none permit the specified intent.

    93 		 @return KErrPermissionDenied if the client is not allowed to use this content object.

    94 		 @return Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 

    95 				other system-wide error codes for any other errors.

    96 

    97 		 @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted

    98 		 */

    99 		virtual TInt EvaluateIntent(TIntent aIntent) = 0;

   100 		

   101 		/**

   102 		 Execute intent allows the application to signal it is about to carry out

   103 		 the specified intent on DRM protected content.The agent will decrement applicable 

   104 		 stateful rights such as play counts where necessary.

   105 

   106   		 Applications should be very careful to use this function correctly.

   107 		 @li If ExecuteIntent() is never called stateful rights will never be decremented. Users will be able to use the content forever

   108 		 @li If ExecuteIntent() is called too often stateful rights may be consumed prematurely. 

   109 

   110 		 Usually it would be best to call ExecuteIntent immediately before the content 

   111 		 is displayed or the instant playback begins. ExecuteIntent should not be considered a 

   112 		 prerequisite for calling the Read functions. It is valid for an application to read from 

   113 		 the file before calling ExecuteIntent. 

   114 

   115 		 @note Since rights are executed here the agent will decrement any rights-state such as 

   116 		 play counts that apply. 

   117 		 

   118 		@param aIntent	The intent indicator.

   119 		@return The result of attempting executing the intent.

   120 		@return KErrNone if the intent is permitted and stateful rights may have been decremented.

   121 		@return KErrNoRights if no rights exist for the specified content object.

   122 		@return KErrCANoPermission	if rights exist but the specified intent is not permitted.

   123 		@return KErrCAPendingRights if the rights have not yet arrived but are expected soon.

   124 		@return KErrNoPermission if rights exist but none permit the specified intent.

   125 		@return KErrPermissionDenied if the client is not allowed to use this content object.

   126 		@return Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the

   127 				other system-wide error codes for any other errors.

   128 		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted 

   129 		*/

   130 		virtual TInt ExecuteIntent(TIntent aIntent) = 0;

   131 

   132 		/** 

   133 		 Reads from a content object up to the maximum length of the

   134 		 descriptor or the end of the content object.

   135 		 	

   136 		 When an attempt is made to read beyond the end of the content,

   137 		 no error is returned. The descriptor’s length is set to the

   138 		 number of bytes that were read into it. Therefore, when reading

   139 		 through content, the end has been reached when the

   140 		 descriptor length (given by TDesC::Length()) is zero.

   141 		 

   142 		 @param aDes	Descriptor into which binary data is read. Any existing

   143 		  				contents are overwritten. On return, its length is set

   144 		 				to the number of bytes read.

   145 		 @return		KErrNone if successful, otherwise another of the

   146 		  				system-wide error codes.

   147 		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted 

   148 		*/

   149 		virtual TInt Read(TDes8& aDes) = 0;

   150 

   151 		/**

   152 		 Reads a specified number of bytes of content.

   153 		  

   154 		 @see Read(TDes8& aDes)

   155 		 		 

   156 		 @param aDes	Descriptor into which binary data is read. Any existing

   157 		  				contents are overwritten. On return, its length is set

   158 		 				to the number of bytes read.

   159 		 @param aLength		The number of bytes to read from the file,

   160 		 					or to the end of the file, whichever is encountered first. 

   161 		 					The length of the buffer is set to the number of bytes actually read.

   162 		 @return		KErrNone if successful.

   163 		 @return		Otherwise one of the CAF error codes defined in \c caferr.h  or 

   164 		 				one of the other system-wide error codes.

   165 		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted 

   166 		*/

   167 		virtual TInt Read(TDes8& aDes, TInt aLength) = 0;

   168 

   169 		/**

   170 		 Reads content asynchronously.

   171 		 

   172 		 @see Read(TDes8& aDes)

   173 		 

   174 		 @param aDes 		Descriptor into which binary data is read. Any

   175 		  					existing contents are overwritten. On return,

   176 		 					its length is set to the number of bytes read. 

   177 		 @param aStatus		Asynchronous request status. On completion this will contain one 

   178 		 					of the following error codes: KErrNone if the data was 

   179 							successfully read. Otherwise one of the CAF error codes defined in 

   180 							\c caferr.h  or one of the other standard system-wide

   181 							error codes for any other errors.

   182 		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted 

   183 		*/

   184 		virtual void Read(TDes8& aDes, TRequestStatus& aStatus) = 0;

   185 

   186 		/**

   187 		 Reads content asynchronously (up to a specified maximum number of bytes)

   188 		 

   189 		 @see Read(TDes8& aDes)

   190 		 

   191 		 @param aDes 		Descriptor into which binary data is read. Any

   192 		  					existing contents are overwritten. On return,

   193 		 					its length is set to the number of bytes read. 

   194 		 @param aLength		The number of bytes to read from the file,

   195 		 					or to the end of the file, whichever is encountered first. 

   196 		 					The length of the buffer is set to the number of bytes actually read.

   197 		 @param aStatus		Asynchronous request status. On completion this will contain one 

   198 		 					of the following error codes: KErrNone if the data was 

   199 							successfully read. Otherwise one of the CAF error codes defined in 

   200 							\c caferr.h  or one of the other standard system-wide

   201 							error codes for any other errors.

   202 		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted 

   203 		*/

   204 		virtual void Read(TDes8& aDes, TInt aLength, TRequestStatus& aStatus) = 0;

   205 		

   206 		/**

   207 		 Cancels asynchronous read.

   208 		 

   209 		 @param aStatus		Asynchronous request status. This parameter should have been supplied earlier to

   210 		 					an asynchronous Read call. If it has not been previously supplied to a Read call,

   211 		 					this function will not have any effect.

   212 		 @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted 

   213 		*/

   214 		virtual void ReadCancel(TRequestStatus& aStatus);

   215 

   216 		/**

   217 		 Changes or retrieves the location of the file pointer within 

   218 		 the content object

   219 		 

   220 		 There are four seek modes used: 

   221 		 

   222 		 @li ESeekStart - Sets the file pointer aPos bytes from the start of the 

   223 		 content object.  aPos is not modified by the call to Seek()

   224 		 @li ESeekEnd - Sets the file pointer aPos bytes from the end of the 

   225 		 content object. The aPos parameter supplied should be zero or negative 

   226 		 when using ESeekEnd. Upon completion aPos is updated with the current 

   227 		 position relative to the start of the content object.

   228 		 @li ESeekCurrent - Moves the file pointer aPos bytes from the current 

   229 		 position. Upon completion aPos is updated with the new position relative 

   230 		 to the start of the content object. Suppling a zero value for the aPos Parameter can be

   231 		 used to retrieve the current file pointer location 

   232 		 @li ESeekAddress Sets the aPos parameter to the address of the byte 

   233 		 aPos bytes from the start of the content object

   234 

   235 		 @see TSeek

   236 		 

   237 		 @param aMode	Seek mode - controls the destination of the

   238 		  				seek operation.

   239 		  

   240 		 @param aPos	Offset from either the start, end or current position depending upon 

   241 		 the seek mode. Negative offsets are used to seek before the current position or

   242 		 relative to the end of the file.

   243 		 

   244 		 @return		KErrNone if successful. 

   245 		 @return		Otherwise one of the CAF error codes defined in \c caferr.h  or one 

   246 		 				of the other system-wide error codes.

   247 		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted 

   248 		*/

   249 		virtual TInt Seek(TSeek aMode, TInt& aPos) = 0;

   250 

   251 		/** 

   252 		Allows an application to request the modification of a property 

   253 		within the agent handling this content. The agent may or may not

   254 		permit the property to be changed

   255 		 	

   256 		@param aProperty The property to set.

   257 		@param aValue The value of the property.

   258 		@return Whether or not the property was set.

   259 		@return KErrNone if the property was set.

   260 		@return KErrCANotSupported if the agent does not support the property or value.

   261 		@return KErrAccessDenied if the agent does not permit the property to be changed.

   262 		@return KErrPermissionDenied if the application does not have the necessary capability to change the property.

   263 		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted 

   264 		 */

   265 		virtual TInt SetProperty(TAgentProperty aProperty, TInt aValue) = 0;

   266 

   267 		/**  Get the value of an attribute for this content object

   268  

   269 		@param aAttribute The attribute to query, from ContentAccess::TAttribute.

   270 		@param aValue Used to return the attribute value.

   271 		@return Whether the attribute was updated.

   272 		@return KErrNone if the value of the attribute was updated.

   273 		@return KErrCANotSupported if the requested attribute does not exist.

   274 		@return KErrPermissionDenied if the access to the protected content is not permitted by the CAF Agent.

   275 		@return Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 

   276 				other system-wide error codes for any other errors.

   277 		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted 

   278 		*/

   279 		virtual TInt GetAttribute(TInt aAttribute, TInt& aValue)=0;

   280 

   281 		/** Get a set of attributes from a content object

   282 

   283 		@param aAttributeSet The set of attributes to query and update.

   284 		@return Whether the attribute set was updated.

   285 		@return KErrNone if the attributes were retrieved successfully.

   286 		@return KErrPermissionDenied if the access to the protected content is not permitted by the CAF Agent.

   287 		@return Otherwise one of the CAF error codes defined in \c caferr.h  or one of the 

   288 				other system-wide error codes for any other errors.				 

   289 		*/

   290 		virtual TInt GetAttributeSet(RAttributeSet& aAttributeSet) = 0;

   291 

   292 		/**  Get text string attributes or meta-data for this content object

   293 

   294 		@param aAttribute The attribute to query, from ContentAccess::TStringAttribute.

   295 		@param aValue Returns the value of the attribute.

   296 		@return Whether the value was updated.

   297 		@return KErrNone if the attribute was retrieved.

   298 		@return KErrOverflow if the buffer was not large enough to return the result.

   299 		@return KErrCANotSupported if the requested attribute does not exist.

   300 		@return KErrPermissionDenied if the access to the protected content is not permitted by the CAF Agent.

   301 		@return Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 

   302 				other system-wide error codes for any other errors.				 

   303 		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted 

   304 		*/

   305 		virtual TInt GetStringAttribute(TInt aAttribute, TDes& aValue)=0;

   306 

   307 	

   308 		/** Used to obtain a set of string attributes 

   309 

   310 		@param aStringAttributeSet The set of attributes to query and update.

   311 		@return Whether the string attribute set was updated.

   312 		@return KErrNone if the attributes were retrieved successfully.

   313 		@return KErrNotFound if the default content object was not found.

   314 		@return KErrPermissionDenied if the access to the protected content is not permitted by the CAF Agent.

   315 		@return Otherwise one of the CAF error codes defined in \c caferr.h  or one of the 

   316 				other system-wide error codes for any other errors.				 

   317 		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted. 

   318 		*/

   319 		virtual TInt GetStringAttributeSet(RStringAttributeSet& aStringAttributeSet)=0;

   320 		

   321 		/**  

   322 		 Reads content asynchronously. The data is read from a specified offset 

   323 		 up to a specified number of bytes or until the end of the content object 

   324 		 is reached. The data is read into the descriptor buffer supplied.

   325 		 

   326 		 @see Read(TDes8& aDes)

   327 		 

   328 		 @param aPos		Position of first byte to be read. 

   329 		 					This is an offset from the start of the file. 

   330 		 @param aDes 		Descriptor into which binary data is read. Any

   331 		  					existing contents are overwritten. On return,

   332 		 					its length is set to the number of bytes read. 

   333 		 @param aLength		The number of bytes to read from the file,

   334 		 					or to the end of the file, whichever is encountered first. 

   335 		 					The length of the buffer is set to the number of bytes actually 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 		 @return KErrNone if the async read request was successfully submitted.

   342 		 @return KErrCANotSupported if the agent does not support this operation.

   343 		 @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted 

   344 		*/

   345 		virtual TInt Read(TInt aPos, TDes8& aDes, TInt aLength, TRequestStatus& aStatus);

   346 		};

   347 

   348 	/**	Defines the agent interface allowing clients to browse the objects 

   349 	within a file

   350 

   351 	@publishedPartner

   352 	@released

   353 	*/

   354 	class CAgentContent : public CBase

   355 		{

   356 	public:

   357  		/** Open a Container object within the file.

   358  		

   359  		Allows an application to access the content objects and 

   360  		any nested container objects within the specified container.

   361   		

   362  		@param aUniqueId The container object's unique ID.

   363 		@return Whether the container was opened.

   364  		@return KErrNone if the container was opened successfully.

   365  		@return KErrNotFound if the container does not exist.

   366 		@return KErrPermissionDenied if the access to the protected content is not permitted by the CAF Agent.		 

   367 		@return Otherwise one of the CAF error codes defined in \c caferr.h  or one of the 

   368 				other system-wide error codes for any other errors.

   369 		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted 

   370  		*/

   371 		virtual TInt OpenContainer(const TDesC& aUniqueId) = 0;

   372 

   373  		/** Close the current container object and go back to previous enclosing

   374  		container within the file.

   375  		

   376  		Allows an application to access the content objects and 

   377  		any nested container objects within parent container

   378   		

   379 		@return Whether the container was closed.

   380   		@return KErrNone if the container was closed.

   381   		@return KErrNotFound if there is no enclosing container.

   382   		@return KErrPermissionDenied if the access to the protected content is not permitted by the CAF Agent.		 		

   383   		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted 

   384  		*/

   385 		virtual  TInt CloseContainer() = 0;

   386 

   387 		/** List all the embedded container objects and content objects within the 

   388 		current container

   389  		 		

   390 		The UniqueId() member of CEmbeddedObject can be used to refer directly to 

   391 		a particular object within the file.

   392 

   393 		@param aArray The array to be populated with the embedded objects. 

   394 		@leave KErrPermissionDenied if the access to the protected content is not permitted by the CAF Agent.		 

   395 		@leave ...			One of the CAF error codes defined in \c caferr.h  or one of the 

   396 							other system-wide error codes for any other errors.

   397   		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted 

   398  		*/

   399 		virtual void GetEmbeddedObjectsL(RStreamablePtrArray<CEmbeddedObject>& aArray) = 0;

   400 		

   401 		/** List all the embedded objects within the current container that

   402 		are of the specified type

   403  		 		

   404 		@param aArray The array to be populated with the embedded objects. 

   405 		@param aType The type of objects to list.

   406 		@leave KErrPermissionDenied If the access to the protected content is not permitted by the CAF Agent.		 

   407 		@leave ...			One of the CAF error codes defined in \c caferr.h  or one of the 

   408 							other system-wide error codes for any other errors.

   409   		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted 

   410  		*/

   411 		virtual void GetEmbeddedObjectsL(RStreamablePtrArray<CEmbeddedObject>& aArray, TEmbeddedType aType) = 0;

   412 

   413 		/** Search the current container for content objects with a particular mime type

   414 

   415   		@param aArray The array to store the results of the search. The agent will add CEmbeddedObject objects to the supplied array.

   416 		@param aMimeType The mime type to search for.

   417 		@param aRecursive ETrue to search inside containers embedded within the current container, EFalse to search only the current container.

   418 		@return The result of the search.

   419 		@return KErrNone if the search was successful, even if no content objects were found.

   420 		@return KErrPermissionDenied if the access to the protected content is not permitted by the CAF Agent.		 

   421 		@return Otherwise one of the CAF error codes defined in \c caferr.h  or one of the 

   422 				other system-wide error codes for any other errors.

   423 		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted 

   424 		*/

   425 		virtual TInt Search(RStreamablePtrArray<CEmbeddedObject>& aArray, const TDesC8& aMimeType, TBool aRecursive) = 0;

   426 		

   427 		/**  Get an attribute for an object within the file

   428 	

   429 		@param aAttribute The attribute to query, from ContentAccess::TAttribute.

   430 		@param aValue Used to return the attribute value.

   431 		@param aUniqueId The UniqueId of the object within the file.

   432 		@return Whether the attribute value was updated.

   433 		@return KErrNone if the value of the attribute was updated.

   434 		@return KErrNotFound if the object with the given UniqueId was not found.

   435 		@return KErrCANotSupported if the requested attribute does not exist.

   436 		@return KErrPermissionDenied if the access to the protected content is not permitted by the CAF Agent.	 

   437 		@return Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 

   438 				other system-wide error codes for any other errors.

   439 		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted. 

   440 		*/

   441 		virtual TInt GetAttribute(TInt aAttribute, TInt& aValue, const TDesC& aUniqueId) = 0;

   442 

   443 		/** Get a set of attributes for an object within the file

   444 

   445 		@param aAttributeSet The set of attributes to query and update.

   446 		@param aUniqueId The unique ID of the object within the file.

   447 		@return Whether that attribute set was updated.

   448 		@return KErrNone if the attributes were retrieved successfully.

   449 		@return KErrNotFound if the default content object was not found.

   450 		@return KErrPermissionDenied if the access to the protected content is not permitted by the CAF Agent.		 

   451 		@return Otherwise one of the CAF error codes defined in \c caferr.h  or one of the 

   452 				other system-wide error codes for any other errors.

   453 		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted. 

   454 		*/

   455 		virtual TInt GetAttributeSet(RAttributeSet& aAttributeSet, const TDesC& aUniqueId) = 0;

   456 

   457 		/**  Get text string attributes or meta-data for an object within the file

   458 

   459 		@param aAttribute The attribute to query, from ContentAccess::TStringAttribute.

   460 		@param aValue Returns the value of the attribute.

   461 		@param aUniqueId The UniqueId of the object within the file. 

   462 		@return Whether the attribute value was updated.

   463 		@return KErrNone if the attribute was retrieved.

   464 		@return KErrNotFound if the object with the given UniqueId was not found.

   465 		@return KErrOverflow if the buffer was not large enough to return the result.

   466 		@return KErrCANotSupported if the requested attribute does not exist.

   467 		@return KErrPermissionDenied if the access to the protected content is not permitted by the CAF Agent.	 

   468 		@return Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 

   469 				other system-wide error codes for any other errors.

   470 		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted. 

   471 		*/

   472 		virtual TInt GetStringAttribute(TInt aAttribute, TDes& aValue, const TDesC& aUniqueId) = 0;

   473 

   474 		/** Used to obtain a set of string attributes for an object within the file

   475 

   476 		@param aStringAttributeSet The set of attributes to query and update.

   477 		@param aUniqueId The UniqueId of the container or content. 

   478 		@return Whether the attribute set was updated.

   479 		@return KErrNone if the attributes were retrieved successfully.

   480 		@return KErrNotFound if the object with the given UniqueId was not found.

   481 		@return KErrPermissionDenied if the access to the protected content is not permitted by the CAF Agent.		 

   482 		@return Otherwise one of the CAF error codes defined in \c caferr.h  or one of the 

   483 				other system-wide error codes for any other errors.

   484 		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted. 

   485 		*/

   486 		virtual TInt GetStringAttributeSet(RStringAttributeSet& aStringAttributeSet, const TDesC& aUniqueId)=0;

   487 

   488 		/** Allows extended synchronous calls to the CAF agent handling this file

   489 		

   490 		Applications familiar with the agent can pass objects in and out using serialization.

   491 

   492 		@param aCommand The agent defined command.

   493 		@param aInputBuffer Non modifyable input data buffer.

   494 		@param aOutputBuffer Modifyable output buffer to hold the result of the command.

   495 		@return The outcome of the agent specific command.

   496 		@return KErrCANotSupported if the agent does not recognize the command.

   497 		@return KErrOverflow if the output buffer supplied is too small.

   498 		@return KErrPermissionDenied if the agent does not allow the client to execute the command.

   499 		@return Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 

   500 				other system-wide error codes for any other errors.

   501 		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted 

   502 		*/

   503 		virtual TInt AgentSpecificCommand(TInt aCommand, const TDesC8& aInputBuffer, TDes8& aOutputBuffer) = 0;

   504 

   505 		/** Allows extended synchronous calls to the CAF agent handling this file.

   506 		Applications familiar with the agent can pass objects in and out using serialization.

   507 		NB: No assumption should be made about the scope of the descriptor 

   508 		passed to aInputBuffer for asynchronous IPC.

   509 

   510 		@param aCommand The agent defined command.

   511 		@param aInputBuffer Non modifyable input data buffer.

   512 		@param aOutputBuffer Modifyable output buffer to hold the result of the command.

   513 		@param aStatus Asynchronous request status. On completion this will contain 

   514 						one of the following error codes:

   515 						KErrNone if the command was successfully executed.

   516 						KErrCANotSupported  if the agent does not recognize the command.

   517 						KErrOverflow if the output buffer supplied is too small.

   518 						KErrPermissionDenied if the agent does not allow the client 

   519 						to execute the command. Otherwise one of the other CAF error codes defined 

   520 						in \c caferr.h  or one of the other system-wide error codes 

   521 						for any other errors.

   522 		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted 

   523 		*/

   524 		virtual void AgentSpecificCommand(TInt aCommand, const TDesC8& aInputBuffer, TDes8& aOutputBuffer, TRequestStatus& aStatus) = 0;

   525 

   526 		/** Request notification for an event for an object within the file.

   527 		NB: No assumption should be made about the scope of the descriptor 

   528 		passed to aUniqueId for asynchronous IPC.

   529 

   530 		@param aMask Bitmask of events the caller is interested in.

   531 		@param aStatus The TRequestStatus object to complete if the event occurs.

   532 		@param aUniqueId The UniqueId of the container or content. 

   533 		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted 

   534 		*/

   535 		virtual void NotifyStatusChange(TEventMask aMask, TRequestStatus& aStatus, const TDesC& aUniqueId) = 0;

   536 		

   537 		/** Cancel a previous notification request

   538 

   539 		@param aStatus The TRequestStatus supplied in the call to NotifyStatusChange().

   540 		@param aUniqueId The UniqueId of the content object within the file.

   541 		@return The outcome of the cancel request.

   542 		@return KErrNone if the request was cancelled.

   543 		@return KErrNotFound if there was no matching request outstanding.

   544 		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted 

   545 		*/

   546 		virtual TInt CancelNotifyStatusChange(TRequestStatus& aStatus, const TDesC& aUniqueId) = 0;

   547 

   548 		/** Request the agent to obtain rights for a protected content object.

   549 		NB: No assumption should be made about the scope of the descriptor 

   550 		passed to aUniqueId for asynchronous IPC.

   551 

   552 		This request may be handled differently by different agents. 

   553 		Some agents may open a browser and direct the user to a URL. Others may 

   554 		download and install the rights in the background.

   555 

   556 		The call should not block execution, applications can wait for a notification 

   557 		if they are interested in the outcome. 

   558 		

   559 		If a rights request completes sucessfully it does not necessarily mean rights 

   560 		are available. It just means the request is complete.

   561 

   562 		@param aStatus Asynchronous request status. On completion this will contain 

   563 						one of the following error codes:

   564 						KErrNone if the rights request was successful.

   565 						KErrCANotSupported  if the agent does not allow rights requests.

   566 						Otherwise one of the other CAF error codes defined in \c caferr.h  

   567 						or one of the other system-wide error codes 

   568 						for any other errors.

   569 

   570 		@param aUniqueId The unique id of the object within the file.

   571 		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted.		

   572 		*/

   573 		virtual void RequestRights(TRequestStatus& aStatus, const TDesC& aUniqueId) = 0; 

   574 

   575 		/** Cancel a previous RequestRights() request

   576 

   577 		@param aStatus The TRequestStatus that was supplied to the RequestRights() function.

   578 		@param aUniqueId The objects Unique Id that was supplied to the RequestRights() function.

   579 		@return The result of the cancel rights request.

   580 		@return KErrNone if the rights request was cancelled.

   581 		@return KErrNotFound if there was no matching rights request outstanding.

   582 		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted 

   583 		*/

   584 		virtual TInt CancelRequestRights(TRequestStatus& aStatus, const TDesC& aUniqueId) = 0;

   585 

   586 		/** View information associated with a single content object

   587 		

   588 		This call blocks execution and only returns once the display is dismissed 

   589 		by the user.

   590 

   591 		@param aInfo The information to display.

   592 		@param aUniqueId The unique id of the object within the file.

   593 		@leave KErrCANotSupported if information cannot be displayed or does not exist.

   594 		@leave ...			One of the other CAF error codes defined in \c caferr.h  

   595 							or one of the system-wide error codes for 

   596 							any other errors.

   597 		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted. 

   598 		*/

   599 		virtual void DisplayInfoL(TDisplayInfo aInfo, const TDesC& aUniqueId) = 0;

   600 

   601 		/** 

   602 		Allows an application to request the modification of a property 

   603 		within the agent handling this content. The agent may or may not

   604 		permit the property to be changed

   605 		 	

   606 		@param aProperty The property to set.

   607 		@param aValue The value of the property.

   608 		@return Whether the property was set.

   609 		@return KErrNone if the property was set.

   610 		@return KErrCANotSupported if the agent does not support the property or value.

   611 		@return KErrAccessDenied if the agent does not permit the property to be changed.

   612 		@return KErrPermissionDenied if the application does not have the necessary capability to change the property.

   613 		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted 

   614 		*/

   615 		virtual TInt SetProperty(TAgentProperty aProperty, TInt aValue) = 0;

   616 		

   617 		};

   618 

   619 	/**

   620 	 Defines the interface for importing files into a Content access agent. 

   621 

   622 	The agent should treat the import as a transaction and either import the

   623 	entire file or revert to the state before the import if the import is cancelled.

   624 	

   625 	The client cancels an import by deleting the CAgentImportFile object 

   626 	before WriteDataComplete() is called. 

   627 	 

   628 	 @publishedPartner

   629 	 @released

   630 	 */

   631 	class CAgentImportFile : public CBase

   632 		{

   633 	public:

   634 

   635 		/** Writes a block of data from a file to the agent

   636 		

   637 		@param aData The block of data.

   638 		@return	The result of the write operation.

   639 		@return KErrNone if the data was written successfully.

   640 		@return	KErrCANewFileHandleRequired if the agent requires the client to provide a new file handle before proceeding. The agent must save its state and continue processing when the new handle is supplied by ContinueWithNewOutputFile().

   641 		@return KErrNotReady if the agent was not expecting WriteData() to be called at this point.

   642 		@return Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 

   643 				other system-wide error codes for any other errors.

   644 		@capability DRM Importing DRM protected content is not permitted for processes without DRM capability. 

   645 		*/

   646 		virtual TInt WriteData(const TDesC8& aData)=0;

   647 

   648 		/** Signals to the agent that the entire file has now been transferred to the agent.

   649 		

   650 		@return The result of the write operation. 

   651 		@return KErrNone if the data was written successfully.

   652 		@return	KErrCANewFileHandleRequired if the agent requires the client to provide a new file handle before proceeding. The agent must save its state and continue processing when the new handle is supplied by ContinueWithNewOutputFile().

   653 		@return KErrNotReady if the agent was not expecting WriteDataComplete() to be called at this point.

   654 		@return Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 

   655 				other system-wide error codes for any other errors.		

   656 		@capability DRM Importing DRM protected content is not permitted for processes without DRM capability. 

   657 		*/

   658 		virtual TInt WriteDataComplete()=0;

   659 

   660 		/** Asynchronously writes a block of data from a file the agent

   661 		 

   662 		Notifies the client when the write operation is complete.

   663 		

   664 		@param aData 	The block of data.

   665 		@param aStatus 	Asynchronous request status. On completion this will 

   666 						contain one of the following error codes: KErrNone if the data was written successfully. 

   667 						KErrCANewFileHandleRequired if the agent requires a new 

   668 						file handle before proceeding - the agent must save its 

   669 						state and continue processing when the new handle 

   670 						is supplied by ContinueWithNewOutputFile().

   671 						KErrNotReady if the agent was not expecting WriteDataComplete() 

   672 						to be called at this point. Otherwise one of the other CAF error codes 

   673 						defined in \c caferr.h  or one of the other standard system-wide 

   674 						error codes for any other errors.

   675 		@capability DRM Importing DRM protected content is not permitted for processes without DRM capability. 

   676 		*/

   677 		virtual void WriteData(const TDesC8& aData, TRequestStatus& aStatus)=0;

   678 

   679 		/** Signals to the agent that the entire file has now been transferred to the agent

   680 		

   681 		Notifies the client when any final processing operation is complete.

   682 		

   683 		@param aStatus 	Asynchronous request status. On completion this will 

   684 						contain one of the following error codes: KErrNone if the data was written successfully. 

   685 						KErrCANewFileHandleRequired if the agent requires a new 

   686 						file handle before proceeding - the agent must save its 

   687 						state and continue processing when the new handle 

   688 						is supplied by ContinueWithNewOutputFile().

   689 						KErrNotReady if the agent was not expecting WriteDataComplete() 

   690 						to be called at this point. Otherwise one of the other CAF error codes 

   691 						defined in \c caferr.h  or one of the other standard system-wide 

   692 						error codes for any other errors.

   693 		@capability DRM Importing DRM protected content is not permitted for processes without DRM capability. 

   694 		*/

   695 		virtual void WriteDataComplete(TRequestStatus& aStatus)=0;

   696 

   697 		/** Gets the number of output files produced so far. 

   698 		@return The number of output files.

   699 		*/

   700 		virtual TInt OutputFileCountL() const = 0;

   701 

   702 		/** Return information about an output file generated by the import operation. 

   703 		

   704 		 It is possible that the output file does not have the same name 

   705 		 as the one suggested at the beginning of the import. An agent may

   706 		 need to use a particular file extension or a particular name.

   707 

   708 		The agent may decide not to store the output file in the output directory 

   709 		suggested at the start of the import. eg. it may store the file in its private 

   710 		server directory.

   711 

   712 		The output files may only appear in this array after the WriteDataComplete() 

   713 		function has been called. 

   714 

   715 		@param aIndex The zero-based index of the file (must be less than the value returned by OutputFileCountL().

   716 		@return The CSupplierOutputFile for this object.

   717 		@capability DRM Importing DRM protected content is not permitted for processes without DRM capability. 

   718 		*/

   719 		virtual CSupplierOutputFile& OutputFileL(TInt aIndex) = 0;

   720 

   721 		/** Retrieve the import status

   722 

   723 		Used to indicate non fatal problems encountered during the import operation.

   724 		Provides feedback to the client in case any problems are encountered.

   725 

   726 		The client can then decide whether or not to continue the import.

   727 		 

   728 		@return	The state of the import operation.

   729 		@capability DRM Importing DRM protected content is not permitted for processes without DRM capability. 

   730 		*/

   731 		virtual TImportStatus GetImportStatus() const = 0;

   732 

   733 		

   734 		/** Get the agents suggestion for the file extension of the output file required by the agent

   735 

   736 		This function should only be called when the agent has returned KErrCANewFileHandleRequired from

   737 		WriteData() or WriteDataComplete().

   738 

   739 		The extension must include the dot '.' character.

   740 

   741 		@param aFileExtension On completion this will contain the appropriate file extension.

   742 		@return The result of the request for a file extension.

   743 		@return KErrNone if the agent populated aFileExtension with the correct file extension.

   744 		@return KErrNotReady if the agent is not waiting for another file handle to be provided.

   745 		@return KErrUnknown if the agent does not know what extension should be used.

   746 		*/

   747 		virtual TInt GetSuggestedOutputFileExtension(TDes& aFileExtension) = 0;

   748 

   749 		/** Get the agents suggestion for the file name (with extension) of the output file required by the agent

   750 

   751 		This function should only be called when the agent has returned KErrCANewFileHandleRequired from

   752 		WriteData() or WriteDataComplete().

   753 

   754 		The file name is of the form filename.extension.

   755 

   756 		@param aFileName On completion this will contain the appropriate filename.

   757 		@return KErrNone if the agent populated aFileName with the correct file name.

   758 		@return KErrNotReady if the agent is not waiting for another file handle to be provided.

   759 		@return KErrUnknown if the agent does not know what file name should be used.

   760 		*/

   761 		virtual TInt GetSuggestedOutputFileName(TDes& aFileName) = 0;

   762 

   763 		/** Continue the last write operation with a new file handle as requested by the agent

   764 

   765 		@param aFile A new file handle opened with write permission.

   766 		@param aFileName The name of the file handle that has  been supplied. This is used by the agent when creating CSupplierOutputFile objects. It should include the full path and filename in order to be consistent with files generated by the agent.

   767 		@return The result of the continuing write operation.

   768 		@return KErrNone if the WriteData() or WriteDataComplete() operation is now complete.

   769 		@return KErrCANewFileHandleRequired if the agent requires a new 

   770 						file handle before proceeding - the agent must save its 

   771 						state and continue processing when the new handle 

   772 						is supplied by ContinueWithNewOutputFile().

   773 		@return Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 

   774 				other system-wide error codes for any other errors.		

   775 		*/

   776 		virtual TInt ContinueWithNewOutputFile(RFile& aFile, const TDesC& aFileName) = 0;

   777 

   778 		/** Continue the last write operation with a new file handle and return the result asynchronously.

   779 

   780 		@param aFile A new file handle opened with write permission

   781 		@param aFileName The name of the file handle that has  been supplied. This is used by the agent when creating CSupplierOutputFile objects. It should include the full path and filename in order to be consistent with files generated by the agent

   782 		

   783 		@param aStatus 	Asynchronous request status. On completion this will 

   784 						contain one of the following error codes: KErrNone if the 

   785 						WriteData() or WriteDataComplete() operation is now complete.

   786 						KErrCANewFileHandleRequired if the agent requires a new 

   787 						file handle before proceeding - the agent must save its 

   788 						state and continue processing when the new handle 

   789 						is supplied by ContinueWithNewOutputFile(). Otherwise one of the 

   790 						other CAF error codes defined in \c caferr.h  or one of the 

   791 						other system-wide error codes for any other errors.

   792 		*/

   793 		virtual void ContinueWithNewOutputFile(RFile& aFile, const TDesC& aFileName, TRequestStatus& aStatus) = 0;

   794 		

   795 		/** Cancel an outstanding asynchronous WriteData() request.

   796 		*/

   797 		IMPORT_C virtual void Cancel();

   798 		

   799 		/** Retrieve the content MIME type based on available data

   800 		

   801 		This function should only be called when the agent has returned KErrCANewFileHandleRequired from WriteData()

   802 		If the agent cannot return a content MIME type, the importer should assume that no content type

   803 		will be available until after the import session has been finished 

   804 

   805 		@param aContentMime On return this will contain the appropriate content MIME type.

   806 		@return The result of the request for a content MIME type.

   807 		@return ETrue if the agent populated aContentMime with the correct content MIME type.

   808 		@return EFalse if the agent cannot return the content MIME type (for example, there 

   809 					is not enough data, or the content is multi-part)

   810 		*/

   811 		IMPORT_C virtual TBool ContentMimeTypeL(TDes8& aContentMime);

   812 				

   813 		};

   814 

   815 	/**

   816 	 Defines the agent interface for manager operations. 

   817 	 

   818 	 The CAgentManager is not related to any particular content object but 

   819 	 used to manage files and settings belonging to this agent

   820 	 

   821 	All operations performed by the agent manager should be implemented in a 

   822 	transactional manner by either completing or reverting to the state before

   823 	the function was called.

   824 	 

   825  	 @publishedPartner

   826 	 @released

   827 	 */	

   828 	class CAgentManager : public CBase

   829 		{

   830 	public:

   831 		/** 

   832 		 Delete a file belonging to this agent

   833 

   834 		 The agent implementation may delete rights that were associated with 

   835 		 the content at the same time. If an agent does delete rights at the same

   836 		 time as the content it should display a confirmation dialog that makes it

   837 		 clear to the user the rights they paid for will be also deleted. 

   838 

   839 		 Execution will be blocked until any dialog displayed is complete. Applications 

   840 		 can request to disable the agents user interface using the SetProperty() command

   841 		 

   842 		 Access to the agents private directory is permitted at the 

   843 		 agents discretion.

   844 

   845 		 @param aFileName The full pathname of the file to delete.

   846 		 @return The outcome of the delete operation.

   847 		 @return KErrNone if the file was deleted successfully.

   848 		 @return KErrCancel if the user selects cancel in an agent supplied confirmation screen.

   849 		 @return KErrAccessDenied if the agent does not allow the file to be deleted.

   850 		 @return KErrCANotSupported if the agent does not support file deletion

   851 		 @return KErrPermissionDenied if the client does not have the necessary capabilities to delete the file.

   852 		@return Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 

   853 				other system-wide error codes for any other errors.

   854 		 @capability DRM Deleting DRM protected content is not permitted for processes without DRM capability. 

   855 		 */

   856 		virtual TInt DeleteFile(const TDesC &aFileName) = 0;

   857 

   858 		/**

   859 		Make a copy of the content file (eg to removable media) belonging to this agent

   860 

   861 		Access to the agents private directory is permitted at the 

   862 		agents discretion.

   863 

   864   		@param aSource The full pathname of the source file.

   865 		@param aDestination The full pathname of the destination file.

   866 		@return The outcome of the copy operation.

   867 		@return KErrNone if the file was copied successfully.

   868 		@return KErrAccessDenied if the agent does not allow the file to be copied.

   869 		@return KErrCANotSupported if the agent does not support file copying.

   870 		@return KErrPermissionDenied if the client does not have the necessary capabilities to copy the file.

   871 		@return Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 

   872 				other system-wide error codes for any other errors.

   873   		@capability DRM Copying DRM protected files is not permitted for processes without DRM capability. Copying unprotected files is permitted

   874 		*/

   875 		virtual TInt CopyFile(const TDesC& aSource, const TDesC& aDestination) = 0;

   876 

   877 		/**

   878 		Rename or move the content file (eg to removable media) belonging to this agent

   879 

   880 		Access to the agent private directories is permitted at the 

   881 		agents discretion.

   882 

   883 		@param aSource The full pathname of the source file.

   884 		@param aDestination The full pathname of the destination file.

   885 		@return The outcome of the Rename operation.

   886 		@return KErrNone if the file was moved or renamed successfully.

   887 		@return KErrAccessDenied if the agent does not allow the file to be moved or renamed.

   888 		@return KErrCANotSupported if the agent does not support file renaming.

   889 		@return KErrPermissionDenied if the client does not have the necessary capabilities to move or rename the file.

   890 		@return Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 

   891 				other system-wide error codes for any other errors.

   892   		@capability DRM Moving DRM protected files is not permitted for processes without DRM capability. Moving unprotected files is permitted

   893 		*/

   894 		virtual TInt RenameFile(const TDesC& aSource, const TDesC& aDestination) = 0;

   895 

   896 		/** Create a directory

   897 

   898 		This function can be used to create a directory within in the agent's 

   899 		private directory. Access to the agents private directory is permitted at the 

   900 		agents discretion. 

   901 

   902 		@param aPath The full pathname of the directory to create.

   903 		@return The outcome of the MkDir operation.

   904 		@return KErrNone if the directory was created successfully.

   905 		@return KErrAccessDenied if the agent does not allow the directory to be created.

   906 		@return KErrCANotSupported if the agent does not support directory creation.

   907 		@return KErrPermissionDenied if the client does not have the necessary capabilities to create directories.

   908 		@return Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 

   909 				other system-wide error codes for any other errors.

   910 		

   911 		@capability DRM Required when attempting to access an agents private directory

   912 		*/

   913 		virtual TInt MkDir(const TDesC& aPath) = 0;

   914 

   915 		/** Create all directories in the given path if they do not exist

   916 

   917 		This function can be used to create directories within in the agent's 

   918 		private directory. Access to the agents private directory is permitted at the 

   919 		agents discretion. 

   920 		

   921 		@param aPath The full pathname of the directory to create.

   922 		@return The outcome of the MkDirAll operation.

   923 		@return KErrNone if the directory was created successfully.

   924 		@return KErrAccessDenied if the agent does not allow the directory to be created.

   925 		@return KErrPermissionDenied if the client does not have the necessary capabilities to create directories.

   926 		@return Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 

   927 				other system-wide error codes for any other errors.

   928 		@capability DRM Required when attempting to access an agents private directory

   929 		*/

   930 		virtual TInt MkDirAll(const TDesC& aPath) = 0;

   931 

   932 		/** Remove a directory

   933 

   934 		This function can be used to remove a directory from within the agent's 

   935 		private directory. Access to the agents private directory is permitted 

   936 		at the agents discretion. 

   937 		

   938 		@param aPath The full pathname of the directory to remove.

   939 		@return The outcome of the RmDir operation.

   940 		@return KErrNone if the directory was removed successfully.

   941 		@return KErrAccessDenied if the agent does not allow the directory to be removed.

   942 		@return KErrCANotSupported if the agent does not support directory removal.

   943 		@return KErrPermissionDenied if the client does not have the necessary capabilities to remove directories.

   944 		@return Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 

   945 				other system-wide error codes for any other errors.

   946 		@capability DRM Required when attempting to access an agents private directory

   947 		*/

   948 		virtual TInt RmDir(const TDesC& aPath) = 0;

   949 

   950 		/**  Gets a filtered list of a directory's contents. 

   951 

   952 		The bitmask determines which file and directory entry types should be listed. The sort key determines the order in which they are listed.

   953 

   954 		Notes:

   955 		-# If sorting by UID (as indicated when the ESortByUid bit is OR'ed with the sort key), then UID information will be included in the listing whether or not KEntryAttAllowUid is specified in aEntryAttMask.

   956 		-# The function sets aFileList to NULL, and then allocates memory for it before appending entries to the list. Therefore, aFileList should have no memory allocated to it before this function is called, otherwise this memory will become orphaned.

   957 		-# The caller of this function is responsible for deleting aFileList after the function has returned.

   958 

   959 

   960 		This function can be used to list the contents of the agent's 

   961 		private directory. Access to the agents private directory is permitted at 

   962 		the agents discretion. 

   963 		

   964 		Agents can just return KErrCANotSupported if they do not wish to publish their

   965 		private directory. Alternatively they can just populate the CDir object

   966 		with the entries they wish to show.

   967 	

   968   		@param aName The name of the directory for which a listing is required. Wildcards may be used to specify particular files.

   969 		@param aEntryAttMask Bitmask indicating the attributes of interest. Only files and directories whose attributes match those specified here can be included in the listing. For more information, see KEntryAttMatchMask and the other directory entry details. Also see KEntryAttNormal and the other file or directory attributes 

   970 		@param aEntrySortKey The sort key. This is a set of flags indicating the order in which the entries are to be sorted. These flags are defined by TEntryKey. 

   971 		@param aEntryList On return contains a filtered list of directory and file entries.

   972 		@return The outcome of the GetDir operation.

   973 		@return KErrNone if the directory contents were listed successfully.

   974 		@return KErrCANotSupported if the agent does not allow clients to view its private directory.

   975 		@return KErrPermissionDenied if the process does not have the correct capabilities to view the directory.

   976 		@return Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 

   977 				other system-wide error codes for any other errors.

   978 		@capability DRM Required when attempting to access an agents private directory

   979 		*/

   980 		virtual TInt GetDir(const TDesC& aName,TUint aEntryAttMask,TUint aEntrySortKey, CDir*& aEntryList) const = 0;

   981 

   982 		/**  Gets a filtered list of the directory and file entries contained in a directory and a list of the directory entries only

   983 

   984 		The bitmask determines which file and directory entry types should be listed in aFileList. The contents of the second list, aDirList are not affected by the bitmask; it returns all directory entries contained in directory aName. The sort key determines the order in which both lists are sorted.

   985 

   986 		Notes:

   987 		-# If sorting by UID (as indicated when the ESortByUid bit is OR'ed with the sort key), then UID information will be included in the listing whether or not KEntryAttAllowUid is specified in aEntryAttMask.

   988 		-# The function sets both aFileList and aDirList to NULL, and then allocates memory to them before appending entries to the lists. Therefore, aFileList and aDirList should have no memory allocated to them before this function is called, otherwise the allocated memory will become orphaned.

   989 		-# The caller of this function is responsible for deleting aFileList and aDirList after the function has returned.

   990 

   991 		This function can be used to list the contents of the agent's 

   992 		private directory. Access to the agents private directory is permitted at 

   993 		the agents discretion. 

   994 

   995 		Agents can just return KErrCANotSupported if they do not wish to publish their

   996 		private directory. Alternatively they can just populate the CDir object

   997 		with the entries they wish to show.

   998 

   999 		@param aName The name of the directory for which a listing is required. Wildcards may be used to specify particular files. 

  1000 		@param aEntryAttMask Bitmask indicating the attributes of interest. Only files and directories whose attributes match those specified here can be included in aFileList. aDirList is unaffected by this mask. For more information, see KEntryAttMatchMask and the other directory entry details. Also see KEntryAttNormal and the other file or directory attributes.

  1001 		@param aEntrySortKey The sort key. This is a set of flags indicating the order in which the entries in both lists are to be sorted. These flags are defined by TEntryKey. 

  1002 		@param aEntryList On return contains a filtered list of directory and file entries. 

  1003 		@param aDirList On return contains a filtered list of directory entries only.

  1004 		@return The outcome of the GetDir operation.

  1005 		@return KErrNone The directory contents were listed successfully.

  1006 		@return KErrCANotSupported The agent does not allow clients to view its private directory.

  1007 		@return KErrPermissionDenied If the process does not have the correct capabilities to view the directory.

  1008 		@return Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 

  1009 				other system-wide error codes for any other errors.

  1010 		@capability DRM Required when attempting to access an agents private directory

  1011 		*/

  1012 		virtual TInt GetDir(const TDesC& aName,TUint aEntryAttMask,TUint aEntrySortKey, CDir*& aEntryList,CDir*& aDirList) const = 0;

  1013 

  1014 		/**  Gets a filtered list of a directory's contents by UID

  1015 

  1016 		The aUidType parameter determines which file entry types should be listed. The sort key determines the order in which they are listed.

  1017 

  1018 		Notes:

  1019 		-# The function sets aFileList to NULL, and then allocates memory for it before appending entries to the list. Therefore, aFileList should have no memory allocated to it before this function is called, otherwise this memory will become orphaned.

  1020 		-# The caller of this function is responsible for deleting aFileList after the function has returned.

  1021 

  1022 		This function can be used to list the contents of the agent's 

  1023 		private directory. Access to the agents private directory is permitted at 

  1024 		the agents discretion. 

  1025 

  1026 		Agents can just return KErrCANotSupported if they do not wish to publish their

  1027 		private directory. Alternatively they can just populate the CDir object

  1028 		with the entries they wish to show.

  1029 

  1030 		@param aName The name of the directory for which a listing is required. Wildcards may be used to specify particular files. 

  1031 		@param aEntryUid Only those files whose UIDs match those specified within this UID type will be included in the file list. Any, or all, of the three UIDs within the UID type may be omitted. Any UID which is omitted acts in a similar manner to a wildcard character, matching to all UIDs. 

  1032 		@param aEntrySortKey The sort key. This is a set of flags indicating the order in which the entries are to be sorted. These flags are defined by TEntryKey.

  1033 		@param aFileList On return contains a filtered list of directory and file entries.

  1034 		@return The outcome of the GetDir operation.

  1035 		@return KErrNone The directory contents were listed successfully.

  1036 		@return KErrCANotSupported The agent does not allow clients to view its private directory.

  1037 		@return KErrPermissionDenied If the process does not have the correct capabilities to view the directory.

  1038 		@return Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 

  1039 				other system-wide error codes for any other errors.

  1040 		@capability DRM Required when attempting to access an agents private directory

  1041 		*/

  1042 		virtual TInt GetDir(const TDesC& aName,const TUidType& aEntryUid,TUint aEntrySortKey, CDir*& aFileList) const = 0;

  1043 		

  1044 		/**  Get an attribute from a content object

  1045 	

  1046 		@param aAttribute The attribute to retrieve, from ContentAccess::TAttribute.

  1047 		@param aValue Used to return the value of the attribute.

  1048 		@param aVirtualPath The content object whose attributes are to be queried.

  1049 		@return Whether the attribute value was updated.

  1050 		@return KErrNone if the attribute value was updated.

  1051 		@return KErrNotFound if the URI or the object with the given UniqueId inside the file was not found.

  1052 		@return KErrCANotSupported if the requested attribute is not supported for this content object.

  1053 		@return Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 

  1054 				other system-wide error codes for any other errors.

  1055 		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted. 

  1056 		*/

  1057 		virtual TInt GetAttribute(TInt aAttribute, TInt& aValue, const TVirtualPathPtr& aVirtualPath) = 0;

  1058 

  1059 		/** Get a set of attributes from a content object

  1060 

  1061 		@param aAttributeSet The set of attributes to query and update.

  1062 		@param aVirtualPath The content object to retrieve attributes from.

  1063 		@return Whether the attribute set was updated.

  1064 		@return KErrNone if the attribute set was updated successfully.

  1065 		@return KErrNotFound if the content object was not found.

  1066 		@return Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 

  1067 				other system-wide error codes for any other errors.

  1068 		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted. 

  1069 		*/

  1070 		virtual TInt GetAttributeSet(RAttributeSet& aAttributeSet, const TVirtualPathPtr& aVirtualPath) = 0;

  1071 		

  1072 		/**  Get text string attributes or meta-data from the file 

  1073 

  1074 		@param aAttribute The attribute to retrieve, from ContentAccess::TStringAttribute.

  1075 		@param aValue Used to return the value of the attribute.

  1076 		@param aVirtualPath The content object whose attributes are to be retrieved.

  1077 		@return Whether the value was updated.

  1078 		@return KErrNone if the attribute was retrieved successfully.

  1079 		@return KErrNotFound if the content object does not exist.

  1080 		@return KErrCANotSupported if the requested attribute does not apply to this content object.

  1081 		@return KErrOverflow if the buffer was not large enough to return the result.

  1082 		@return Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 

  1083 				other system-wide error codes for any other errors.

  1084 		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted. 

  1085 		*/

  1086 		virtual TInt GetStringAttribute(TInt aAttribute, TDes& aValue, const TVirtualPathPtr& aVirtualPath) = 0;

  1087 

  1088 		/** Used to obtain a set of string attributes 

  1089 

  1090 		@param aStringAttributeSet The set of attributes to query and update.

  1091 		@param aVirtualPath The content object whose attributes are to be retrieved.

  1092 		@return Whether the string attribute set was updated.

  1093 		@return KErrNone if the attribute set was updated successfully.

  1094 		@return KErrNotFound if the object with the given virtual path was not found.

  1095 		@return Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 

  1096 				other system-wide error codes for any other errors.

  1097 		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted. 

  1098 		*/

  1099 		virtual TInt GetStringAttributeSet(RStringAttributeSet& aStringAttributeSet, const TVirtualPathPtr& aVirtualPath) = 0;

  1100 

  1101 		/** Notify the caller when the status of a DRM protected content object changes.

  1102 		NB: No assumption should be made about the scope of the descriptor 

  1103 		passed to aURI for asynchronous IPC.

  1104 

  1105 		@param aURI The location of the file.

  1106 		@param aMask Bitmask of events the caller is interested in.

  1107 		@param aStatus The TRequestStatus object to complete if the event occurs, or KErrCANotSupported if the agent does not support asynchronous notifications.

  1108 		@capability DRM Deleting DRM protected content is not permitted for processes without DRM capability. 

  1109 		*/

  1110 		virtual void NotifyStatusChange(const TDesC& aURI, TEventMask aMask, TRequestStatus& aStatus) = 0;

  1111 

  1112 		/** Cancel a previous notification request

  1113 		@param aURI The URI supplied in the call to NotifyStatusChange().

  1114 		@param aStatus The TRequestStatus supplied in the call to NotifyStatusChange().

  1115 		@return The outcome of the cancel request.

  1116 		@return KErrNone if the notification was cancelled.

  1117 		@return KErrNotFound if there was no matching request outstanding.

  1118 		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted 

  1119 		*/

  1120 		virtual TInt CancelNotifyStatusChange(const TDesC& aURI, TRequestStatus& aStatus) = 0;

  1121 

  1122 		/** 

  1123 		Allows an application to request the modification of a property 

  1124 		within the agent. The agent may or may not permit the property to be changed

  1125 		 	

  1126 		@param aProperty The property to set.

  1127 		@param aValue The value of the property.

  1128 		@return The outcome of the set property command.

  1129 		@return KErrNone if the property was set by all agents.

  1130 		@return KErrCANotSupported if one of the agent does not support the property or value.

  1131 		@return KErrAccessDenied if one of the agents does not permit the property to be changed.

  1132 		@return KErrPermissionDenied if the application does not have the necessary capability to change the property.

  1133 		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted 

  1134 		*/