/*

* 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;