/*

 * Copyright (c) 2003-2007 Nokia Corporation and/or its subsidiary(-ies).

 * All rights reserved.

 * This component and the accompanying materials are made available

 * under the terms of the License "Eclipse Public License v1.0"

 * which accompanies this distribution, and is available

 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

 *

 * Initial Contributors:

 * Nokia Corporation - initial contribution.

 *

 * Contributors:

 *

 * Description: 

 *

 */

 /** 

 @file

 @publishedPartner

 @released

 */

 #ifndef __CONTENT_H__

 #define __CONTENT_H__

 #include <e32base.h>

 #include <f32file.h>

 #include <caf/caftypes.h>

 #include <caf/agent.h>

 #include <caf/streamableptrarray.h>

 #include <caf/virtualpathptr.h>

 namespace ContentAccess

 	{

 	class CAgentResolver;

 	class CAgentFactory;

 	class CAgentContent;

 	class CData;

 	class CEmbeddedObject;

 	class RAttributeSet;

 	class RStringAttributeSet;

 #ifndef REMOVE_CAF1

 	class CAttribute;

 #endif

 /**

    CContent allows applications to browse the content objects contained within a 

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

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

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

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

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

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

   the content and indirect access to the plaintext data itself through 

   the CData class. 

   Applications can use CContent to browse the hierarchy of content objects 

   within a file containing several content objects.

   During construction CContent loads the correct CAF Agent plugin to handle 

   the file specified by the URI.

   @publishedPartner

   @released

  */

 	class CContent :  public CBase

 		{

 	public:

 		/**

 		 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

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

 		 @return a new CContent object.

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

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

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

 						other system-wide error codes for any other errors.

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

 		 */

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

 		/**

 		 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

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

 		 @return a new CContent object.

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

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

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

 							other system-wide error codes for any other errors.

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

 		 */

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

 		/**

 		 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

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

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

 		 @return a new CContent object.

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

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

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

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

 							other system-wide error codes for any other errors.

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

 		 */

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

 		/** 

 		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

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

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

 		@return a new CContent object.

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

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

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

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

 							other system-wide error codes for any other errors.

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

 		*/

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

 		/**

 		 Constructs a new CContent object with an open file handle.

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

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

 		 object.

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

 		 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.

 		 @return a new CContent object.

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

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

 							other system-wide error codes for any other errors.

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

 		 */

 		IMPORT_C static CContent* NewLC(RFile& aFile);

 		/** 

 		 Constructs a new CContent object with an open file handle.

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

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

 		 object.

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

 		 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.

 		 @return a new CContent object.

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

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

 							other system-wide error codes for any other errors.

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

 		*/

 		IMPORT_C static CContent* NewL(RFile& aFile);

 		/** destructor */

 		virtual ~CContent();

  		/** Open a Container object within the file.

  		Allows an application to access the content objects and 

  		any nested container objects within the specified container.

  		@param aUniqueId The container object's unique ID.

 		@return Whether the container was opened.

  		@return KErrNone if the container was opened successfully.

  		@return KErrNotFound if the container does not exist.

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

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

 				other system-wide error codes for any other errors.

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

  		*/

  		IMPORT_C TInt OpenContainer(const TDesC& aUniqueId);

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

  		container within the file.

  		Allows an application to access the content objects and 

  		any nested container objects within parent container.

 		@return Whether the container was closed.

   		@return KErrNone if the container was closed.

   		@return KErrNotFound if there is no enclosing container.

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

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

  		*/

 		IMPORT_C TInt CloseContainer();

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

 		current container

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

 		a particular object within the file.

 		@code

 		// Create a ccontent object for the file of interest

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

 		// Define an array to store the results

 		RStreamablePtrArray <CEmbeddedObject> array;

 		CleanupClosePushL(array);

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

 		content->GetEmbeddedObjectsL(array);

 		// Do something with the array

 		....

 		// Finished

 		CleanupStack::PopAndDestroy(2);

 		@endcode

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

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

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

 							other system-wide error codes for any other errors.

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

  		*/

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

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

 		are of the specified type

 		@code

 		// Create a ccontent object for the file of interest

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

 		// Define an array to store the results

 		RStreamablePtrArray <CEmbeddedObject> array;

 		CleanupClosePushL(array);

 		// Find all the content objects within the current container

 		content->GetEmbeddedObjectsL(array, EContentObject);

 		// Do something with the array

 		....

 		// Finished

 		CleanupStack::PopAndDestroy(2);

 		@endcode

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

 		@param aType The type of objects to list.

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

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

 							other system-wide error codes for any other errors.

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

  		*/

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

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

 		@code

 		_LIT8(KTextPlainMimeType, "text/plain");

 		// Create a ccontent object for the file of interest

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

 		// Define an array to store the results

 		RStreamablePtrArray <CEmbeddedObject> array;

 		CleanupClosePushL(array);

 		// Recursively search for all the content objects with the 

 		// specified mime type

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

 		// Do something with the array

 		....

 		// Finished

 		CleanupStack::PopAndDestroy(2);

 		@endcode

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

 		@param aMimeType The mime type to search for.

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

 		@return The result of the search.

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

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

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

 				other system-wide error codes for any other errors.

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

 		*/

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

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

   		@see ContentAccess::TAttribute

 		@code

 		TInt value = 0;

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

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

 		if(err == KErrNone && value)

 			{

 			DisplayPadLock();

 			}

 		@endcode

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

 		@param aValue Used to return the attribute value.

 		@return Whether the attribute value was updated.

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

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

 		@return KErrCANotSupported if the requested attribute does not exist.

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

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

 				other system-wide error codes for any other errors.

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

 		*/

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

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

 		@see ContentAccess::TAttribute

 		@code

 		TInt value = 0;

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

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

 		if(err == KErrNone && value)

 			{

 			DisplayPadLock();

 			}

 		@endcode

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

 		@param aValue Used to return the attribute value.

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

 		@return Whether the attribute value was updated.

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

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

 		@return KErrCANotSupported if the requested attribute does not exist.

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

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

 				other system-wide error codes for any other errors.

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

 		*/

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

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

 		@see ContentAccess::TAttribute

 		The following example determines whether the default content object 

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

 		user

 		@code

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

 		RAttributeSet attributeSet;

 		CleanupClosePushL(attributeSet);

 		attributeSet->AddL(EProtected);

 		attributeSet->AddL(ECanView);

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

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

 		if(err == KErrNone && value)

 				{

 				// file is DRM protected

 				}

 		err = attributeSet.GetValue(ECanView, value);

 		if(err == KErrNone && value)

 				{

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

 				}

 		// Finished

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

 		@endcode

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

 		@return Whether the attribute set was updated.

 		@return KErrNone if the attributes were retrieved successfully.

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

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

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

 				other system-wide error codes for any other errors.

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

 		*/

 		IMPORT_C TInt GetAttributeSet(RAttributeSet& aAttributeSet) const;		

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

 		@see ContentAccess::TAttribute

 		The following example determines whether the default content object 

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

 		user

 		@code

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

 		RAttributeSet attributeSet;

 		CleanupClosePushL(attributeSet);

 		attributeSet->AddL(EProtected);

 		attributeSet->AddL(ECanView);

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

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

 		if(err == KErrNone && value)

 				{

 				// file is DRM protected

 				}

 		err = attributeSet.GetValue(ECanView, value);

 		if(err == KErrNone && value)

 				{

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

 				}

 		// Finished

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

 		@endcode

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

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

 		@return Whether that attribute set was updated.

 		@return KErrNone if the attributes were retrieved successfully.

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

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

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

 				other system-wide error codes for any other errors.

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

 		*/

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

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

 		@see ContentAccess::TStringAttribute

 		@code

 		TInt err = KErrNone;

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

 		TBuf <MAX_PATH> previewUri;

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

 		if(err == KErrNone)

 			{

 			DisplayPreview(previewUri);

 			}

 		@endcode

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

 		@param aValue Returns the value of the attribute.

 		@return Whether the attribute value was updated.

 		@return KErrNone if the attribute was retrieved.

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

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

 		@return KErrCANotSupported if the requested attribute does not exist.

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

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

 				other system-wide error codes for any other errors.

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

 		*/

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

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

 		@see ContentAccess::TStringAttribute

 		@code

 		TInt err = KErrNone;

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

 		TBuf <MAX_PATH> previewUri;

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

 		if(err == KErrNone)

 			{

 			DisplayPreview(previewUri);

 			}

 		@endcode

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

 		@param aValue Returns the value of the attribute.

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

 		@return Whether the attribute value was updated.

 		@return KErrNone if the attribute was retrieved.

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

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

 		@return KErrCANotSupported if the requested attribute does not exist.

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

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

 				other system-wide error codes for any other errors.

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

 		*/

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

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

 		@see ContentAccess::TStringAttribute

 		@code

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

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

 		RStringAttributeSet stringAttributeSet;

 		CleanupClosePushL(stringAttributeSet);

 		stringAttributeSet.AddL(EPreviewURI);

 		stringAttributeSet.AddL(ETitle);

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

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

 		TFileName previewUri;		

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

 		if(err == KErrNone)

 			{

 			DisplayPreview(previewUri);

 			}

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

 		@endcode

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

 		@return Whether the attribute set was updated.

 		@return KErrNone if the attributes were retrieved successfully.

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

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

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

 				other system-wide error codes for any other errors.

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

 		*/

 		IMPORT_C TInt GetStringAttributeSet(RStringAttributeSet& aStringAttributeSet) const;

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

 		@see ContentAccess::TStringAttribute

 		@code

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

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

 		RStringAttributeSet stringAttributeSet;

 		CleanupClosePushL(stringAttributeSet);

 		stringAttributeSet.AddL(EPreviewURI);

 		stringAttributeSet.AddL(ETitle);

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

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

 		TFileName previewUri;		

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

 		if(err == KErrNone)

 			{

 			DisplayPreview(previewUri);

 			}

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

 		@endcode

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

 		@param aUniqueId The UniqueId of the container or content. 

 		@return Whether the attribute set was updated.

 		@return KErrNone if the attributes were retrieved successfully.

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

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

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

 				other system-wide error codes for any other errors.

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

 		*/

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

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

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

 		@param aCommand The agent defined command.

 		@param aInputBuffer Non modifyable input data buffer.

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

 		@return The outcome of the agent specific command.

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

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

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

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

 				other system-wide error codes for any other errors.

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

 		*/

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

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

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

 		NB: It is important that the descriptor passed to 

 		aOutputBuffer remains in scope until the request has completed.		

 		@param aCommand The agent defined command.

 		@param aInputBuffer Non modifyable input data buffer.

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

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

 						one of the following error codes:

 						KErrNone if the command was successfully executed.

 						KErrCANotSupported  if the agent does not recognize the command.

 						KErrOverflow if the output buffer supplied is too small.

 						KErrPermissionDenied if the agent does not allow the client 

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

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

 						for any other errors.

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

 		*/

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

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

 		@see ContentAccess::TEventMask

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

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

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

 		*/

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

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

 		@see ContentAccess::TEventMask

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

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

 		@param aUniqueId The UniqueId of the container or content. 						 

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

 		*/

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

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

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

 		@return The outcome of the cancel request.

 		@return KErrNone if the request was cancelled.

 		@return KErrNotFound if there was no matching request outstanding.

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

 		*/

 		IMPORT_C TInt CancelNotifyStatusChange(TRequestStatus& aStatus);

 		/** Cancel a previous notification request

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

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

 		@return The outcome of the cancel request.

 		@return KErrNone if the request was cancelled.

 		@return KErrNotFound if there was no matching request outstanding.

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

 		*/

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

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

 		This request may be handled differently by different agents. 

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

 		download and install the rights in the background.

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

 		if they are interested in the outcome.

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

 						one of the following error codes:

 						KErrNone if the rights request was successful.

 						KErrCANotSupported  if the agent does not allow rights requests.

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

 						or one of the other system-wide error codes 

 						for any other errors.

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

 		*/

 		IMPORT_C void RequestRights(TRequestStatus& aStatus);

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

 		This request may be handled differently by different agents. 

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

 		download and install the rights in the background.

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

 		if they are interested in the outcome.

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

 						one of the following error codes:

 						KErrNone if the rights request was successful.

 						KErrCANotSupported  if the agent does not allow rights requests.

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

 						or one of the other system-wide error codes 

 						for any other errors.

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

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

 		*/

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

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

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

 		@return The result of the cancel rights request.

 		@return KErrNone if the rights request was cancelled.

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

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

 		*/

 		IMPORT_C TInt CancelRequestRights(TRequestStatus& aStatus);

 		/** Cancel a previous RequestRights() request

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

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

 		@return The result of the cancel rights request.

 		@return KErrNone if the rights request was cancelled.

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

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

 		*/

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

 		/** View information associated with the default content object

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

 		by the user.

 		@see ContentAccess::TDisplayInfo

 		@param aInfo The information to display.

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

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

 							or one of the system-wide error codes for 

 							any other errors.

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

 		*/

 		IMPORT_C void DisplayInfoL(TDisplayInfo aInfo) const;

 		/** View information associated with a single content object

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

 		by the user.

 		@see ContentAccess::TDisplayInfo

 		@param aInfo The information to display.

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

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

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

 							or one of the system-wide error codes for 

 							any other errors.

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

 		*/

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

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

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

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

 		CContent.

   		@see ContentAccess::TAgentProperty

 		@param aProperty The property to set.

 		@param aValue The value of the property.

 		@return Whether the property was set.

 		@return KErrNone if the property was set.

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

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

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

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

 		*/

 		IMPORT_C TInt SetProperty(TAgentProperty aProperty, TInt aValue);

 		/** 

 		 Grants read access to the default content object based on 

 		 evaluation of the supplied intent information. 

 		 Note that the intent is simply evaluated and not executed. 

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

 		 ContentAccess::CData::ExecuteIntent(). 

 		 A CData object can be obtained as follows:

 		 @code

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

 		 ...

 		 delete MyData; // when finished accessing plaintext content

 		 @endcode

 		 @see ContentAccess::TIntent

 		 @param aIntent	The intent indicator.

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

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

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

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

 		 @leave KErrCANoRights		No rights exist for the content object.

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

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

 		 @leave KErrAccessDenied	The content is already in use.

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

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

 								errors.		 

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

 		 */

 		IMPORT_C CData* OpenContentL(TIntent aIntent);

 		/** 

 		 Grants read access to the default content object based on 

 		 evaluation of the supplied intent information. 

 		 Note that the intent is simply evaluated and not executed. 

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

 		 ContentAccess::CData::ExecuteIntent(). 

 		 A CData object can be obtained as follows:

 		 @code

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

 		 ...

 		 // when finished accessing plaintext content

 		 CleanupStack::PopAndDestroy(myData); 

 		 @endcode

 		 @see ContentAccess::TIntent

 		 @param aIntent	The intent indicator.

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

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

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

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

 		 @leave KErrCANoRights			No rights exist for the content object.

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

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

 		 @leave KErrAccessDenied		The content is already in use.

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

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

 								errors.		 

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

 		 */

 		IMPORT_C CData* OpenContentLC(TIntent aIntent);

 		/** 

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

 		 supplied intent information. 

 		 Note that the intent is simply evaluated and not executed. 

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

 		 ContentAccess::CData::ExecuteIntent(). 

 		 A CData object can be obtained as follows:

 		 @code

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

 		 ...

 		 delete MyData; // when finished accessing plaintext content

 		 @endcode

 		 @see ContentAccess::TIntent

 		 @param aIntent	The intent indicator.

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

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

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

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

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

 		 @leave KErrCANoRights		No rights exist for the content object.

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

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

 		 @leave KErrAccessDenied	The content is already in use.

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

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

 								errors.		 

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

 		 */

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

 		/** 

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

 		 supplied intent information. 

 		 Note that the intent is simply evaluated and not executed. 

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

 		 ContentAccess::CData::ExecuteIntent(). 

 		 A CData object can be obtained as follows:

 		 @code

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

 		 ...

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

 		 @endcode

 		 @see ContentAccess::TIntent

 		 @param aIntent	The intent indicator.

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

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

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

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

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

 		 @leave KErrCANoRights		No rights exist for the content object.

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

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

 		 @leave KErrAccessDenied	The content is already in use.

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

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

 								errors.		 

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

 		 */

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

 		/** Find out which agent is handling this file

 		@return The agent handling the File

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

 		*/

 		IMPORT_C const TAgent& Agent() const;

 #ifndef REMOVE_CAF1

 		/** Create a CData object for reading the content 

 		@see ContentAccess::TIntent

 		@param aIntent The intended use of the content

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

 		@return A new CData object

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

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

 		@deprecated

 		*/

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

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

 		@return The agent handling the File

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

 		@deprecated 

 		*/

 		IMPORT_C CAttribute* NewAttributeL(TBool aPreloaded);

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

 		@return The agent handling the File

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

 		@deprecated 

 		*/

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

 #endif  // REMOVE_CAF1

 	private:

 		CContent(); 

 		void ConstructL(RFile& aFile); 

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

 	private:	

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

 		CAgentFactory* iAgentFactory;

 		/** 

 		 Agent object used for browsing the contents of a file

 		 */

 		CAgentContent* iAgentContent;

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

 		CVirtualPath* iVirtualPath;

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

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

 		*/

 		TVirtualPathPtr iDefaultVirtualPath;

 		/* Stores the name and UID of the agent

 		*/

 		TAgent iAgent;

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

 		TContentShareMode iShareMode;

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

 		RFile iFile;

 		};

 	} // namespace ContentAccess

 #endif /* __CONTENT_H__ */