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 @file

    21 

    22 @publishedPartner

    23 @released

    24 */

    25 

    26 

    27 #ifndef __CONTENT_H__

    28 #define __CONTENT_H__

    29 

    30 #include <e32base.h>

    31 #include <f32file.h>

    32 

    33 #include <caf/caftypes.h>

    34 #include <caf/agent.h>

    35 #include <caf/streamableptrarray.h>

    36 #include <caf/virtualpathptr.h>

    37 

    38 namespace ContentAccess

    39 	{

    40 	class CAgentResolver;

    41 	class CAgentFactory;

    42 	class CAgentContent;

    43 	class CData;

    44 	class CEmbeddedObject;

    45 	class RAttributeSet;

    46 	class RStringAttributeSet;

    47 

    48 	

    49 

    50 #ifndef REMOVE_CAF1

    51 	class CAttribute;

    52 #endif

    53 	

    54 

    55 /**

    56    CContent allows applications to browse the content objects contained within a 

    57    single file and construct a CData object for reading that content.

    58  

    59   Applications will use an object of this type rather than the traditional 

    60   RFile mechanisms. They will, however, be  required to indicate 

    61   <i>DRM Intent</i> - something that determines whether (and how) access to

    62   the content should be permitted by a Content-Access agent.

    63  

    64   CContent allows direct access to meta-data such as the attributes of 

    65   the content and indirect access to the plaintext data itself through 

    66   the CData class. 

    67   

    68   Applications can use CContent to browse the hierarchy of content objects 

    69   within a file containing several content objects.

    70    

    71   During construction CContent loads the correct CAF Agent plugin to handle 

    72   the file specified by the URI.

    73   

    74   @publishedPartner

    75   @released

    76  */

    77 	class CContent :  public CBase

    78 		{

    79 	public:

    80 

    81 		/**

    82 		 Constructs a new CContent object with a given URI. The URI can be in the same format as a virtual path for more information see CVirtualPath and TVirtualPathPtr

    83 

    84 		 @param aURI	The filename, URI or virtual path of the DRM file.

    85 		 @return a new CContent object.

    86 		 @leave KErrNotFound If the file at the given URI does not exist or if an invalid URI or virtual path have been supplied.

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

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

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

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

    91 		 */

    92 		IMPORT_C static CContent* NewLC(const TDesC& aURI);

    93 

    94 		/**

    95 		 Constructs a new CContent object with a given URI. The URI can be in the same format as a virtual path for more information see CVirtualPath and TVirtualPathPtr

    96 

    97 		 @param aURI	The filename, URI or virtual path of the DRM file.

    98 		 @return a new CContent object.

    99 		 @leave KErrNotFound If the file at the given URI does not exist or if an invalid URI or virtual path have been supplied.

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

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

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

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

   104 		 */

   105 		IMPORT_C static CContent* NewL(const TDesC& aURI);

   106 		

   107 		/**

   108 		 Constructs a new CContent object with a given URI. The URI can be in the same format as a virtual path for more information see CVirtualPath and TVirtualPathPtr

   109 

   110 		 @param aURI	The filename, URI or virtual path of the DRM file.

   111 		 @param aShareMode The sharing mode used when accessing the content.

   112 		 @return a new CContent object.

   113 		 @leave KErrNotFound If the file at the given URI does not exist or if an invalid URI or virtual path have been supplied.

   114 		 @leave KErrAccessDenied If the file is already open with a different share mode.

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

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

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

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

   119 		 */

   120 		IMPORT_C static CContent* NewLC(const TDesC& aURI, TContentShareMode aShareMode);

   121 		

   122 		/** 

   123 		Constructs a new CContent object with a given URI. The URI can be in the same format as a virtual path for more information see CVirtualPath and TVirtualPathPtr

   124 

   125 		@param aURI	The filename, URI or virtual path of the DRM file.

   126 		@param aShareMode The sharing mode used when accessing the content.

   127 		@return a new CContent object.

   128 		@leave KErrNotFound If the file at the given URI does not exist or if an invalid URI or virtual path have been supplied.

   129 		@leave KErrAccessDenied If the file is already open with a different share mode.

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

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

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

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

   134 		*/

   135 		IMPORT_C static CContent* NewL(const TDesC& aURI, TContentShareMode aShareMode);

   136 

   137 		/**

   138 		 Constructs a new CContent object with an open file handle.

   139 

   140   		 CContent will use a duplicate of this file handle, the client is 

   141 		 free to close its file handle any time after creating the CContent 

   142 		 object.

   143 

   144 		 @param aFile The file handle. The file must already be open before calling NewLC. 

   145 		 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.

   146 		 @return a new CContent object.

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

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

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

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

   151 		 */

   152 		IMPORT_C static CContent* NewLC(RFile& aFile);

   153 		

   154 		/** 

   155 		 Constructs a new CContent object with an open file handle.

   156 

   157   		 CContent will use a duplicate of this file handle, the client is 

   158 		 free to close its file handle any time after creating the CContent 

   159 		 object.

   160 

   161 		 @param aFile The file handle. The file must already be open before calling this method. 

   162 		 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.

   163 		 @return a new CContent object.

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

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

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

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

   168 		*/

   169 		IMPORT_C static CContent* NewL(RFile& aFile);

   170 

   171 		/** destructor */

   172 		virtual ~CContent();

   173 

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

   175  		

   176  		Allows an application to access the content objects and 

   177  		any nested container objects within the specified container.

   178   		

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

   180 		@return Whether the container was opened.

   181  		@return KErrNone if the container was opened successfully.

   182  		@return KErrNotFound if the container does not exist.

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

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

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

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

   187  		*/

   188  		IMPORT_C TInt OpenContainer(const TDesC& aUniqueId);

   189 

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

   191  		container within the file.

   192  		

   193  		Allows an application to access the content objects and 

   194  		any nested container objects within parent container.

   195   		

   196 		@return Whether the container was closed.

   197   		@return KErrNone if the container was closed.

   198   		@return KErrNotFound if there is no enclosing container.

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

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

   201  		*/

   202 		IMPORT_C TInt CloseContainer();

   203 

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

   205 		current container

   206  		 		

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

   208 		a particular object within the file.

   209 		

   210 		@code

   211 		// Create a ccontent object for the file of interest

   212 		CContent* content = CContent::NewLC(uri);

   213 		

   214 		// Define an array to store the results

   215 		RStreamablePtrArray <CEmbeddedObject> array;

   216 		CleanupClosePushL(array);

   217 		

   218 		// Find all the content and container objects within the current container

   219 		content->GetEmbeddedObjectsL(array);

   220 		

   221 		// Do something with the array

   222 		....

   223 		

   224 		// Finished

   225 		CleanupStack::PopAndDestroy(2);

   226 		@endcode

   227 		

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

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

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

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

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

   233  		*/

   234 		IMPORT_C void GetEmbeddedObjectsL(RStreamablePtrArray<CEmbeddedObject>& aArray) const;

   235 

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

   237 		are of the specified type

   238 

   239 		@code

   240 		// Create a ccontent object for the file of interest

   241 		CContent* content = CContent::NewLC(uri);

   242 		

   243 		// Define an array to store the results

   244 		RStreamablePtrArray <CEmbeddedObject> array;

   245 		CleanupClosePushL(array);

   246 		

   247 		// Find all the content objects within the current container

   248 		content->GetEmbeddedObjectsL(array, EContentObject);

   249 		

   250 		// Do something with the array

   251 		....

   252 		

   253 		// Finished

   254 		CleanupStack::PopAndDestroy(2);

   255 		@endcode

   256  		 		

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

   258 		@param aType The type of objects to list.

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

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

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

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

   263  		*/

   264 		IMPORT_C void GetEmbeddedObjectsL(RStreamablePtrArray<CEmbeddedObject>& aArray, TEmbeddedType aType) const;

   265 		

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

   267 

   268 		@code

   269 		_LIT8(KTextPlainMimeType, "text/plain");

   270 		

   271 		// Create a ccontent object for the file of interest

   272 		CContent* content = CContent::NewLC(uri);

   273 		

   274 		// Define an array to store the results

   275 		RStreamablePtrArray <CEmbeddedObject> array;

   276 		CleanupClosePushL(array);

   277 		

   278 		// Recursively search for all the content objects with the 

   279 		// specified mime type

   280 		User::LeaveIfError(content->Search(array, KTextPlainMimeType(), ETrue));

   281 		

   282 		// Do something with the array

   283 		....

   284 		

   285 		// Finished

   286 		CleanupStack::PopAndDestroy(2);

   287 		@endcode

   288 

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

   290 		@param aMimeType The mime type to search for.

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

   292 		@return The result of the search.

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

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

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

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

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

   298 		*/

   299 		IMPORT_C TInt Search(RStreamablePtrArray<CEmbeddedObject>& aArray, const TDesC8& aMimeType, TBool aRecursive);

   300 

   301 

   302 		/**  Get an attribute for the default content object within the file

   303 

   304   		@see ContentAccess::TAttribute

   305 

   306 		@code

   307 		TInt value = 0;

   308 		CContent* c = CContent::NewL(uri);

   309 		TInt err =c->GetAttribute(EIsProtected, value);

   310 		if(err == KErrNone && value)

   311 			{

   312 			DisplayPadLock();

   313 			}

   314 		@endcode

   315 

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

   317 		@param aValue Used to return the attribute value.

   318 		@return Whether the attribute value was updated.

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

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

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

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

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

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

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

   326 		*/

   327 		IMPORT_C TInt GetAttribute(TInt aAttribute, TInt& aValue) const;		

   328 

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

   330 

   331 		@see ContentAccess::TAttribute

   332 

   333 		@code

   334 		TInt value = 0;

   335 		CContent* c = CContent::NewL(uri);

   336 		TInt err =c->GetAttribute(EIsProtected, value, uniqueId);

   337 		if(err == KErrNone && value)

   338 			{

   339 			DisplayPadLock();

   340 			}

   341 		@endcode

   342 

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

   344 		@param aValue Used to return the attribute value.

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

   346 		@return Whether the attribute value was updated.

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

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

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

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

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

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

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

   354 		*/

   355 		IMPORT_C TInt GetAttribute(TInt aAttribute, TInt& aValue, const TDesC& aUniqueId) const;

   356 		

   357 

   358 		/** Get a set of attributes for the default content object within the file

   359 

   360 		@see ContentAccess::TAttribute

   361 

   362 		The following example determines whether the default content object 

   363 		is protected and has rights that will enable it to be viewed by the 

   364 		user

   365 

   366 		@code

   367 		CContent* content = CContent::NewLC(uri);

   368 				

   369 		RAttributeSet attributeSet;

   370 		CleanupClosePushL(attributeSet);

   371 		attributeSet->AddL(EProtected);

   372 		attributeSet->AddL(ECanView);

   373 

   374 		User::LeaveIfError(content->GetAttributeSet(attributeSet);

   375 

   376 		TInt err = attributeSet.GetValue(EProtected, value);

   377 		if(err == KErrNone && value)

   378 				{

   379 				// file is DRM protected

   380 				}

   381 

   382 		err = attributeSet.GetValue(ECanView, value);

   383 		if(err == KErrNone && value)

   384 				{

   385 				// File has rights that allow it to be displayed on screen

   386 				}

   387 		

   388 		// Finished

   389 		CleanupStack::PopAndDestroy(2); // content, attributeSet.Close()

   390 		@endcode

   391 

   392 

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

   394 		@return Whether the attribute set was updated.

   395 		@return KErrNone if the attributes were retrieved successfully.

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

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

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

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

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

   401 		*/

   402 		IMPORT_C TInt GetAttributeSet(RAttributeSet& aAttributeSet) const;		

   403 		

   404 		/** Get a set of attributes from an object within the file

   405 

   406 		@see ContentAccess::TAttribute

   407 

   408 		The following example determines whether the default content object 

   409 		is protected and has rights that will enable it to be viewed by the 

   410 		user

   411 

   412 		@code

   413 		CContent* content = CContent::NewLC(uri);

   414 				

   415 		RAttributeSet attributeSet;

   416 		CleanupClosePushL(attributeSet);

   417 		attributeSet->AddL(EProtected);

   418 		attributeSet->AddL(ECanView);

   419 

   420 		User::LeaveIfError(content->GetAttributeSet(attributeSet, uniqueId);

   421 

   422 		TInt err = attributeSet.GetValue(EProtected, value);

   423 		if(err == KErrNone && value)

   424 				{

   425 				// file is DRM protected

   426 				}

   427 

   428 		err = attributeSet.GetValue(ECanView, value);

   429 		if(err == KErrNone && value)

   430 				{

   431 				// File has rights that allow it to be displayed on screen

   432 				}

   433 		

   434 		// Finished

   435 		CleanupStack::PopAndDestroy(2); // content, attributeSet.Close()

   436 		@endcode

   437 

   438 

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

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

   441 		@return Whether that attribute set was updated.

   442 		@return KErrNone if the attributes were retrieved successfully.

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

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

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

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

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

   448 		*/

   449 		IMPORT_C TInt GetAttributeSet(RAttributeSet& aAttributeSet, const TDesC& aUniqueId) const;

   450 		

   451 		/**  Get text string attributes or meta-data for the default content object within the file

   452 	

   453 		@see ContentAccess::TStringAttribute

   454 

   455 		@code

   456 		TInt err = KErrNone;

   457 		

   458 		CContent* c = CContent::NewL(uri);

   459 		TBuf <MAX_PATH> previewUri;

   460 		err = c->GetStringAttribute(EPreviewURI, previewUri);

   461 		if(err == KErrNone)

   462 			{

   463 			DisplayPreview(previewUri);

   464 			}

   465 		@endcode

   466 

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

   468 		@param aValue Returns the value of the attribute.

   469 		@return Whether the attribute value was updated.

   470 		@return KErrNone if the attribute was retrieved.

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

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

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

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

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

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

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

   478 		*/

   479 		IMPORT_C TInt GetStringAttribute(TInt aAttribute, TDes& aValue) const;

   480 		

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

   482 

   483 		@see ContentAccess::TStringAttribute

   484 

   485 		@code

   486 		TInt err = KErrNone;

   487 		

   488 		CContent* c = CContent::NewL(uri);

   489 		TBuf <MAX_PATH> previewUri;

   490 		err = c->GetStringAttribute(EPreviewURI, previewUri, uniqueId);

   491 		if(err == KErrNone)

   492 			{

   493 			DisplayPreview(previewUri);

   494 			}

   495 		@endcode

   496 

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

   498 		@param aValue Returns the value of the attribute.

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

   500 		@return Whether the attribute value was updated.

   501 		@return KErrNone if the attribute was retrieved.

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

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

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

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

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

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

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

   509 		*/

   510 		IMPORT_C TInt GetStringAttribute(TInt aAttribute, TDes& aValue, const TDesC& aUniqueId) const;

   511 		

   512 		/** Obtain a set of string attributes for the default content object within the file

   513 

   514 		@see ContentAccess::TStringAttribute

   515 	  

   516 		@code

   517 		CContent* content = CContent::NewLC(uri);

   518 		

   519 		// create the attribute set, add the attributes we are interested in

   520 		RStringAttributeSet stringAttributeSet;

   521 		CleanupClosePushL(stringAttributeSet);

   522 		stringAttributeSet.AddL(EPreviewURI);

   523 		stringAttributeSet.AddL(ETitle);

   524 		

   525 		User::LeaveIfError(content->GetStringAttributeSet(stringAttributeSet));

   526 	

   527 		// Pass the value of the string attribute to DisplayPreview()

   528 		TFileName previewUri;		

   529 		TInt err = stringAttributeSet.GetValue(EPreviewURI, previewUri);

   530 		if(err == KErrNone)

   531 			{

   532 			DisplayPreview(previewUri);

   533 			}

   534 		

   535 		CleanupStack::PopAndDestroy(2); // content, stringAttributeSet.Close()

   536 		@endcode

   537 	

   538 

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

   540 		@return Whether the attribute set was updated.

   541 		@return KErrNone if the attributes were retrieved successfully.

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

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

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

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

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

   547 		*/

   548 		IMPORT_C TInt GetStringAttributeSet(RStringAttributeSet& aStringAttributeSet) const;

   549 	

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

   551 

   552 		@see ContentAccess::TStringAttribute

   553 	

   554 		@code

   555 		CContent* content = CContent::NewLC(uri);

   556 		

   557 		// create the attribute set, add the attributes we are interested in

   558 		RStringAttributeSet stringAttributeSet;

   559 		CleanupClosePushL(stringAttributeSet);

   560 		stringAttributeSet.AddL(EPreviewURI);

   561 		stringAttributeSet.AddL(ETitle);

   562 		

   563 		User::LeaveIfError(content->GetStringAttributeSet(stringAttributeSet, uniqueId));

   564 	

   565 		// Pass the value of the string attribute to DisplayPreview()

   566 		TFileName previewUri;		

   567 		TInt err = stringAttributeSet.GetValue(EPreviewURI, previewUri);

   568 		if(err == KErrNone)

   569 			{

   570 			DisplayPreview(previewUri);

   571 			}

   572 		

   573 		CleanupStack::PopAndDestroy(2); // content, stringAttributeSet.Close()

   574 		@endcode

   575 	

   576 

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

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

   579 		@return Whether the attribute set was updated.

   580 		@return KErrNone if the attributes were retrieved successfully.

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

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

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

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

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

   586 		*/

   587 		IMPORT_C TInt GetStringAttributeSet(RStringAttributeSet& aStringAttributeSet, const TDesC& aUniqueId) const;

   588 

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

   590 		

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

   592 

   593 		@param aCommand The agent defined command.

   594 		@param aInputBuffer Non modifyable input data buffer.

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

   596 		@return The outcome of the agent specific command.

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

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

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

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

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

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

   603 		*/

   604 		IMPORT_C TInt AgentSpecificCommand(TInt aCommand, const TDesC8& aInputBuffer, TDes8& aOutputBuffer);

   605 

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

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

   608 		NB: It is important that the descriptor passed to 

   609 		aOutputBuffer remains in scope until the request has completed.		

   610 

   611 		@param aCommand The agent defined command.

   612 		@param aInputBuffer Non modifyable input data buffer.

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

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

   615 						one of the following error codes:

   616 						KErrNone if the command was successfully executed.

   617 						KErrCANotSupported  if the agent does not recognize the command.

   618 						KErrOverflow if the output buffer supplied is too small.

   619 						KErrPermissionDenied if the agent does not allow the client 

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

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

   622 						for any other errors.

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

   624 		*/

   625 		IMPORT_C void AgentSpecificCommand(TInt aCommand, const TDesC8& aInputBuffer, TDes8& aOutputBuffer, TRequestStatus& aStatus);

   626 

   627 

   628 		/** Request notification for an event for the default content object within the file

   629 

   630 		@see ContentAccess::TEventMask

   631 

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

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

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

   635 		*/

   636 		IMPORT_C void NotifyStatusChange(TEventMask aMask, TRequestStatus& aStatus);

   637 

   638 		/** Request notification for an event for an object within the file

   639 

   640 		@see ContentAccess::TEventMask

   641 

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

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

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

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

   646 		*/

   647 		IMPORT_C void NotifyStatusChange(TEventMask aMask, TRequestStatus& aStatus, const TDesC& aUniqueId);

   648 

   649 		/** Cancel a previous notification request for the default content object

   650 

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

   652 		@return The outcome of the cancel request.

   653 		@return KErrNone if the request was cancelled.

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

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

   656 		*/

   657 		IMPORT_C TInt CancelNotifyStatusChange(TRequestStatus& aStatus);

   658 

   659 		/** Cancel a previous notification request

   660 

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

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

   663 		@return The outcome of the cancel request.

   664 		@return KErrNone if the request was cancelled.

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

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

   667 		*/

   668 		IMPORT_C TInt CancelNotifyStatusChange(TRequestStatus& aStatus, const TDesC& aUniqueId);

   669 		

   670 		/** Request the agent to obtain rights for the default content object

   671 

   672 		This request may be handled differently by different agents. 

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

   674 		download and install the rights in the background.

   675 

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

   677 		if they are interested in the outcome.

   678 

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

   680 						one of the following error codes:

   681 						KErrNone if the rights request was successful.

   682 						KErrCANotSupported  if the agent does not allow rights requests.

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

   684 						or one of the other system-wide error codes 

   685 						for any other errors.

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

   687 		*/

   688 		IMPORT_C void RequestRights(TRequestStatus& aStatus);

   689 

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

   691 

   692 		This request may be handled differently by different agents. 

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

   694 		download and install the rights in the background.

   695 

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

   697 		if they are interested in the outcome.

   698 

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

   700 						one of the following error codes:

   701 						KErrNone if the rights request was successful.

   702 						KErrCANotSupported  if the agent does not allow rights requests.

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

   704 						or one of the other system-wide error codes 

   705 						for any other errors.

   706 

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

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

   709 		*/

   710 		IMPORT_C void RequestRights(TRequestStatus& aStatus, const TDesC& aUniqueId);

   711 

   712 

   713 		/** Cancel a previous RequestRights() request for the default content object

   714 

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

   716 		@return The result of the cancel rights request.

   717 		@return KErrNone if the rights request was cancelled.

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

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

   720 		*/

   721 		IMPORT_C TInt CancelRequestRights(TRequestStatus& aStatus);

   722 

   723 		/** Cancel a previous RequestRights() request

   724 

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

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

   727 		@return The result of the cancel rights request.

   728 		@return KErrNone if the rights request was cancelled.

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

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

   731 		*/

   732 		IMPORT_C TInt CancelRequestRights(TRequestStatus& aStatus, const TDesC& aUniqueId);

   733 

   734 		/** View information associated with the default content object

   735 	

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

   737 		by the user.

   738 

   739 		@see ContentAccess::TDisplayInfo

   740 

   741 		@param aInfo The information to display.

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

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

   744 							or one of the system-wide error codes for 

   745 							any other errors.

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

   747 		*/

   748 		IMPORT_C void DisplayInfoL(TDisplayInfo aInfo) const;

   749 		

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

   751 		

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

   753 		by the user.

   754 

   755 		@see ContentAccess::TDisplayInfo

   756 

   757 		@param aInfo The information to display.

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

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

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

   761 							or one of the system-wide error codes for 

   762 							any other errors.

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

   764 		*/

   765 		IMPORT_C void DisplayInfoL(TDisplayInfo aInfo, const TDesC& aUniqueId) const;

   766 

   767 

   768 		/** Request the agent handling this content to set a property value. If 

   769 		the property is set it is only set for this CContent session and does not 

   770 		impact other CAF users and is not set for CData products created by the 

   771 		CContent.

   772 

   773   		@see ContentAccess::TAgentProperty

   774 

   775 		@param aProperty The property to set.

   776 		@param aValue The value of the property.

   777 		@return Whether the property was set.

   778 		@return KErrNone if the property was set.

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

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

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

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

   783 		*/

   784 		IMPORT_C TInt SetProperty(TAgentProperty aProperty, TInt aValue);

   785 		

   786 		/** 

   787 		 Grants read access to the default content object based on 

   788 		 evaluation of the supplied intent information. 

   789 		 

   790 		 Note that the intent is simply evaluated and not executed. 

   791 		 To force the intent to be executed, clients must use the call

   792 		 ContentAccess::CData::ExecuteIntent(). 

   793 		 

   794 		 A CData object can be obtained as follows:

   795 		 @code

   796 		 CData* MyData = myContent->OpenContentL(ChosenIntent);

   797 		 ...

   798 		 delete MyData; // when finished accessing plaintext content

   799 		 @endcode

   800 

   801 		 @see ContentAccess::TIntent

   802 

   803 		 @param aIntent	The intent indicator.

   804 		 @return A CData instance. The caller gets ownership of this object.

   805 		 

   806 		 @leave KErrNotFound		The content object with the given UniqueId does not exist.

   807 		 @leave KErrCAPendingRights The rights have not yet arrived but are expected soon.

   808 		 @leave KErrCANoPermission	Rights exist but the specified intent is not permitted.

   809 		 @leave KErrCANoRights		No rights exist for the content object.

   810 		 @leave KErrCANotSupported	Unable to open the object with the specified UniqueId, it may be a container object.

   811 		 @leave KErrPermissionDenied The agent does not allow the client to access the content object.

   812 		 @leave KErrAccessDenied	The content is already in use.

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

   814 		 						or one of the other system-wide error codes for any other 

   815 								errors.		 

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

   817 		 */

   818 		IMPORT_C CData* OpenContentL(TIntent aIntent);

   819 

   820 		/** 

   821 		 Grants read access to the default content object based on 

   822 		 evaluation of the supplied intent information. 

   823 	

   824 		 Note that the intent is simply evaluated and not executed. 

   825 		 To force the intent to be executed, clients must use the call

   826 		 ContentAccess::CData::ExecuteIntent(). 

   827 		 

   828 		 A CData object can be obtained as follows:

   829 		 @code

   830 		 CData* myData = myContent->OpenContentLC(ChosenIntent);

   831 		 ...

   832 		 // when finished accessing plaintext content

   833 		 CleanupStack::PopAndDestroy(myData); 

   834 		 @endcode

   835 

   836 		 @see ContentAccess::TIntent

   837 

   838 		 @param aIntent	The intent indicator.

   839 		 @return A CData instance. The caller gets ownership of this object.

   840 		 

   841 		 @leave KErrNotFound			The content object with the given UniqueId does not exist.

   842 		 @leave KErrCAPendingRights		The rights have not yet arrived but are expected soon.

   843 		 @leave KErrCANoPermission		Rights exist but the specified intent is not permitted.

   844 		 @leave KErrCANoRights			No rights exist for the content object.

   845 		 @leave KErrCANotSupported		Unable to open the object with the specified UniqueId, it may be a container object.

   846 		 @leave KErrPermissionDenied	The agent does not allow the client to access the content object.

   847 		 @leave KErrAccessDenied		The content is already in use.

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

   849 		 						or one of the other system-wide error codes for any other 

   850 								errors.		 

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

   852 		 */

   853 		IMPORT_C CData* OpenContentLC(TIntent aIntent);

   854 		

   855 		/** 

   856 		 Grants read access to the content object based on evaluation of the

   857 		 supplied intent information. 

   858 		 

   859 		 Note that the intent is simply evaluated and not executed. 

   860 		 To force the intent to be executed, clients must use the call

   861 		 ContentAccess::CData::ExecuteIntent(). 

   862 		 

   863 		 A CData object can be obtained as follows:

   864 		 @code

   865 		 CData* MyData = myContent->OpenContentL(ChosenIntent, uniqueId);

   866 		 ...

   867 		 delete MyData; // when finished accessing plaintext content

   868 		 @endcode

   869 		 	

   870 		 @see ContentAccess::TIntent

   871 

   872 		 @param aIntent	The intent indicator.

   873 		 @param aUniqueId The object to open for reading. If the UniqueId is set to KNullDesC16() the entire file will be opened for reading with no transformation.

   874 		 @return A CData instance. The caller gets ownership of this object.

   875 		 

   876 		 @leave KErrNotFound		The content object with the given UniqueId does not exist.

   877 		 @leave KErrCAPendingRights The rights have not yet arrived but are expected soon.

   878 		 @leave KErrCANoPermission	Rights exist but the specified intent is not permitted.

   879 		 @leave KErrCANoRights		No rights exist for the content object.

   880 		 @leave KErrCANotSupported	Unable to open the object with the specified UniqueId, it may be a container object.

   881 		 @leave KErrPermissionDenied The agent does not allow the client to access the content object.

   882 		 @leave KErrAccessDenied	The content is already in use.

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

   884 		 						or one of the other system-wide error codes for any other 

   885 								errors.		 

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

   887 		 */

   888 		IMPORT_C CData* OpenContentL(TIntent aIntent, const TDesC& aUniqueId);

   889 

   890 

   891 		/** 

   892 		 Grants read access to the content object based on evaluation of the

   893 		 supplied intent information. 

   894 		 

   895 		 Note that the intent is simply evaluated and not executed. 

   896 		 To force the intent to be executed, clients must use the call

   897 		 ContentAccess::CData::ExecuteIntent(). 

   898 		 

   899 		 A CData object can be obtained as follows:

   900 		 @code

   901 		 CData* MyData = myContent->OpenContentLC(ChosenIntent, uniqueId);

   902 		 ...

   903 		 PopAndDestroy(MyData); // when finished accessing plaintext content

   904 		 @endcode

   905 		 	

   906 		 @see ContentAccess::TIntent

   907 

   908 		 @param aIntent	The intent indicator.

   909 		 @param aUniqueId The object to open for reading. If the UniqueId is set to KNullDesC16() the entire file will be opened for reading with no transformation.

   910 		 @return A CData instance. The caller gets ownership of this object.

   911 		 

   912 		 @leave KErrNotFound		The content object with the given UniqueId does not exist.

   913 		 @leave KErrCAPendingRights The rights have not yet arrived but are expected soon.

   914 		 @leave KErrCANoPermission	Rights exist but the specified intent is not permitted.

   915 		 @leave KErrCANoRights		No rights exist for the content object.

   916 		 @leave KErrCANotSupported	Unable to open the object with the specified UniqueId, it may be a container object.

   917 		 @leave KErrPermissionDenied The agent does not allow the client to access the content object.

   918 		 @leave KErrAccessDenied	The content is already in use.

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

   920 		 						or one of the other system-wide error codes for any other 

   921 								errors.		 

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

   923 		 */

   924 		IMPORT_C CData* OpenContentLC(TIntent aIntent, const TDesC& aUniqueId);

   925 

   926 

   927 		/** Find out which agent is handling this file

   928 		@return The agent handling the File

   929 		@capability DRM Access to DRM agents is not permitted for processes without DRM capability

   930 		*/

   931 		IMPORT_C const TAgent& Agent() const;

   932 		

   933 #ifndef REMOVE_CAF1

   934 		/** Create a CData object for reading the content 

   935 

   936 		@see ContentAccess::TIntent

   937 		@param aIntent The intended use of the content

   938 		@param aShareMode The mode used to open the file. If EContentShareExclusive is required, use CData::NewL() instead

   939 		@return A new CData object

   940 		@leave One of the CAF error codes defined in \c caferr.h  or one of the system-wide error codes for any errors.

   941 		@capability DRM Access to DRM agents is not permitted for processes without DRM capability

   942 		@deprecated

   943 		*/

   944 		IMPORT_C CData* OpenContentL(TIntent aIntent, TContentShareMode aShareMode);

   945 

   946 		/** Create a CAttribute object to determine the attributes of the default content object

   947 		

   948 		@return The agent handling the File

   949 		@capability DRM Access to DRM agents is not permitted for processes without DRM capability

   950 		@deprecated 

   951 		*/

   952 		IMPORT_C CAttribute* NewAttributeL(TBool aPreloaded);

   953 

   954 		/** Create a CAttribute object to determine the attributes of the default content object

   955 		

   956 		@return The agent handling the File

   957 		@capability DRM Access to DRM agents is not permitted for processes without DRM capability

   958 		@deprecated 

   959 		*/

   960 		IMPORT_C CAttribute* NewAttributeL(TBool aPreloaded, TContentShareMode aShareMode);

   961 

   962 #endif  // REMOVE_CAF1

   963 		

   964 	private:

   965 		CContent(); 

   966 		void ConstructL(RFile& aFile); 

   967 		void ConstructL(const TDesC& aURI, TContentShareMode aShareMode); 

   968 		

   969 	private:	

   970 	

   971 		/** CAgentFactory object is effectively the	ECOM session handle */

   972 		CAgentFactory* iAgentFactory;

   973 

   974 		/** 

   975 		 Agent object used for browsing the contents of a file

   976 		 */

   977 		CAgentContent* iAgentContent;

   978 

   979 		/** Points to the default content object if the file is opened by name */

   980 		CVirtualPath* iVirtualPath;

   981 

   982 		/** The content object referred to by CContent, either points to iVirtualPath

   983 		or points to (KNullDesC(), KDefaultContentObject()) 

   984 		*/

   985 		TVirtualPathPtr iDefaultVirtualPath;

   986 

   987 		/* Stores the name and UID of the agent

   988 		*/

   989 		TAgent iAgent;

   990 		

   991 		/** The share mode used to open the content file*/

   992 		TContentShareMode iShareMode;

   993 

   994 		/** Reference to the file handle if the content was opened with a file handle */

   995 		RFile iFile;

   996 		};

   997 

   998 	} // namespace ContentAccess

   999 #endif /* __CONTENT_H__ */