/*

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

#define __AGENTINTERFACE_H__

#include <e32base.h>

#include <ecom/ecom.h>

#include <caf/caftypes.h>

#include <caf/streamableptrarray.h>

#include <caf/caferr.h>

class RStringPool;

class RHTTPHeaders;

namespace ContentAccess

{

	class CEmbeddedObject;

	class CSupplierOutputFile;

	class RAttributeSet;

	class RStringAttributeSet;

	class TVirtualPathPtr;

	class CRightsInfo;

	class CVirtualPath;

	class MAgentRightsBase;

	class CImportFile;

	class CMetaDataArray;

	class CDirStreamable;

	/**

	 Defines the agent interface for consumer operations such as 

	 reading and seeking within a content object in a file.

	 @publishedPartner

	 @released

     */

	class CAgentData : public CBase

		{

	public:

		/**

		 Gets the data size in bytes.

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

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

		 @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

		 */

		virtual void DataSizeL(TInt &aSize) = 0;

		/**

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

		 current rights for the data object. 

		 Doing so may cause subsequent reads (or other accesses)

		 to fail. The result of the agent's evaluation

		 of the intent is returned.

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

		 any rights-state such as play counts.

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

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

		 @return KErrNone if the intent is permitted.

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

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

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

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

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

		 @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

		 */

		virtual TInt EvaluateIntent(TIntent aIntent) = 0;

		/**

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

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

		 stateful rights such as play counts where necessary.

  		 Applications should be very careful to use this function correctly.

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

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

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

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

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

		 the file before calling ExecuteIntent. 

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

		 play counts that apply. 

		@param aIntent	The intent indicator.

		@return The result of attempting executing the intent.

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

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

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

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

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

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

		@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 

		*/

		virtual TInt ExecuteIntent(TIntent aIntent) = 0;

		/** 

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

		 descriptor or the end of the content object.

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

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

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

		 through content, the end has been reached when the

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

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

		  				contents are overwritten. On return, its length is set

		 				to the number of bytes read.

		 @return		KErrNone if successful, otherwise another of the

		  				system-wide error codes.

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

		*/

		virtual TInt Read(TDes8& aDes) = 0;

		/**

		 Reads a specified number of bytes of content.

		 @see Read(TDes8& aDes)

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

		  				contents are overwritten. On return, its length is set

		 				to the number of bytes read.

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

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

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

		 @return		KErrNone if successful.

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

		 				one of the other system-wide error codes.

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

		*/

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

		/**

		 Reads content asynchronously.

		 @see Read(TDes8& aDes)

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

		  					existing contents are overwritten. On return,

		 					its length is set to the number of bytes read. 

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

		 					of the following error codes: KErrNone if the data was 

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

							\c caferr.h  or one of the other standard 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 

		*/

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

		/**

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

		 @see Read(TDes8& aDes)

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

		  					existing contents are overwritten. On return,

		 					its length is set to the number of bytes read. 

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

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

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

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

		 					of the following error codes: KErrNone if the data was 

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

							\c caferr.h  or one of the other standard 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 

		*/

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

		/**

		 Cancels asynchronous read.

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

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

		 					this function will not have any effect.

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

		*/

		virtual void ReadCancel(TRequestStatus& aStatus);

		/**

		 Changes or retrieves the location of the file pointer within 

		 the content object

		 There are four seek modes used: 

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

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

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

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

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

		 position relative to the start of the content object.

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

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

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

		 used to retrieve the current file pointer location 

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

		 aPos bytes from the start of the content object

		 @see TSeek

		 @param aMode	Seek mode - controls the destination of the

		  				seek operation.

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

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

		 relative to the end of the file.

		 @return		KErrNone if successful. 

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

		 				of the other system-wide error codes.

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

		*/

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

		/** 

		Allows an application to request the modification of a property 

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

		permit the property to be changed

		@param aProperty The property to set.

		@param aValue The value of the property.

		@return Whether or not 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 

		 */

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

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

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

		@param aValue Used to return the attribute value.

		@return Whether the attribute was updated.

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

		@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 

		*/

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

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

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

		*/

		virtual TInt GetAttributeSet(RAttributeSet& aAttributeSet) = 0;

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

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

		@param aValue Returns the value of the attribute.

		@return Whether the value was updated.

		@return KErrNone if the attribute was retrieved.

		@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 

		*/

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

		/** Used to obtain a set of string attributes 

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

		@return Whether the string 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. 

		*/

		virtual TInt GetStringAttributeSet(RStringAttributeSet& aStringAttributeSet)=0;

		/**  

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

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

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

		 @see Read(TDes8& aDes)

		 @param aPos		Position of first byte to be read. 

		 					This is an offset from the start of the file. 

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

		  					existing contents are overwritten. On return,

		 					its length is set to the number of bytes read. 

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

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

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

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

		 					of the following error codes: KErrNone if the data was 

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

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

							error codes for any other errors.

		 @return KErrNone if the async read request was successfully submitted.

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

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

		*/

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

		};

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

	within a file

	@publishedPartner

	@released

	*/

	class CAgentContent : public CBase

		{

	public:

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

 		*/

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

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

 		*/

		virtual  TInt CloseContainer() = 0;

		/** 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.

		@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 

 		*/

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

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

		are of the specified type

		@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 

 		*/

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

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

  		@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 

		*/

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

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

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

		*/

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

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

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

		*/

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

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

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

		*/

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

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

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

		*/

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

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

		*/

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

		/** 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: No assumption should be made about the scope of the descriptor 

		passed to aInputBuffer for asynchronous IPC.

		@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 

		*/

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

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

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

		passed to aUniqueId for asynchronous IPC.