sl@0: /*
sl@0: * Copyright (c) 2003-2009 Nokia Corporation and/or its subsidiary(-ies).
sl@0: * All rights reserved.
sl@0: * This component and the accompanying materials are made available
sl@0: * under the terms of the License "Eclipse Public License v1.0"
sl@0: * which accompanies this distribution, and is available
sl@0: * at the URL "http://www.eclipse.org/legal/epl-v10.html".
sl@0: *
sl@0: * Initial Contributors:
sl@0: * Nokia Corporation - initial contribution.
sl@0: *
sl@0: * Contributors:
sl@0: *
sl@0: * Description: 
sl@0: *
sl@0: */
sl@0: 
sl@0: 
sl@0: /**
sl@0:  @file
sl@0:  @publishedPartner
sl@0:  @released
sl@0: */
sl@0: 
sl@0: #ifndef __AGENTINTERFACE_H__
sl@0: #define __AGENTINTERFACE_H__
sl@0: 
sl@0: #include <e32base.h>
sl@0: #include <ecom/ecom.h>
sl@0: 
sl@0: #include <caf/caftypes.h>
sl@0: #include <caf/streamableptrarray.h>
sl@0: #include <caf/caferr.h>
sl@0: 
sl@0: class RStringPool;
sl@0: class RHTTPHeaders;
sl@0: 
sl@0: namespace ContentAccess
sl@0: {
sl@0: 	class CEmbeddedObject;
sl@0: 	class CSupplierOutputFile;
sl@0: 	class RAttributeSet;
sl@0: 	class RStringAttributeSet;
sl@0: 	class TVirtualPathPtr;
sl@0: 	class CRightsInfo;
sl@0: 	class CVirtualPath;
sl@0: 	class MAgentRightsBase;
sl@0: 	class CImportFile;
sl@0: 	class CMetaDataArray;
sl@0: 	class CDirStreamable;
sl@0: 
sl@0: 	/**
sl@0: 	 Defines the agent interface for consumer operations such as 
sl@0: 	 reading and seeking within a content object in a file.
sl@0: 
sl@0: 	 @publishedPartner
sl@0: 	 @released
sl@0:      */
sl@0: 	class CAgentData : public CBase
sl@0: 		{
sl@0: 	public:
sl@0: 		/**
sl@0: 		 Gets the data size in bytes.
sl@0: 		 
sl@0: 		 @param aSize	On return this will contain the size of the plaintext data in bytes.
sl@0: 		 @leave KErrCASizeNotDetermined	Size could not be determined by the managing agent.
sl@0: 		 @leave ...		One of the other CAF error codes defined in \c caferr.h  or one of the 
sl@0: 						system-wide error codes for any other errors.		 
sl@0: 		 @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted
sl@0: 		 */
sl@0: 		virtual void DataSizeL(TInt &aSize) = 0;
sl@0: 		
sl@0: #ifdef SYMBIAN_ENABLE_64_BIT_FILE_SERVER_API
sl@0: 		/**
sl@0: 		 This is the 64bit version of DataSizeL. Implementing this function should take advantage of 64bit
sl@0: 		 file system and use RFile::Size64(TInt64 &). If this function is not implemented, fallback to 32bit 
sl@0: 		 DataSizeL will be provided by CAF automatically.
sl@0: 		 
sl@0: 		 @see DataSizeL(TInt &aSize)
sl@0: 		*/
sl@0: 		IMPORT_C virtual void DataSize64L(TInt64 &aSize);
sl@0: #endif //SYMBIAN_ENABLE_64_BIT_FILE_SERVER_API
sl@0: 		
sl@0: 		/**
sl@0: 		 Allows a client to verify that the intent is supported by the
sl@0: 		 current rights for the data object. 
sl@0: 		 
sl@0: 		 Doing so may cause subsequent reads (or other accesses)
sl@0: 		 to fail. The result of the agent's evaluation
sl@0: 		 of the intent is returned.
sl@0: 		 
sl@0: 		 @note Since the intent is only evaluated the agent will not decrement 
sl@0: 		 any rights-state such as play counts.
sl@0: 		  
sl@0: 		 @param aIntent	The intended way the content will be used.
sl@0: 		 @return Whether rights exist allowing the content to be used for this intent.
sl@0: 		 @return KErrNone if the intent is permitted.
sl@0: 		 @return KErrNoRights if no rights exist for the specified content object.
sl@0: 		 @return KErrCANoPermission	if rights exist but the specified intent is not permitted.
sl@0: 		 @return KErrCAPendingRights if the rights have not yet arrived but are expected soon.
sl@0: 		 @return KErrNoPermission if rights exist but none permit the specified intent.
sl@0: 		 @return KErrPermissionDenied if the client is not allowed to use this content object.
sl@0: 		 @return Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 
sl@0: 				other system-wide error codes for any other errors.
sl@0: 
sl@0: 		 @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted
sl@0: 		 */
sl@0: 		virtual TInt EvaluateIntent(TIntent aIntent) = 0;
sl@0: 		
sl@0: 		/**
sl@0: 		 Execute intent allows the application to signal it is about to carry out
sl@0: 		 the specified intent on DRM protected content.The agent will decrement applicable 
sl@0: 		 stateful rights such as play counts where necessary.
sl@0: 
sl@0:   		 Applications should be very careful to use this function correctly.
sl@0: 		 @li If ExecuteIntent() is never called stateful rights will never be decremented. Users will be able to use the content forever
sl@0: 		 @li If ExecuteIntent() is called too often stateful rights may be consumed prematurely. 
sl@0: 
sl@0: 		 Usually it would be best to call ExecuteIntent immediately before the content 
sl@0: 		 is displayed or the instant playback begins. ExecuteIntent should not be considered a 
sl@0: 		 prerequisite for calling the Read functions. It is valid for an application to read from 
sl@0: 		 the file before calling ExecuteIntent. 
sl@0: 
sl@0: 		 @note Since rights are executed here the agent will decrement any rights-state such as 
sl@0: 		 play counts that apply. 
sl@0: 		 
sl@0: 		@param aIntent	The intent indicator.
sl@0: 		@return The result of attempting executing the intent.
sl@0: 		@return KErrNone if the intent is permitted and stateful rights may have been decremented.
sl@0: 		@return KErrNoRights if no rights exist for the specified content object.
sl@0: 		@return KErrCANoPermission	if rights exist but the specified intent is not permitted.
sl@0: 		@return KErrCAPendingRights if the rights have not yet arrived but are expected soon.
sl@0: 		@return KErrNoPermission if rights exist but none permit the specified intent.
sl@0: 		@return KErrPermissionDenied if the client is not allowed to use this content object.
sl@0: 		@return Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the
sl@0: 				other system-wide error codes for any other errors.
sl@0: 		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted 
sl@0: 		*/
sl@0: 		virtual TInt ExecuteIntent(TIntent aIntent) = 0;
sl@0: 
sl@0: 		/** 
sl@0: 		 Reads from a content object up to the maximum length of the
sl@0: 		 descriptor or the end of the content object.
sl@0: 		 	
sl@0: 		 When an attempt is made to read beyond the end of the content,
sl@0: 		 no error is returned. The descriptor’s length is set to the
sl@0: 		 number of bytes that were read into it. Therefore, when reading
sl@0: 		 through content, the end has been reached when the
sl@0: 		 descriptor length (given by TDesC::Length()) is zero.
sl@0: 		 
sl@0: 		 @param aDes	Descriptor into which binary data is read. Any existing
sl@0: 		  				contents are overwritten. On return, its length is set
sl@0: 		 				to the number of bytes read.
sl@0: 		 @return		KErrNone if successful, otherwise another of the
sl@0: 		  				system-wide error codes.
sl@0: 		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted 
sl@0: 		*/
sl@0: 		virtual TInt Read(TDes8& aDes) = 0;
sl@0: 
sl@0: 		/**
sl@0: 		 Reads a specified number of bytes of content.
sl@0: 		  
sl@0: 		 @see Read(TDes8& aDes)
sl@0: 		 		 
sl@0: 		 @param aDes	Descriptor into which binary data is read. Any existing
sl@0: 		  				contents are overwritten. On return, its length is set
sl@0: 		 				to the number of bytes read.
sl@0: 		 @param aLength		The number of bytes to read from the file,
sl@0: 		 					or to the end of the file, whichever is encountered first. 
sl@0: 		 					The length of the buffer is set to the number of bytes actually read.
sl@0: 		 @return		KErrNone if successful.
sl@0: 		 @return		Otherwise one of the CAF error codes defined in \c caferr.h  or 
sl@0: 		 				one of the other system-wide error codes.
sl@0: 		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted 
sl@0: 		*/
sl@0: 		virtual TInt Read(TDes8& aDes, TInt aLength) = 0;
sl@0: 
sl@0: 		/**
sl@0: 		 Reads content asynchronously.
sl@0: 		 
sl@0: 		 @see Read(TDes8& aDes)
sl@0: 		 
sl@0: 		 @param aDes 		Descriptor into which binary data is read. Any
sl@0: 		  					existing contents are overwritten. On return,
sl@0: 		 					its length is set to the number of bytes read. 
sl@0: 		 @param aStatus		Asynchronous request status. On completion this will contain one 
sl@0: 		 					of the following error codes: KErrNone if the data was 
sl@0: 							successfully read. Otherwise one of the CAF error codes defined in 
sl@0: 							\c caferr.h  or one of the other standard system-wide
sl@0: 							error codes for any other errors.
sl@0: 		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted 
sl@0: 		*/
sl@0: 		virtual void Read(TDes8& aDes, TRequestStatus& aStatus) = 0;
sl@0: 
sl@0: 		/**
sl@0: 		 Reads content asynchronously (up to a specified maximum number of bytes)
sl@0: 		 
sl@0: 		 @see Read(TDes8& aDes)
sl@0: 		 
sl@0: 		 @param aDes 		Descriptor into which binary data is read. Any
sl@0: 		  					existing contents are overwritten. On return,
sl@0: 		 					its length is set to the number of bytes read. 
sl@0: 		 @param aLength		The number of bytes to read from the file,
sl@0: 		 					or to the end of the file, whichever is encountered first. 
sl@0: 		 					The length of the buffer is set to the number of bytes actually read.
sl@0: 		 @param aStatus		Asynchronous request status. On completion this will contain one 
sl@0: 		 					of the following error codes: KErrNone if the data was 
sl@0: 							successfully read. Otherwise one of the CAF error codes defined in 
sl@0: 							\c caferr.h  or one of the other standard system-wide
sl@0: 							error codes for any other errors.
sl@0: 		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted 
sl@0: 		*/
sl@0: 		virtual void Read(TDes8& aDes, TInt aLength, TRequestStatus& aStatus) = 0;
sl@0: 		
sl@0: 		/**
sl@0: 		 Cancels asynchronous read.
sl@0: 		 
sl@0: 		 @param aStatus		Asynchronous request status. This parameter should have been supplied earlier to
sl@0: 		 					an asynchronous Read call. If it has not been previously supplied to a Read call,
sl@0: 		 					this function will not have any effect.
sl@0: 		 @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted 
sl@0: 		*/
sl@0: 		IMPORT_C virtual void ReadCancel(TRequestStatus& aStatus);
sl@0: 
sl@0: 		/**
sl@0: 		 Changes or retrieves the location of the file pointer within 
sl@0: 		 the content object
sl@0: 		 
sl@0: 		 There are four seek modes used: 
sl@0: 		 
sl@0: 		 @li ESeekStart - Sets the file pointer aPos bytes from the start of the 
sl@0: 		 content object.  aPos is not modified by the call to Seek()
sl@0: 		 @li ESeekEnd - Sets the file pointer aPos bytes from the end of the 
sl@0: 		 content object. The aPos parameter supplied should be zero or negative 
sl@0: 		 when using ESeekEnd. Upon completion aPos is updated with the current 
sl@0: 		 position relative to the start of the content object.
sl@0: 		 @li ESeekCurrent - Moves the file pointer aPos bytes from the current 
sl@0: 		 position. Upon completion aPos is updated with the new position relative 
sl@0: 		 to the start of the content object. Suppling a zero value for the aPos Parameter can be
sl@0: 		 used to retrieve the current file pointer location 
sl@0: 		 @li ESeekAddress Sets the aPos parameter to the address of the byte 
sl@0: 		 aPos bytes from the start of the content object
sl@0: 
sl@0: 		 @see TSeek
sl@0: 		 
sl@0: 		 @param aMode	Seek mode - controls the destination of the
sl@0: 		  				seek operation.
sl@0: 		  
sl@0: 		 @param aPos	Offset from either the start, end or current position depending upon 
sl@0: 		 the seek mode. Negative offsets are used to seek before the current position or
sl@0: 		 relative to the end of the file.
sl@0: 		 
sl@0: 		 @return		KErrNone if successful. 
sl@0: 		 @return		Otherwise one of the CAF error codes defined in \c caferr.h  or one 
sl@0: 		 				of the other system-wide error codes.
sl@0: 		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted 
sl@0: 		*/
sl@0: 		virtual TInt Seek(TSeek aMode, TInt& aPos) = 0;
sl@0: 
sl@0: #ifdef SYMBIAN_ENABLE_64_BIT_FILE_SERVER_API
sl@0: 		/**
sl@0: 		  This is the 64bit version of Seek. Implementing this function should take advantage of 64bit
sl@0: 		  file system and use RFile::Seek64(TSeek, TInt64 &). If this function is not implemented, fallback to 32bit 
sl@0: 		  Seek will be provided by CAF automatically.
sl@0: 		  
sl@0: 		  @see Seek(TSeek aMode, TInt& aPos)
sl@0: 		*/
sl@0: 		IMPORT_C virtual TInt Seek64(TSeek aMode, TInt64& aPos);
sl@0: #endif //SYMBIAN_ENABLE_64_BIT_FILE_SERVER_API
sl@0: 		
sl@0: 		/** 
sl@0: 		Allows an application to request the modification of a property 
sl@0: 		within the agent handling this content. The agent may or may not
sl@0: 		permit the property to be changed
sl@0: 		 	
sl@0: 		@param aProperty The property to set.
sl@0: 		@param aValue The value of the property.
sl@0: 		@return Whether or not the property was set.
sl@0: 		@return KErrNone if the property was set.
sl@0: 		@return KErrCANotSupported if the agent does not support the property or value.
sl@0: 		@return KErrAccessDenied if the agent does not permit the property to be changed.
sl@0: 		@return KErrPermissionDenied if the application does not have the necessary capability to change the property.
sl@0: 		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted 
sl@0: 		 */
sl@0: 		virtual TInt SetProperty(TAgentProperty aProperty, TInt aValue) = 0;
sl@0: 
sl@0: 		/**  Get the value of an attribute for this content object
sl@0:  
sl@0: 		@param aAttribute The attribute to query, from ContentAccess::TAttribute.
sl@0: 		@param aValue Used to return the attribute value.
sl@0: 		@return Whether the attribute was updated.
sl@0: 		@return KErrNone if the value of the attribute was updated.
sl@0: 		@return KErrCANotSupported if the requested attribute does not exist.
sl@0: 		@return KErrPermissionDenied if the access to the protected content is not permitted by the CAF Agent.
sl@0: 		@return Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 
sl@0: 				other system-wide error codes for any other errors.
sl@0: 		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted 
sl@0: 		*/
sl@0: 		virtual TInt GetAttribute(TInt aAttribute, TInt& aValue)=0;
sl@0: 
sl@0: 		/** Get a set of attributes from a content object
sl@0: 
sl@0: 		@param aAttributeSet The set of attributes to query and update.
sl@0: 		@return Whether the attribute set was updated.
sl@0: 		@return KErrNone if the attributes were retrieved successfully.
sl@0: 		@return KErrPermissionDenied if the access to the protected content is not permitted by the CAF Agent.
sl@0: 		@return Otherwise one of the CAF error codes defined in \c caferr.h  or one of the 
sl@0: 				other system-wide error codes for any other errors.
sl@0: 		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted 				
sl@0: 		*/
sl@0: 		virtual TInt GetAttributeSet(RAttributeSet& aAttributeSet) = 0;
sl@0: 
sl@0: 		/**  Get text string attributes or meta-data for this content object
sl@0: 
sl@0: 		@param aAttribute The attribute to query, from ContentAccess::TStringAttribute.
sl@0: 		@param aValue Returns the value of the attribute.
sl@0: 		@return Whether the value was updated.
sl@0: 		@return KErrNone if the attribute was retrieved.
sl@0: 		@return KErrOverflow if the buffer was not large enough to return the result.
sl@0: 		@return KErrCANotSupported if the requested attribute does not exist.
sl@0: 		@return KErrPermissionDenied if the access to the protected content is not permitted by the CAF Agent.
sl@0: 		@return Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 
sl@0: 				other system-wide error codes for any other errors.				 
sl@0: 		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted 
sl@0: 		*/
sl@0: 		virtual TInt GetStringAttribute(TInt aAttribute, TDes& aValue)=0;
sl@0: 
sl@0: 	
sl@0: 		/** Used to obtain a set of string attributes 
sl@0: 
sl@0: 		@param aStringAttributeSet The set of attributes to query and update.
sl@0: 		@return Whether the string attribute set was updated.
sl@0: 		@return KErrNone if the attributes were retrieved successfully.
sl@0: 		@return KErrNotFound if the default content object was not found.
sl@0: 		@return KErrPermissionDenied if the access to the protected content is not permitted by the CAF Agent.
sl@0: 		@return Otherwise one of the CAF error codes defined in \c caferr.h  or one of the 
sl@0: 				other system-wide error codes for any other errors.				 
sl@0: 		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted. 
sl@0: 		*/
sl@0: 		virtual TInt GetStringAttributeSet(RStringAttributeSet& aStringAttributeSet)=0;
sl@0: 		
sl@0: 		/**  
sl@0: 		 Reads content asynchronously. The data is read from a specified offset 
sl@0: 		 up to a specified number of bytes or until the end of the content object 
sl@0: 		 is reached. The data is read into the descriptor buffer supplied.
sl@0: 		 
sl@0: 		 @see Read(TDes8& aDes)
sl@0: 		 
sl@0: 		 @param aPos		Position of first byte to be read. 
sl@0: 		 					This is an offset from the start of the file. 
sl@0: 		 @param aDes 		Descriptor into which binary data is read. Any
sl@0: 		  					existing contents are overwritten. On return,
sl@0: 		 					its length is set to the number of bytes read. 
sl@0: 		 @param aLength		The number of bytes to read from the file,
sl@0: 		 					or to the end of the file, whichever is encountered first. 
sl@0: 		 					The length of the buffer is set to the number of bytes actually read.
sl@0: 		 @param aStatus		Asynchronous request status. On completion this will contain one 
sl@0: 		 					of the following error codes: KErrNone if the data was 
sl@0: 							successfully read. Otherwise one of the CAF error codes defined in 
sl@0: 							\c caferr.h  or one of the other standard system-wide
sl@0: 							error codes for any other errors.
sl@0: 		 @return KErrNone if the async read request was successfully submitted.
sl@0: 		 @return KErrCANotSupported if the agent does not support this operation.
sl@0: 		 @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted 
sl@0: 		*/
sl@0: 		IMPORT_C virtual TInt Read(TInt aPos, TDes8& aDes, TInt aLength, TRequestStatus& aStatus);
sl@0: 		
sl@0: #ifdef SYMBIAN_ENABLE_64_BIT_FILE_SERVER_API
sl@0: 		/**  
sl@0: 		 This is the 64bit version of CAgentData::Read(TInt aPos, TDes8& aDes, TInt aLength, TRequestStatus& aStatus)
sl@0: 		 Implementing this function should take advantage of 64bit file system and use RFile::Seek64(TSeek, TInt64 &) to get to
sl@0: 		 the position in file specified by aPos. If this function is not implemented, fallback to 32bit 
sl@0: 		 Read will be provided by CAF automatically. 
sl@0: 		 
sl@0: 		 @see Read(TInt aPos, TDes8& aDes, TInt aLength, TRequestStatus& aStatus)
sl@0: 		*/
sl@0: 		IMPORT_C virtual TInt Read64(TInt64 aPos, TDes8& aDes, TInt aLength, TRequestStatus& aStatus);
sl@0: #endif //SYMBIAN_ENABLE_64_BIT_FILE_SERVER_API
sl@0: 
sl@0: #ifdef SYMBIAN_ENABLE_SDP_WMDRM_SUPPORT
sl@0: 		/**
sl@0: 		Decrypts the encrypted input data packet.Default implementation of this method returns KErrCANotSupported.
sl@0: 		
sl@0: 		@param aEncryptedInputDataPacket	Buffer descriptor containing the encrypted data packet supplied by client application. 
sl@0: 		@param aDecryptedOutputDataPacket	Buffer descriptor supplied by the client application into which the decrypted data is written.
sl@0: 											The length of this descriptor must be equal to or greater than the input packet.
sl@0: 		@return								KErrNone if successful or KErrInsuffcientDataPacketLength, if a part of input data packet
sl@0: 											is provided for decryption.Otherwise one of the CAF error codes defined in \c caferr.h  or 
sl@0: 		 									one of the other system-wide error.
sl@0: 		@capability 						DRM Access to DRM protected content is not permitted for processes without DRM capability.
sl@0: 											Access to unprotected content is unrestricted.
sl@0: 		*/
sl@0: 		IMPORT_C virtual TInt Read(const TDesC8& aEncryptedInputDataPacket, TDes8& aDecryptedOutputDataPacket);
sl@0: 		
sl@0: 		
sl@0: 		/**
sl@0: 		Decrypts the encrypted input data packet asynchronously.Default implementation of this method returns KErrCANotSupported.
sl@0: 	
sl@0: 		@param aEncryptedInputDataPacket	Buffer descriptor containing the encrypted data packet supplied by client application. 
sl@0: 		@param aDecryptedOutputDataPacket	Buffer descriptor supplied by the client application into which the decrypted data is written.
sl@0: 											The length of this descriptor must be equal to or greater than the input packet.
sl@0: 		@param aStatus						Asynchronous request status. On completion this will contain one of the following error codes:
sl@0: 											KErrNone if the data packet was successfully decrypted or KErrInsuffcientDataPacketLength, if a part of input data packet
sl@0: 											is provided for decryption.Otherwise one of the CAF error codes defined in \c caferr.h  or 
sl@0: 		 									one of the other system-wide error codes.
sl@0: 		@capability 						DRM Access to DRM protected content is not permitted for processes without DRM capability.
sl@0: 										    Access to unprotected content is unrestricted. 
sl@0: 		*/
sl@0: 		IMPORT_C virtual void Read(const TDesC8& aEncryptedInputDataPacket, TDes8& aDecryptedOutputDataPacket, TRequestStatus& aStatus);
sl@0: #endif //SYMBIAN_ENABLE_SDP_WMDRM_SUPPORT
sl@0: 		};
sl@0: 
sl@0: 	/**	Defines the agent interface allowing clients to browse the objects 
sl@0: 	within a file
sl@0: 
sl@0: 	@publishedPartner
sl@0: 	@released
sl@0: 	*/
sl@0: 	class CAgentContent : public CBase
sl@0: 		{
sl@0: 	public:
sl@0:  		/** Open a Container object within the file.
sl@0:  		
sl@0:  		Allows an application to access the content objects and 
sl@0:  		any nested container objects within the specified container.
sl@0:   		
sl@0:  		@param aUniqueId The container object's unique ID.
sl@0: 		@return Whether the container was opened.
sl@0:  		@return KErrNone if the container was opened successfully.
sl@0:  		@return KErrNotFound if the container does not exist.
sl@0: 		@return KErrPermissionDenied if the access to the protected content is not permitted by the CAF Agent.		 
sl@0: 		@return Otherwise one of the CAF error codes defined in \c caferr.h  or one of the 
sl@0: 				other system-wide error codes for any other errors.
sl@0: 		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted 
sl@0:  		*/
sl@0: 		virtual TInt OpenContainer(const TDesC& aUniqueId) = 0;
sl@0: 
sl@0:  		/** Close the current container object and go back to previous enclosing
sl@0:  		container within the file.
sl@0:  		
sl@0:  		Allows an application to access the content objects and 
sl@0:  		any nested container objects within parent container
sl@0:   		
sl@0: 		@return Whether the container was closed.
sl@0:   		@return KErrNone if the container was closed.
sl@0:   		@return KErrNotFound if there is no enclosing container.
sl@0:   		@return KErrPermissionDenied if the access to the protected content is not permitted by the CAF Agent.		 		
sl@0:   		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted 
sl@0:  		*/
sl@0: 		virtual  TInt CloseContainer() = 0;
sl@0: 
sl@0: 		/** List all the embedded container objects and content objects within the 
sl@0: 		current container
sl@0:  		 		
sl@0: 		The UniqueId() member of CEmbeddedObject can be used to refer directly to 
sl@0: 		a particular object within the file.
sl@0: 
sl@0: 		@param aArray The array to be populated with the embedded objects. 
sl@0: 		@leave KErrPermissionDenied if the access to the protected content is not permitted by the CAF Agent.		 
sl@0: 		@leave ...			One of the CAF error codes defined in \c caferr.h  or one of the 
sl@0: 							other system-wide error codes for any other errors.
sl@0:   		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted 
sl@0:  		*/
sl@0: 		virtual void GetEmbeddedObjectsL(RStreamablePtrArray<CEmbeddedObject>& aArray) = 0;
sl@0: 		
sl@0: 		/** List all the embedded objects within the current container that
sl@0: 		are of the specified type
sl@0:  		 		
sl@0: 		@param aArray The array to be populated with the embedded objects. 
sl@0: 		@param aType The type of objects to list.
sl@0: 		@leave KErrPermissionDenied If the access to the protected content is not permitted by the CAF Agent.		 
sl@0: 		@leave ...			One of the CAF error codes defined in \c caferr.h  or one of the 
sl@0: 							other system-wide error codes for any other errors.
sl@0:   		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted 
sl@0:  		*/
sl@0: 		virtual void GetEmbeddedObjectsL(RStreamablePtrArray<CEmbeddedObject>& aArray, TEmbeddedType aType) = 0;
sl@0: 
sl@0: 		/** Search the current container for content objects with a particular mime type
sl@0: 
sl@0:   		@param aArray The array to store the results of the search. The agent will add CEmbeddedObject objects to the supplied array.
sl@0: 		@param aMimeType The mime type to search for.
sl@0: 		@param aRecursive ETrue to search inside containers embedded within the current container, EFalse to search only the current container.
sl@0: 		@return The result of the search.
sl@0: 		@return KErrNone if the search was successful, even if no content objects were found.
sl@0: 		@return KErrPermissionDenied if the access to the protected content is not permitted by the CAF Agent.		 
sl@0: 		@return Otherwise one of the CAF error codes defined in \c caferr.h  or one of the 
sl@0: 				other system-wide error codes for any other errors.
sl@0: 		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted 
sl@0: 		*/
sl@0: 		virtual TInt Search(RStreamablePtrArray<CEmbeddedObject>& aArray, const TDesC8& aMimeType, TBool aRecursive) = 0;
sl@0: 		
sl@0: 		/**  Get an attribute for an object within the file
sl@0: 	
sl@0: 		@param aAttribute The attribute to query, from ContentAccess::TAttribute.
sl@0: 		@param aValue Used to return the attribute value.
sl@0: 		@param aUniqueId The UniqueId of the object within the file.
sl@0: 		@return Whether the attribute value was updated.
sl@0: 		@return KErrNone if the value of the attribute was updated.
sl@0: 		@return KErrNotFound if the object with the given UniqueId was not found.
sl@0: 		@return KErrCANotSupported if the requested attribute does not exist.
sl@0: 		@return KErrPermissionDenied if the access to the protected content is not permitted by the CAF Agent.	 
sl@0: 		@return Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 
sl@0: 				other system-wide error codes for any other errors.
sl@0: 		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted. 
sl@0: 		*/
sl@0: 		virtual TInt GetAttribute(TInt aAttribute, TInt& aValue, const TDesC& aUniqueId) = 0;
sl@0: 
sl@0: 		/** Get a set of attributes for an object within the file
sl@0: 
sl@0: 		@param aAttributeSet The set of attributes to query and update.
sl@0: 		@param aUniqueId The unique ID of the object within the file.
sl@0: 		@return Whether that attribute set was updated.
sl@0: 		@return KErrNone if the attributes were retrieved successfully.
sl@0: 		@return KErrNotFound if the default content object was not found.
sl@0: 		@return KErrPermissionDenied if the access to the protected content is not permitted by the CAF Agent.		 
sl@0: 		@return Otherwise one of the CAF error codes defined in \c caferr.h  or one of the 
sl@0: 				other system-wide error codes for any other errors.
sl@0: 		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted. 
sl@0: 		*/
sl@0: 		virtual TInt GetAttributeSet(RAttributeSet& aAttributeSet, const TDesC& aUniqueId) = 0;
sl@0: 
sl@0: 		/**  Get text string attributes or meta-data for an object within the file
sl@0: 
sl@0: 		@param aAttribute The attribute to query, from ContentAccess::TStringAttribute.
sl@0: 		@param aValue Returns the value of the attribute.
sl@0: 		@param aUniqueId The UniqueId of the object within the file. 
sl@0: 		@return Whether the attribute value was updated.
sl@0: 		@return KErrNone if the attribute was retrieved.
sl@0: 		@return KErrNotFound if the object with the given UniqueId was not found.
sl@0: 		@return KErrOverflow if the buffer was not large enough to return the result.
sl@0: 		@return KErrCANotSupported if the requested attribute does not exist.
sl@0: 		@return KErrPermissionDenied if the access to the protected content is not permitted by the CAF Agent.	 
sl@0: 		@return Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 
sl@0: 				other system-wide error codes for any other errors.
sl@0: 		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted. 
sl@0: 		*/
sl@0: 		virtual TInt GetStringAttribute(TInt aAttribute, TDes& aValue, const TDesC& aUniqueId) = 0;
sl@0: 
sl@0: 		/** Used to obtain a set of string attributes for an object within the file
sl@0: 
sl@0: 		@param aStringAttributeSet The set of attributes to query and update.
sl@0: 		@param aUniqueId The UniqueId of the container or content. 
sl@0: 		@return Whether the attribute set was updated.
sl@0: 		@return KErrNone if the attributes were retrieved successfully.
sl@0: 		@return KErrNotFound if the object with the given UniqueId was not found.
sl@0: 		@return KErrPermissionDenied if the access to the protected content is not permitted by the CAF Agent.		 
sl@0: 		@return Otherwise one of the CAF error codes defined in \c caferr.h  or one of the 
sl@0: 				other system-wide error codes for any other errors.
sl@0: 		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted. 
sl@0: 		*/
sl@0: 		virtual TInt GetStringAttributeSet(RStringAttributeSet& aStringAttributeSet, const TDesC& aUniqueId)=0;
sl@0: 
sl@0: 		/** Allows extended synchronous calls to the CAF agent handling this file
sl@0: 		
sl@0: 		Applications familiar with the agent can pass objects in and out using serialization.
sl@0: 
sl@0: 		@param aCommand The agent defined command.
sl@0: 		@param aInputBuffer Non modifyable input data buffer.
sl@0: 		@param aOutputBuffer Modifyable output buffer to hold the result of the command.
sl@0: 		@return The outcome of the agent specific command.
sl@0: 		@return KErrCANotSupported if the agent does not recognize the command.
sl@0: 		@return KErrOverflow if the output buffer supplied is too small.
sl@0: 		@return KErrPermissionDenied if the agent does not allow the client to execute the command.
sl@0: 		@return Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 
sl@0: 				other system-wide error codes for any other errors.
sl@0: 		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted 
sl@0: 		*/
sl@0: 		virtual TInt AgentSpecificCommand(TInt aCommand, const TDesC8& aInputBuffer, TDes8& aOutputBuffer) = 0;
sl@0: 
sl@0: 		/** Allows extended synchronous calls to the CAF agent handling this file.
sl@0: 		Applications familiar with the agent can pass objects in and out using serialization.
sl@0: 		NB: No assumption should be made about the scope of the descriptor 
sl@0: 		passed to aInputBuffer for asynchronous IPC.
sl@0: 
sl@0: 		@param aCommand The agent defined command.
sl@0: 		@param aInputBuffer Non modifyable input data buffer.
sl@0: 		@param aOutputBuffer Modifyable output buffer to hold the result of the command.
sl@0: 		@param aStatus Asynchronous request status. On completion this will contain 
sl@0: 						one of the following error codes:
sl@0: 						KErrNone if the command was successfully executed.
sl@0: 						KErrCANotSupported  if the agent does not recognize the command.
sl@0: 						KErrOverflow if the output buffer supplied is too small.
sl@0: 						KErrPermissionDenied if the agent does not allow the client 
sl@0: 						to execute the command. Otherwise one of the other CAF error codes defined 
sl@0: 						in \c caferr.h  or one of the other system-wide error codes 
sl@0: 						for any other errors.
sl@0: 		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted 
sl@0: 		*/
sl@0: 		virtual void AgentSpecificCommand(TInt aCommand, const TDesC8& aInputBuffer, TDes8& aOutputBuffer, TRequestStatus& aStatus) = 0;
sl@0: 
sl@0: 		/** Request notification for an event for an object within the file.
sl@0: 		NB: No assumption should be made about the scope of the descriptor 
sl@0: 		passed to aUniqueId for asynchronous IPC.
sl@0: 
sl@0: 		@param aMask Bitmask of events the caller is interested in.
sl@0: 		@param aStatus The TRequestStatus object to complete if the event occurs.
sl@0: 		@param aUniqueId The UniqueId of the container or content. 
sl@0: 		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted 
sl@0: 		*/
sl@0: 		virtual void NotifyStatusChange(TEventMask aMask, TRequestStatus& aStatus, const TDesC& aUniqueId) = 0;
sl@0: 		
sl@0: 		/** Cancel a previous notification request
sl@0: 
sl@0: 		@param aStatus The TRequestStatus supplied in the call to NotifyStatusChange().
sl@0: 		@param aUniqueId The UniqueId of the content object within the file.
sl@0: 		@return The outcome of the cancel request.
sl@0: 		@return KErrNone if the request was cancelled.
sl@0: 		@return KErrNotFound if there was no matching request outstanding.
sl@0: 		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted 
sl@0: 		*/
sl@0: 		virtual TInt CancelNotifyStatusChange(TRequestStatus& aStatus, const TDesC& aUniqueId) = 0;
sl@0: 
sl@0: 		/** Request the agent to obtain rights for a protected content object.
sl@0: 		NB: No assumption should be made about the scope of the descriptor 
sl@0: 		passed to aUniqueId for asynchronous IPC.
sl@0: 
sl@0: 		This request may be handled differently by different agents. 
sl@0: 		Some agents may open a browser and direct the user to a URL. Others may 
sl@0: 		download and install the rights in the background.
sl@0: 
sl@0: 		The call should not block execution, applications can wait for a notification 
sl@0: 		if they are interested in the outcome. 
sl@0: 		
sl@0: 		If a rights request completes sucessfully it does not necessarily mean rights 
sl@0: 		are available. It just means the request is complete.
sl@0: 
sl@0: 		@param aStatus Asynchronous request status. On completion this will contain 
sl@0: 						one of the following error codes:
sl@0: 						KErrNone if the rights request was successful.
sl@0: 						KErrCANotSupported  if the agent does not allow rights requests.
sl@0: 						Otherwise one of the other CAF error codes defined in \c caferr.h  
sl@0: 						or one of the other system-wide error codes 
sl@0: 						for any other errors.
sl@0: 
sl@0: 		@param aUniqueId The unique id of the object within the file.
sl@0: 		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted.		
sl@0: 		*/
sl@0: 		virtual void RequestRights(TRequestStatus& aStatus, const TDesC& aUniqueId) = 0; 
sl@0: 
sl@0: 		/** Cancel a previous RequestRights() request
sl@0: 
sl@0: 		@param aStatus The TRequestStatus that was supplied to the RequestRights() function.
sl@0: 		@param aUniqueId The objects Unique Id that was supplied to the RequestRights() function.
sl@0: 		@return The result of the cancel rights request.
sl@0: 		@return KErrNone if the rights request was cancelled.
sl@0: 		@return KErrNotFound if there was no matching rights request outstanding.
sl@0: 		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted 
sl@0: 		*/
sl@0: 		virtual TInt CancelRequestRights(TRequestStatus& aStatus, const TDesC& aUniqueId) = 0;
sl@0: 
sl@0: 		/** View information associated with a single content object
sl@0: 		
sl@0: 		This call blocks execution and only returns once the display is dismissed 
sl@0: 		by the user.
sl@0: 
sl@0: 		@param aInfo The information to display.
sl@0: 		@param aUniqueId The unique id of the object within the file.
sl@0: 		@leave KErrCANotSupported if information cannot be displayed or does not exist.
sl@0: 		@leave ...			One of the other CAF error codes defined in \c caferr.h  
sl@0: 							or one of the system-wide error codes for 
sl@0: 							any other errors.
sl@0: 		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted. 
sl@0: 		*/
sl@0: 		virtual void DisplayInfoL(TDisplayInfo aInfo, const TDesC& aUniqueId) = 0;
sl@0: 
sl@0: 		/** 
sl@0: 		Allows an application to request the modification of a property 
sl@0: 		within the agent handling this content. The agent may or may not
sl@0: 		permit the property to be changed
sl@0: 		 	
sl@0: 		@param aProperty The property to set.
sl@0: 		@param aValue The value of the property.
sl@0: 		@return Whether the property was set.
sl@0: 		@return KErrNone if the property was set.
sl@0: 		@return KErrCANotSupported if the agent does not support the property or value.
sl@0: 		@return KErrAccessDenied if the agent does not permit the property to be changed.
sl@0: 		@return KErrPermissionDenied if the application does not have the necessary capability to change the property.
sl@0: 		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted 
sl@0: 		*/
sl@0: 		virtual TInt SetProperty(TAgentProperty aProperty, TInt aValue) = 0;
sl@0: 		
sl@0: 		};
sl@0: 
sl@0: 	/**
sl@0: 	 Defines the interface for importing files into a Content access agent. 
sl@0: 
sl@0: 	The agent should treat the import as a transaction and either import the
sl@0: 	entire file or revert to the state before the import if the import is cancelled.
sl@0: 	
sl@0: 	The client cancels an import by deleting the CAgentImportFile object 
sl@0: 	before WriteDataComplete() is called. 
sl@0: 	 
sl@0: 	 @publishedPartner
sl@0: 	 @released
sl@0: 	 */
sl@0: 	class CAgentImportFile : public CBase
sl@0: 		{
sl@0: 	public:
sl@0: 
sl@0: 		/** Writes a block of data from a file to the agent
sl@0: 		
sl@0: 		@param aData The block of data.
sl@0: 		@return	The result of the write operation.
sl@0: 		@return KErrNone if the data was written successfully.
sl@0: 		@return	KErrCANewFileHandleRequired if the agent requires the client to provide a new file handle before proceeding. The agent must save its state and continue processing when the new handle is supplied by ContinueWithNewOutputFile().
sl@0: 		@return KErrNotReady if the agent was not expecting WriteData() to be called at this point.
sl@0: 		@return Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 
sl@0: 				other system-wide error codes for any other errors.
sl@0: 		*/
sl@0: 		virtual TInt WriteData(const TDesC8& aData)=0;
sl@0: 
sl@0: 		/** Signals to the agent that the entire file has now been transferred to the agent.
sl@0: 		
sl@0: 		@return The result of the write operation. 
sl@0: 		@return KErrNone if the data was written successfully.
sl@0: 		@return	KErrCANewFileHandleRequired if the agent requires the client to provide a new file handle before proceeding. The agent must save its state and continue processing when the new handle is supplied by ContinueWithNewOutputFile().
sl@0: 		@return KErrNotReady if the agent was not expecting WriteDataComplete() to be called at this point.
sl@0: 		@return Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 
sl@0: 				other system-wide error codes for any other errors.		
sl@0: 		*/
sl@0: 		virtual TInt WriteDataComplete()=0;
sl@0: 
sl@0: 		/** Asynchronously writes a block of data from a file the agent
sl@0: 		 
sl@0: 		Notifies the client when the write operation is complete.
sl@0: 		
sl@0: 		@param aData 	The block of data.
sl@0: 		@param aStatus 	Asynchronous request status. On completion this will 
sl@0: 						contain one of the following error codes: KErrNone if the data was written successfully. 
sl@0: 						KErrCANewFileHandleRequired if the agent requires a new 
sl@0: 						file handle before proceeding - the agent must save its 
sl@0: 						state and continue processing when the new handle 
sl@0: 						is supplied by ContinueWithNewOutputFile().
sl@0: 						KErrNotReady if the agent was not expecting WriteDataComplete() 
sl@0: 						to be called at this point. Otherwise one of the other CAF error codes 
sl@0: 						defined in \c caferr.h  or one of the other standard system-wide 
sl@0: 						error codes for any other errors.
sl@0: 		*/
sl@0: 		virtual void WriteData(const TDesC8& aData, TRequestStatus& aStatus)=0;
sl@0: 
sl@0: 		/** Signals to the agent that the entire file has now been transferred to the agent
sl@0: 		
sl@0: 		Notifies the client when any final processing operation is complete.
sl@0: 		
sl@0: 		@param aStatus 	Asynchronous request status. On completion this will 
sl@0: 						contain one of the following error codes: KErrNone if the data was written successfully. 
sl@0: 						KErrCANewFileHandleRequired if the agent requires a new 
sl@0: 						file handle before proceeding - the agent must save its 
sl@0: 						state and continue processing when the new handle 
sl@0: 						is supplied by ContinueWithNewOutputFile().
sl@0: 						KErrNotReady if the agent was not expecting WriteDataComplete() 
sl@0: 						to be called at this point. Otherwise one of the other CAF error codes 
sl@0: 						defined in \c caferr.h  or one of the other standard system-wide 
sl@0: 						error codes for any other errors.
sl@0: 		*/
sl@0: 		virtual void WriteDataComplete(TRequestStatus& aStatus)=0;
sl@0: 
sl@0: 		/** Gets the number of output files produced so far. 
sl@0: 		@return The number of output files.
sl@0: 		*/
sl@0: 		virtual TInt OutputFileCountL() const = 0;
sl@0: 
sl@0: 		/** Return information about an output file generated by the import operation. 
sl@0: 		
sl@0: 		 It is possible that the output file does not have the same name 
sl@0: 		 as the one suggested at the beginning of the import. An agent may
sl@0: 		 need to use a particular file extension or a particular name.
sl@0: 
sl@0: 		The agent may decide not to store the output file in the output directory 
sl@0: 		suggested at the start of the import. eg. it may store the file in its private 
sl@0: 		server directory.
sl@0: 
sl@0: 		The output files may only appear in this array after the WriteDataComplete() 
sl@0: 		function has been called. 
sl@0: 
sl@0: 		@param aIndex The zero-based index of the file (must be less than the value returned by OutputFileCountL().
sl@0: 		@return The CSupplierOutputFile for this object.
sl@0: 		*/
sl@0: 		virtual CSupplierOutputFile& OutputFileL(TInt aIndex) = 0;
sl@0: 
sl@0: 		/** Retrieve the import status
sl@0: 
sl@0: 		Used to indicate non fatal problems encountered during the import operation.
sl@0: 		Provides feedback to the client in case any problems are encountered.
sl@0: 
sl@0: 		The client can then decide whether or not to continue the import.
sl@0: 		 
sl@0: 		@return	The state of the import operation.
sl@0: 		*/
sl@0: 		virtual TImportStatus GetImportStatus() const = 0;
sl@0: 
sl@0: 		
sl@0: 		/** Get the agents suggestion for the file extension of the output file required by the agent
sl@0: 
sl@0: 		This function should only be called when the agent has returned KErrCANewFileHandleRequired from
sl@0: 		WriteData() or WriteDataComplete().
sl@0: 
sl@0: 		The extension must include the dot '.' character.
sl@0: 
sl@0: 		@param aFileExtension On completion this will contain the appropriate file extension.
sl@0: 		@return The result of the request for a file extension.
sl@0: 		@return KErrNone if the agent populated aFileExtension with the correct file extension.
sl@0: 		@return KErrNotReady if the agent is not waiting for another file handle to be provided.
sl@0: 		@return KErrUnknown if the agent does not know what extension should be used.
sl@0: 		*/
sl@0: 		virtual TInt GetSuggestedOutputFileExtension(TDes& aFileExtension) = 0;
sl@0: 
sl@0: 		/** Get the agents suggestion for the file name (with extension) of the output file required by the agent
sl@0: 
sl@0: 		This function should only be called when the agent has returned KErrCANewFileHandleRequired from
sl@0: 		WriteData() or WriteDataComplete().
sl@0: 
sl@0: 		The file name is of the form filename.extension.
sl@0: 
sl@0: 		@param aFileName On completion this will contain the appropriate filename.
sl@0: 		@return KErrNone if the agent populated aFileName with the correct file name.
sl@0: 		@return KErrNotReady if the agent is not waiting for another file handle to be provided.
sl@0: 		@return KErrUnknown if the agent does not know what file name should be used.
sl@0: 		*/
sl@0: 		virtual TInt GetSuggestedOutputFileName(TDes& aFileName) = 0;
sl@0: 
sl@0: 		/** Continue the last write operation with a new file handle as requested by the agent
sl@0: 
sl@0: 		@param aFile A new file handle opened with write permission.
sl@0: 		@param aFileName The name of the file handle that has  been supplied. This is used by the agent when creating CSupplierOutputFile objects. It should include the full path and filename in order to be consistent with files generated by the agent.
sl@0: 		@return The result of the continuing write operation.
sl@0: 		@return KErrNone if the WriteData() or WriteDataComplete() operation is now complete.
sl@0: 		@return KErrCANewFileHandleRequired if the agent requires a new 
sl@0: 						file handle before proceeding - the agent must save its 
sl@0: 						state and continue processing when the new handle 
sl@0: 						is supplied by ContinueWithNewOutputFile().
sl@0: 		@return Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 
sl@0: 				other system-wide error codes for any other errors.		
sl@0: 		*/
sl@0: 		virtual TInt ContinueWithNewOutputFile(RFile& aFile, const TDesC& aFileName) = 0;
sl@0: 
sl@0: 		/** Continue the last write operation with a new file handle and return the result asynchronously.
sl@0: 
sl@0: 		@param aFile A new file handle opened with write permission
sl@0: 		@param aFileName The name of the file handle that has  been supplied. This is used by the agent when creating CSupplierOutputFile objects. It should include the full path and filename in order to be consistent with files generated by the agent
sl@0: 		
sl@0: 		@param aStatus 	Asynchronous request status. On completion this will 
sl@0: 						contain one of the following error codes: KErrNone if the 
sl@0: 						WriteData() or WriteDataComplete() operation is now complete.
sl@0: 						KErrCANewFileHandleRequired if the agent requires a new 
sl@0: 						file handle before proceeding - the agent must save its 
sl@0: 						state and continue processing when the new handle 
sl@0: 						is supplied by ContinueWithNewOutputFile(). Otherwise one of the 
sl@0: 						other CAF error codes defined in \c caferr.h  or one of the 
sl@0: 						other system-wide error codes for any other errors.
sl@0: 		*/
sl@0: 		virtual void ContinueWithNewOutputFile(RFile& aFile, const TDesC& aFileName, TRequestStatus& aStatus) = 0;
sl@0: 		
sl@0: 		/** Cancel an outstanding asynchronous WriteData() request.
sl@0: 		*/
sl@0: 		IMPORT_C virtual void Cancel();
sl@0: 		
sl@0: 		/** Retrieve the content MIME type based on available data
sl@0: 		
sl@0: 		This function should only be called when the agent has returned KErrCANewFileHandleRequired from WriteData()
sl@0: 		If the agent cannot return a content MIME type, the importer should assume that no content type
sl@0: 		will be available until after the import session has been finished 
sl@0: 
sl@0: 		@param aContentMime On return this will contain the appropriate content MIME type.
sl@0: 		@return The result of the request for a content MIME type.
sl@0: 		@return ETrue if the agent populated aContentMime with the correct content MIME type.
sl@0: 		@return EFalse if the agent cannot return the content MIME type (for example, there 
sl@0: 					is not enough data, or the content is multi-part)
sl@0: 		*/
sl@0: 		IMPORT_C virtual TBool ContentMimeTypeL(TDes8& aContentMime);
sl@0: 				
sl@0: 		};
sl@0: 
sl@0: 	/**
sl@0: 	 Defines the agent interface for manager operations. 
sl@0: 	 
sl@0: 	 The CAgentManager is not related to any particular content object but 
sl@0: 	 used to manage files and settings belonging to this agent
sl@0: 	 
sl@0: 	All operations performed by the agent manager should be implemented in a 
sl@0: 	transactional manner by either completing or reverting to the state before
sl@0: 	the function was called.
sl@0: 	 
sl@0:  	 @publishedPartner
sl@0: 	 @released
sl@0: 	 */	
sl@0: 	class CAgentManager : public CBase
sl@0: 		{
sl@0: 	public:
sl@0: 		/** 
sl@0: 		 Delete a file belonging to this agent
sl@0: 
sl@0: 		 The agent implementation may delete rights that were associated with 
sl@0: 		 the content at the same time. If an agent does delete rights at the same
sl@0: 		 time as the content it should display a confirmation dialog that makes it
sl@0: 		 clear to the user the rights they paid for will be also deleted. 
sl@0: 
sl@0: 		 Execution will be blocked until any dialog displayed is complete. Applications 
sl@0: 		 can request to disable the agents user interface using the SetProperty() command
sl@0: 		 
sl@0: 		 Access to the agents private directory is permitted at the 
sl@0: 		 agents discretion.
sl@0: 
sl@0: 		 @param aFileName The full pathname of the file to delete.
sl@0: 		 @return The outcome of the delete operation.
sl@0: 		 @return KErrNone if the file was deleted successfully.
sl@0: 		 @return KErrCancel if the user selects cancel in an agent supplied confirmation screen.
sl@0: 		 @return KErrAccessDenied if the agent does not allow the file to be deleted.
sl@0: 		 @return KErrCANotSupported if the agent does not support file deletion
sl@0: 		 @return KErrPermissionDenied if the client does not have the necessary capabilities to delete the file.
sl@0: 		@return Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 
sl@0: 				other system-wide error codes for any other errors.
sl@0: 		 @capability DRM Deleting DRM protected content is not permitted for processes without DRM capability. 
sl@0: 		 */
sl@0: 		virtual TInt DeleteFile(const TDesC &aFileName) = 0;
sl@0: 
sl@0: 		/**
sl@0: 		Make a copy of the content file (eg to removable media) belonging to this agent
sl@0: 
sl@0: 		Access to the agents private directory is permitted at the 
sl@0: 		agents discretion.
sl@0: 
sl@0:   		@param aSource The full pathname of the source file.
sl@0: 		@param aDestination The full pathname of the destination file.
sl@0: 		@return The outcome of the copy operation.
sl@0: 		@return KErrNone if the file was copied successfully.
sl@0: 		@return KErrAccessDenied if the agent does not allow the file to be copied.
sl@0: 		@return KErrCANotSupported if the agent does not support file copying.
sl@0: 		@return KErrPermissionDenied if the client does not have the necessary capabilities to copy the file.
sl@0: 		@return Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 
sl@0: 				other system-wide error codes for any other errors.
sl@0:   		@capability DRM Copying DRM protected files is not permitted for processes without DRM capability. Copying unprotected files is permitted
sl@0: 		*/
sl@0: 		virtual TInt CopyFile(const TDesC& aSource, const TDesC& aDestination) = 0;
sl@0: 
sl@0: 		/**
sl@0: 		Rename or move the content file (eg to removable media) belonging to this agent
sl@0: 
sl@0: 		Access to the agent private directories is permitted at the 
sl@0: 		agents discretion.
sl@0: 
sl@0: 		@param aSource The full pathname of the source file.
sl@0: 		@param aDestination The full pathname of the destination file.
sl@0: 		@return The outcome of the Rename operation.
sl@0: 		@return KErrNone if the file was moved or renamed successfully.
sl@0: 		@return KErrAccessDenied if the agent does not allow the file to be moved or renamed.
sl@0: 		@return KErrCANotSupported if the agent does not support file renaming.
sl@0: 		@return KErrPermissionDenied if the client does not have the necessary capabilities to move or rename the file.
sl@0: 		@return Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 
sl@0: 				other system-wide error codes for any other errors.
sl@0:   		@capability DRM Moving DRM protected files is not permitted for processes without DRM capability. Moving unprotected files is permitted
sl@0: 		*/
sl@0: 		virtual TInt RenameFile(const TDesC& aSource, const TDesC& aDestination) = 0;
sl@0: 
sl@0: 		/** Create a directory
sl@0: 
sl@0: 		This function can be used to create a directory within in the agent's 
sl@0: 		private directory. Access to the agents private directory is permitted at the 
sl@0: 		agents discretion. 
sl@0: 
sl@0: 		@param aPath The full pathname of the directory to create.
sl@0: 		@return The outcome of the MkDir operation.
sl@0: 		@return KErrNone if the directory was created successfully.
sl@0: 		@return KErrAccessDenied if the agent does not allow the directory to be created.
sl@0: 		@return KErrCANotSupported if the agent does not support directory creation.
sl@0: 		@return KErrPermissionDenied if the client does not have the necessary capabilities to create directories.
sl@0: 		@return Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 
sl@0: 				other system-wide error codes for any other errors.
sl@0: 		
sl@0: 		@capability DRM Required when attempting to access an agents private directory
sl@0: 		*/
sl@0: 		virtual TInt MkDir(const TDesC& aPath) = 0;
sl@0: 
sl@0: 		/** Create all directories in the given path if they do not exist
sl@0: 
sl@0: 		This function can be used to create directories within in the agent's 
sl@0: 		private directory. Access to the agents private directory is permitted at the 
sl@0: 		agents discretion. 
sl@0: 		
sl@0: 		@param aPath The full pathname of the directory to create.
sl@0: 		@return The outcome of the MkDirAll operation.
sl@0: 		@return KErrNone if the directory was created successfully.
sl@0: 		@return KErrAccessDenied if the agent does not allow the directory to be created.
sl@0: 		@return KErrPermissionDenied if the client does not have the necessary capabilities to create directories.
sl@0: 		@return Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 
sl@0: 				other system-wide error codes for any other errors.
sl@0: 		@capability DRM Required when attempting to access an agents private directory
sl@0: 		*/
sl@0: 		virtual TInt MkDirAll(const TDesC& aPath) = 0;
sl@0: 
sl@0: 		/** Remove a directory
sl@0: 
sl@0: 		This function can be used to remove a directory from within the agent's 
sl@0: 		private directory. Access to the agents private directory is permitted 
sl@0: 		at the agents discretion. 
sl@0: 		
sl@0: 		@param aPath The full pathname of the directory to remove.
sl@0: 		@return The outcome of the RmDir operation.
sl@0: 		@return KErrNone if the directory was removed successfully.
sl@0: 		@return KErrAccessDenied if the agent does not allow the directory to be removed.
sl@0: 		@return KErrCANotSupported if the agent does not support directory removal.
sl@0: 		@return KErrPermissionDenied if the client does not have the necessary capabilities to remove directories.
sl@0: 		@return Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 
sl@0: 				other system-wide error codes for any other errors.
sl@0: 		@capability DRM Required when attempting to access an agents private directory
sl@0: 		*/
sl@0: 		virtual TInt RmDir(const TDesC& aPath) = 0;
sl@0: 
sl@0: 		/**  Gets a filtered list of a directory's contents. 
sl@0: 
sl@0: 		The bitmask determines which file and directory entry types should be listed. The sort key determines the order in which they are listed.
sl@0: 
sl@0: 		Notes:
sl@0: 		-# If sorting by UID (as indicated when the ESortByUid bit is OR'ed with the sort key), then UID information will be included in the listing whether or not KEntryAttAllowUid is specified in aEntryAttMask.
sl@0: 		-# The function sets aFileList to NULL, and then allocates memory for it before appending entries to the list. Therefore, aFileList should have no memory allocated to it before this function is called, otherwise this memory will become orphaned.
sl@0: 		-# The caller of this function is responsible for deleting aFileList after the function has returned.
sl@0: 
sl@0: 
sl@0: 		This function can be used to list the contents of the agent's 
sl@0: 		private directory. Access to the agents private directory is permitted at 
sl@0: 		the agents discretion. 
sl@0: 		
sl@0: 		Agents can just return KErrCANotSupported if they do not wish to publish their
sl@0: 		private directory. Alternatively they can just populate the CDir object
sl@0: 		with the entries they wish to show.
sl@0: 	
sl@0:   		@param aName The name of the directory for which a listing is required. Wildcards may be used to specify particular files.
sl@0: 		@param aEntryAttMask Bitmask indicating the attributes of interest. Only files and directories whose attributes match those specified here can be included in the listing. For more information, see KEntryAttMatchMask and the other directory entry details. Also see KEntryAttNormal and the other file or directory attributes 
sl@0: 		@param aEntrySortKey The sort key. This is a set of flags indicating the order in which the entries are to be sorted. These flags are defined by TEntryKey. 
sl@0: 		@param aEntryList On return contains a filtered list of directory and file entries.
sl@0: 		@return The outcome of the GetDir operation.
sl@0: 		@return KErrNone if the directory contents were listed successfully.
sl@0: 		@return KErrCANotSupported if the agent does not allow clients to view its private directory.
sl@0: 		@return KErrPermissionDenied if the process does not have the correct capabilities to view the directory.
sl@0: 		@return Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 
sl@0: 				other system-wide error codes for any other errors.
sl@0: 		@capability DRM Required when attempting to access an agents private directory
sl@0: 		*/
sl@0: 		virtual TInt GetDir(const TDesC& aName,TUint aEntryAttMask,TUint aEntrySortKey, CDir*& aEntryList) const = 0;
sl@0: 
sl@0: 		/**  Gets a filtered list of the directory and file entries contained in a directory and a list of the directory entries only
sl@0: 
sl@0: 		The bitmask determines which file and directory entry types should be listed in aFileList. The contents of the second list, aDirList are not affected by the bitmask; it returns all directory entries contained in directory aName. The sort key determines the order in which both lists are sorted.
sl@0: 
sl@0: 		Notes:
sl@0: 		-# If sorting by UID (as indicated when the ESortByUid bit is OR'ed with the sort key), then UID information will be included in the listing whether or not KEntryAttAllowUid is specified in aEntryAttMask.
sl@0: 		-# The function sets both aFileList and aDirList to NULL, and then allocates memory to them before appending entries to the lists. Therefore, aFileList and aDirList should have no memory allocated to them before this function is called, otherwise the allocated memory will become orphaned.
sl@0: 		-# The caller of this function is responsible for deleting aFileList and aDirList after the function has returned.
sl@0: 
sl@0: 		This function can be used to list the contents of the agent's 
sl@0: 		private directory. Access to the agents private directory is permitted at 
sl@0: 		the agents discretion. 
sl@0: 
sl@0: 		Agents can just return KErrCANotSupported if they do not wish to publish their
sl@0: 		private directory. Alternatively they can just populate the CDir object
sl@0: 		with the entries they wish to show.
sl@0: 
sl@0: 		@param aName The name of the directory for which a listing is required. Wildcards may be used to specify particular files. 
sl@0: 		@param aEntryAttMask Bitmask indicating the attributes of interest. Only files and directories whose attributes match those specified here can be included in aFileList. aDirList is unaffected by this mask. For more information, see KEntryAttMatchMask and the other directory entry details. Also see KEntryAttNormal and the other file or directory attributes.
sl@0: 		@param aEntrySortKey The sort key. This is a set of flags indicating the order in which the entries in both lists are to be sorted. These flags are defined by TEntryKey. 
sl@0: 		@param aEntryList On return contains a filtered list of directory and file entries. 
sl@0: 		@param aDirList On return contains a filtered list of directory entries only.
sl@0: 		@return The outcome of the GetDir operation.
sl@0: 		@return KErrNone The directory contents were listed successfully.
sl@0: 		@return KErrCANotSupported The agent does not allow clients to view its private directory.
sl@0: 		@return KErrPermissionDenied If the process does not have the correct capabilities to view the directory.
sl@0: 		@return Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 
sl@0: 				other system-wide error codes for any other errors.
sl@0: 		@capability DRM Required when attempting to access an agents private directory
sl@0: 		*/
sl@0: 		virtual TInt GetDir(const TDesC& aName,TUint aEntryAttMask,TUint aEntrySortKey, CDir*& aEntryList,CDir*& aDirList) const = 0;
sl@0: 
sl@0: 		/**  Gets a filtered list of a directory's contents by UID
sl@0: 
sl@0: 		The aUidType parameter determines which file entry types should be listed. The sort key determines the order in which they are listed.
sl@0: 
sl@0: 		Notes:
sl@0: 		-# The function sets aFileList to NULL, and then allocates memory for it before appending entries to the list. Therefore, aFileList should have no memory allocated to it before this function is called, otherwise this memory will become orphaned.
sl@0: 		-# The caller of this function is responsible for deleting aFileList after the function has returned.
sl@0: 
sl@0: 		This function can be used to list the contents of the agent's 
sl@0: 		private directory. Access to the agents private directory is permitted at 
sl@0: 		the agents discretion. 
sl@0: 
sl@0: 		Agents can just return KErrCANotSupported if they do not wish to publish their
sl@0: 		private directory. Alternatively they can just populate the CDir object
sl@0: 		with the entries they wish to show.
sl@0: 
sl@0: 		@param aName The name of the directory for which a listing is required. Wildcards may be used to specify particular files. 
sl@0: 		@param aEntryUid Only those files whose UIDs match those specified within this UID type will be included in the file list. Any, or all, of the three UIDs within the UID type may be omitted. Any UID which is omitted acts in a similar manner to a wildcard character, matching to all UIDs. 
sl@0: 		@param aEntrySortKey The sort key. This is a set of flags indicating the order in which the entries are to be sorted. These flags are defined by TEntryKey.
sl@0: 		@param aFileList On return contains a filtered list of directory and file entries.
sl@0: 		@return The outcome of the GetDir operation.
sl@0: 		@return KErrNone The directory contents were listed successfully.
sl@0: 		@return KErrCANotSupported The agent does not allow clients to view its private directory.
sl@0: 		@return KErrPermissionDenied If the process does not have the correct capabilities to view the directory.
sl@0: 		@return Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 
sl@0: 				other system-wide error codes for any other errors.
sl@0: 		@capability DRM Required when attempting to access an agents private directory
sl@0: 		*/
sl@0: 		virtual TInt GetDir(const TDesC& aName,const TUidType& aEntryUid,TUint aEntrySortKey, CDir*& aFileList) const = 0;
sl@0: 		
sl@0: 		/**  Get an attribute from a content object
sl@0: 	
sl@0: 		@param aAttribute The attribute to retrieve, from ContentAccess::TAttribute.
sl@0: 		@param aValue Used to return the value of the attribute.
sl@0: 		@param aVirtualPath The content object whose attributes are to be queried.
sl@0: 		@return Whether the attribute value was updated.
sl@0: 		@return KErrNone if the attribute value was updated.
sl@0: 		@return KErrNotFound if the URI or the object with the given UniqueId inside the file was not found.
sl@0: 		@return KErrCANotSupported if the requested attribute is not supported for this content object.
sl@0: 		@return Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 
sl@0: 				other system-wide error codes for any other errors.
sl@0: 		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted. 
sl@0: 		*/
sl@0: 		virtual TInt GetAttribute(TInt aAttribute, TInt& aValue, const TVirtualPathPtr& aVirtualPath) = 0;
sl@0: 
sl@0: 		/**  Get a content's attribute from a file specified by file handle. Can be used when the source file is in the client's private directory.
sl@0: 	
sl@0: 		@param aAttribute The attribute to retrieve, from ContentAccess::TAttribute.
sl@0: 		@param aValue Used to return the value of the attribute.
sl@0: 		@param aFile The file handle for the file containing the content object.
sl@0: 		@param aUniqueId The unique id of the content object.
sl@0: 		@return Whether the attribute value was updated.
sl@0: 		@return KErrNone if the attribute value was updated.
sl@0: 		@return KErrNotFound if the URI or the object with the given UniqueId inside the file was not found.
sl@0: 		@return KErrCANotSupported if the feature or the requested attribute is not supported for this content object.
sl@0: 		@return Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 
sl@0: 				other system-wide error codes for any other errors.
sl@0: 		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted. 
sl@0: 		*/
sl@0: 		IMPORT_C virtual TInt GetAttribute(TInt aAttribute, TInt& aValue, RFile& aFile, const TDesC& aUniqueId);
sl@0: 		
sl@0: 		/** Get a set of attributes from a content object
sl@0: 
sl@0: 		@param aAttributeSet The set of attributes to query and update.
sl@0: 		@param aVirtualPath The content object to retrieve attributes from.
sl@0: 		@return Whether the attribute set was updated.
sl@0: 		@return KErrNone if the attribute set was updated successfully.
sl@0: 		@return KErrNotFound if the content object was not found.
sl@0: 		@return Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 
sl@0: 				other system-wide error codes for any other errors.
sl@0: 		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted. 
sl@0: 		*/
sl@0: 		virtual TInt GetAttributeSet(RAttributeSet& aAttributeSet, const TVirtualPathPtr& aVirtualPath) = 0;
sl@0: 		
sl@0: 		/** Get a content's set of attributes from a file specified by file handle. Can be used when the source file is in the client's private directory.
sl@0: 
sl@0: 		@param aAttributeSet The set of attributes to query and update.
sl@0: 		@param aFile The file handle for the file containing the content object.
sl@0: 		@param aUniqueId The unique id of the content object.
sl@0: 		@return Whether the attribute set was updated.
sl@0: 		@return KErrNone if the attribute set was updated successfully.
sl@0: 		@return KErrNotFound if the content object was not found.
sl@0: 		@return KErrCANotSupported if the feature not supported.
sl@0: 		@return Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 
sl@0: 				other system-wide error codes for any other errors.
sl@0: 		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted. 
sl@0: 		*/
sl@0: 		IMPORT_C virtual TInt GetAttributeSet(RAttributeSet& aAttributeSet, RFile& aFile, const TDesC& aUniqueId);	
sl@0: 
sl@0: 		/**  Get text string attributes or meta-data from the file 
sl@0: 
sl@0: 		@param aAttribute The attribute to retrieve, from ContentAccess::TStringAttribute.
sl@0: 		@param aValue Used to return the value of the attribute.
sl@0: 		@param aVirtualPath The content object whose attributes are to be retrieved.
sl@0: 		@return Whether the value was updated.
sl@0: 		@return KErrNone if the attribute was retrieved successfully.
sl@0: 		@return KErrNotFound if the content object does not exist.
sl@0: 		@return KErrCANotSupported if the requested attribute does not apply to this content object.
sl@0: 		@return KErrOverflow if the buffer was not large enough to return the result.
sl@0: 		@return Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 
sl@0: 				other system-wide error codes for any other errors.
sl@0: 		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted. 
sl@0: 		*/
sl@0: 		virtual TInt GetStringAttribute(TInt aAttribute, TDes& aValue, const TVirtualPathPtr& aVirtualPath) = 0;
sl@0: 
sl@0: 		/**  Get a content's text string attribute from a file specified by file handle. Can be used when the source file is in the client's private directory.
sl@0: 	
sl@0: 		@param aAttribute The attribute to retrieve, from ContentAccess::TAttribute.
sl@0: 		@param aValue Used to return the value of the attribute.
sl@0: 		@param aFile The file handle for the file containing the content object.
sl@0: 		@param aUniqueId The unique id of the content object whose attributes are to be retrieved.
sl@0: 		@return Whether the attribute value was updated.
sl@0: 		@return KErrNone if the attribute value was updated.
sl@0: 		@return KErrNotFound if the content object does not exist.
sl@0: 		@return KErrCANotSupported if the feature or the requested attribute is not supported for this content object.
sl@0: 		@return KErrOverflow if the buffer was not large enough to return the result.
sl@0: 		@return Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 
sl@0: 				other system-wide error codes for any other errors.
sl@0: 		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted. 
sl@0: 		*/		
sl@0: 		IMPORT_C virtual TInt GetStringAttribute(TInt aAttribute, TDes& aValue, RFile& aFile, const TDesC& aUniqueId);
sl@0: 
sl@0: 		/** Used to obtain a set of string attributes 
sl@0: 
sl@0: 		@param aStringAttributeSet The set of attributes to query and update.
sl@0: 		@param aVirtualPath The content object whose attributes are to be retrieved.
sl@0: 		@return Whether the string attribute set was updated.
sl@0: 		@return KErrNone if the attribute set was updated successfully.
sl@0: 		@return KErrNotFound if the object with the given virtual path was not found.
sl@0: 		@return Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 
sl@0: 				other system-wide error codes for any other errors.
sl@0: 		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted. 
sl@0: 		*/
sl@0: 		virtual TInt GetStringAttributeSet(RStringAttributeSet& aStringAttributeSet, const TVirtualPathPtr& aVirtualPath) = 0;
sl@0: 
sl@0: 		/** Get a content's set of string attributes from a file specified by file handle. Can be used when the source file is in the client's private directory.
sl@0: 
sl@0: 		@param aStringAttributeSet The set of attributes to query and update.
sl@0: 		@param aFile The file handle for the file containing the content object.
sl@0: 		@param aUniqueId The unique id of the content object whose attributes are to be retrieved	
sl@0: 		@return Whether the string attribute set was updated.
sl@0: 		@return KErrNone if the attribute set was updated successfully.
sl@0: 		@return KErrNotFound if the object with the given virtual path was not found.
sl@0: 		@return KErrCANotSupported if the feature not supported.
sl@0: 		@return Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 
sl@0: 				other system-wide error codes for any other errors.
sl@0: 		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted. 
sl@0: 		*/
sl@0: 		IMPORT_C virtual TInt GetStringAttributeSet(RStringAttributeSet& aStringAttributeSet, RFile& aFile, const TDesC& aUniqueId);
sl@0: 				
sl@0: 		/** Notify the caller when the status of a DRM protected content object changes.
sl@0: 		NB: No assumption should be made about the scope of the descriptor 
sl@0: 		passed to aURI for asynchronous IPC.
sl@0: 
sl@0: 		@param aURI The location of the file.
sl@0: 		@param aMask Bitmask of events the caller is interested in.
sl@0: 		@param aStatus The TRequestStatus object to complete if the event occurs, or KErrCANotSupported if the agent does not support asynchronous notifications.
sl@0: 		@capability DRM Deleting DRM protected content is not permitted for processes without DRM capability. 
sl@0: 		*/
sl@0: 		virtual void NotifyStatusChange(const TDesC& aURI, TEventMask aMask, TRequestStatus& aStatus) = 0;
sl@0: 
sl@0: 		/** Cancel a previous notification request
sl@0: 		@param aURI The URI supplied in the call to NotifyStatusChange().
sl@0: 		@param aStatus The TRequestStatus supplied in the call to NotifyStatusChange().
sl@0: 		@return The outcome of the cancel request.
sl@0: 		@return KErrNone if the notification was cancelled.
sl@0: 		@return KErrNotFound if there was no matching request outstanding.
sl@0: 		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted 
sl@0: 		*/
sl@0: 		virtual TInt CancelNotifyStatusChange(const TDesC& aURI, TRequestStatus& aStatus) = 0;
sl@0: 
sl@0: 		/** 
sl@0: 		Allows an application to request the modification of a property 
sl@0: 		within the agent. The agent may or may not permit the property to be changed
sl@0: 		 	
sl@0: 		@param aProperty The property to set.
sl@0: 		@param aValue The value of the property.
sl@0: 		@return The outcome of the set property command.
sl@0: 		@return KErrNone if the property was set by all agents.
sl@0: 		@return KErrCANotSupported if one of the agent does not support the property or value.
sl@0: 		@return KErrAccessDenied if one of the agents does not permit the property to be changed.
sl@0: 		@return KErrPermissionDenied if the application does not have the necessary capability to change the property.
sl@0: 		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted 
sl@0: 		*/
sl@0: 		virtual TInt SetProperty(TAgentProperty aProperty, TInt aValue) = 0;
sl@0: 
sl@0: 		/** View information associated with a single content object
sl@0: 		
sl@0: 		This call blocks execution and only returns once the display is dismissed 
sl@0: 		by the user.
sl@0: 
sl@0: 		@param aInfo The information to display.
sl@0: 		@param aVirtualPath The content object.
sl@0: 		@leave KErrCANotSupported if agent cannot display the requested information.
sl@0: 		@leave ...		One of the other CAF error codes defined in \c caferr.h  
sl@0: 		 				or one of the system-wide error codes 
sl@0: 						for any other errors.		
sl@0: 		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted. 
sl@0: 		*/
sl@0: 		virtual void DisplayInfoL(TDisplayInfo aInfo, const TVirtualPathPtr& aVirtualPath) = 0;
sl@0: 
sl@0: 		/** View information associated with a single content object in a file specified by file handle. Can be used when the source file is in the client's private directory.
sl@0: 		
sl@0: 		This call blocks execution and only returns once the display is dismissed 
sl@0: 		by the user.
sl@0: 
sl@0: 		@param aInfo The information to display.
sl@0: 		@param aFile The file handle for the file containing the content object.
sl@0: 		@param aUniqueId The unique id of the content object.	
sl@0: 		@leave KErrCANotSupported if the feature not supported or if agent cannot display the requested information.
sl@0: 		@leave ...		One of the other CAF error codes defined in \c caferr.h  
sl@0: 		 				or one of the system-wide error codes 
sl@0: 						for any other errors.		
sl@0: 		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted. 
sl@0: 		*/
sl@0: 		IMPORT_C virtual void DisplayInfoL(TDisplayInfo aInfo, RFile& aFile, const TDesC& aUniqueId);
sl@0: 	
sl@0: 		/** 
sl@0: 		Identifies whether or not the file at the given URI is to be handled by
sl@0: 		this agent.
sl@0: 
sl@0: 		The agent should perform the mimimum possible processing to make the recognition
sl@0: 		process as fast as possible. It should avoid opening the file whenever possible.
sl@0: 		
sl@0: 		The agent should leave only if a temporary or permanent condition prevents it from knowing
sl@0: 		whether it can detect the content's type.
sl@0: 		  
sl@0: 		@param aURI		Location of the file to be examined.
sl@0: 		@param aShareMode	The share mode to use if the agent opens a file.
sl@0: 		@return			ETrue if this agent supports and recognises the file, EFalse otherwise. 
sl@0: 		*/
sl@0: 		virtual TBool IsRecognizedL(const TDesC& aURI, TContentShareMode aShareMode) const = 0;
sl@0: 
sl@0: 		/** 
sl@0: 		Identifies whether or not the file is handled by this agent.
sl@0: 
sl@0: 		The agent should look at the name of the file first to try and avoid the need
sl@0: 		to read from the file.
sl@0: 		
sl@0: 		The agent should leave only if a temporary or permanent condition prevents it from knowing
sl@0: 		whether it can detect the content's type.		
sl@0: 		  
sl@0: 		@param aFile An open file handle.
sl@0: 	    @return ETrue if this agent supports and recognises the file, EFalse otherwise. 
sl@0: 		*/
sl@0: 		virtual TBool IsRecognizedL(RFile& aFile) const = 0;
sl@0: 
sl@0: 		/** 
sl@0: 		 Determines whether the file is recognized by this agent. 
sl@0: 		 If it is the agent will fill in the file mime type and content mime 
sl@0: 		 type. 
sl@0: 		 
sl@0: 		 The agent should attempt to recognized the file in an efficient manner
sl@0: 		 It should avoid opening the file to provide the best performance.
sl@0: 
sl@0: 		 The agent should leave only if a temporary or permanent condition prevents it from 
sl@0: 		 detecting content's type.
sl@0: 
sl@0: 		 The agent SHOULD NOT perform any API policing on this API since it
sl@0: 		 will be called from within the Apparc server's process. 
sl@0: 		  
sl@0: 		 If a file is recognized, the file mime type should always be set to
sl@0: 		 the correct value. For the content mime type there are three special cases:
sl@0: 		 
sl@0: 		 @li If the file needs to be imported through the Supplier API before
sl@0: 		 it can be used then the agent should leave the aContentMimeType
sl@0: 		 parameter blank (zero length). 
sl@0: 		 
sl@0: 		 @li If the file has no embedded content, eg an image/jpeg (.jpg) file 
sl@0: 		 the agent should leave the aContentMimeType parameter blank (zero length).
sl@0:   
sl@0: 		 @li If more than one content object is contained within the file, the agent will
sl@0: 		 set aContentMimeType to "application/x-caf" indicating it is an archive that can
sl@0: 		 be navigated by CAF regardless of the actual file format.
sl@0: 		 
sl@0: 		 @param aFileName			The name of the file to recognize. The name is examined, not the file itself.
sl@0: 		 @param aBuffer				Buffer containing bytes from the start of the file.
sl@0: 		 @param aFileMimeType 		Used to return the mime type of the file to the caller.
sl@0: 		 @param aContentMimeType	Used to return the mime type of the content embedded within the file to the caller. This field should be zero length if there is no embedded content.
sl@0: 	     @return				Whether or not the file was recognized.
sl@0:  		 @return ETrue if the file is handled by this agent. The aFileMimeType and aContentMimeType were updated.
sl@0: 		 @return EFalse if the file was not recognized by this agent.
sl@0: 		 */
sl@0: 		virtual TBool RecognizeFileL(const TDesC& aFileName, const TDesC8& aBuffer, TDes8& aFileMimeType, TDes8& aContentMimeType) const = 0;
sl@0: 
sl@0: 		
sl@0: 		/** Allows extended synchronous calls to the agent
sl@0: 		Objects are passed in and out using serialization
sl@0: 
sl@0: 		@param aCommand The agent defined command.
sl@0: 		@param aInputBuffer Non modifyable input data buffer.
sl@0: 		@param aOutputBuffer Modifyable output buffer to hold the result of the command.
sl@0: 		@return The outcome of the agent specific command.
sl@0: 		@return KErrNone if the command was successful.
sl@0: 		@return KErrCANotSupported if the agent does not recognize the command.
sl@0: 		@return KErrPermissionDenied if the agent does not permit the client to execute this command.
sl@0: 		@return Otherwise one of the other CAF error codes defined in \c caferr.h  
sl@0: 				or one of the other system-wide error codes 
sl@0: 				for any other errors.		
sl@0:   		@capability DRM Access to extended DRM agent functions is not permitted for processes without DRM capability
sl@0: 		*/
sl@0: 		virtual TInt AgentSpecificCommand(TInt aCommand, const TDesC8& aInputBuffer, TDes8& aOutputBuffer) = 0;
sl@0: 
sl@0: 		/** Allows extended asynchronous calls to the agent. 
sl@0: 		Objects can be passed in and out using serialization.
sl@0: 		NB: No assumption should be made about the scope of the descriptor 
sl@0: 		passed to aInputBuffer for asynchronous IPC.
sl@0: 
sl@0: 		@param aCommand The agent defined command.
sl@0: 		@param aInputBuffer Non modifyable input data buffer.
sl@0: 		@param aOutputBuffer Modifyable output buffer to hold the result of the command.
sl@0: 		@param aStatus 	Asynchronous request status. On completion this will 
sl@0: 						contain one of the following error codes: KErrNone if the command
sl@0: 						was successful. KErrCANotSupported if the agent does 
sl@0: 						not recognize the command. KErrPermissionDenied if the 
sl@0: 						agent does not permit the client to execute this command.
sl@0: 						Otherwise one of the other CAF error codes 
sl@0: 						defined in \c caferr.h  or one of the other 
sl@0: 						system-wide error codes for any other errors.
sl@0: 		@capability DRM Access to extended DRM agent functions is not permitted for processes without DRM capability
sl@0: 		*/
sl@0: 		virtual void AgentSpecificCommand(TInt aCommand, const TDesC8& aInputBuffer, TDes8& aOutputBuffer, TRequestStatus& aStatus) = 0;
sl@0: 
sl@0: 		/** Allow the agent to display management information for users to 
sl@0: 		manage any settings	or other information stored by the agent
sl@0: 
sl@0: 		The scope of this information is left to the agent implementation but it is expected
sl@0: 		that a DRM agent will display the state of all DRM rights objects 
sl@0: 		(pending, available, expired, orphaned) and allow users to delete rights 
sl@0: 		that are no longer required.
sl@0: 
sl@0: 		@leave KErrCANotSupported If the agent does support the display of management information.
sl@0: 		@capability DRM Agents implementing DRM may not display their management dialog to processes without DRM capability
sl@0: 		*/
sl@0: 		virtual void DisplayManagementInfoL() = 0;
sl@0: 
sl@0: 
sl@0: 		/** Prepare the HTTP request headers required to download files that may be 
sl@0: 		required for this agent.
sl@0: 
sl@0: 		@param aStringPool The string pool used by the HTTP session.
sl@0: 		@param aRequestHeaders The agent will add any required headers to this object.
sl@0: 		*/
sl@0: 		virtual void PrepareHTTPRequestHeaders(RStringPool& aStringPool, RHTTPHeaders& aRequestHeaders) const = 0;
sl@0: 
sl@0: 		
sl@0: 		/** Rename a directory
sl@0: 
sl@0: 		This function can be used to rename a directory from within the agent's 
sl@0: 		private directory. Access to the agents private directory is permitted 
sl@0: 		at the agents discretion. 
sl@0: 		
sl@0: 		@param aOldName The existing pathname of the directory to rename.
sl@0: 		@param aNewName The new pathname of the directory.
sl@0: 		@return The outcome of the RenameDir operation.
sl@0: 		@return KErrNone if the directory was removed successfully.
sl@0: 		@return KErrAccessDenied f the agent does not allow the directory to be removed.
sl@0: 		@return KErrCANotSupported if the agent does not support directory removal.
sl@0: 		@return KErrPermissionDenied if the client does not have the necessary capabilities to remove directories.
sl@0: 		@return Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 
sl@0: 				other system-wide error codes for any other errors.
sl@0: 		@capability DRM Required when attempting to access an agents private directory
sl@0: 		*/
sl@0: 		IMPORT_C virtual TInt RenameDir(const TDesC& aOldName, const TDesC& aNewName );
sl@0: 		
sl@0: 		/**
sl@0: 		Make a copy of the content file (eg to removable media) belonging to this agent 
sl@0: 		using a file handle
sl@0: 
sl@0: 		Access to the agents private directory is permitted at the 
sl@0: 		agents discretion.
sl@0: 
sl@0:   		@param aSource The handle the source file.
sl@0: 		@param aDestination The full pathname of the destination file.
sl@0: 		@return The outcome of the copy operation.
sl@0: 		@return KErrNone if the file was copied successfully.
sl@0: 		@return KErrAccessDenied if the agent does not allow the file to be copied.
sl@0: 		@return KErrCANotSupported if the agent does not support file copying.
sl@0: 		@return KErrPermissionDenied if the client does not have the necessary capabilities to copy the file.
sl@0: 		@return Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 
sl@0: 				other system-wide error codes for any other errors.
sl@0:   		@capability DRM Copying DRM protected files is not permitted for processes without DRM capability. Copying unprotected files is permitted
sl@0: 		*/
sl@0: 		IMPORT_C virtual TInt CopyFile(RFile& aSource, const TDesC& aDestination);
sl@0: 		
sl@0: #ifdef SYMBIAN_ENABLE_SDP_WMDRM_SUPPORT
sl@0: 		/** 
sl@0: 		Identifies whether or not the WMDRM content is handled by this agent using the header
sl@0: 		data of WMDRM file or stream content.
sl@0: 		
sl@0: 		The agent should leave only if a temporary or permanent condition prevents it from knowing
sl@0: 		whether it can detect the content's type.
sl@0: 
sl@0: 		@param aHeaderData	Header data of WMDRM file or stream content.
sl@0: 	    @return ETrue 		If this agent recognises the given content. 
sl@0: 		*/
sl@0: 		IMPORT_C virtual TBool IsRecognizedL(const TDesC8& aHeaderData) const;
sl@0: 		
sl@0: 		/** 
sl@0: 		 Determines whether or not the WMDRM content is recognized by this agent. 
sl@0: 		 If it is recognized, the agent will populate the file and content mime 
sl@0: 		 type. 
sl@0: 		 
sl@0: 		 The agent should leave only if a temporary or permanent condition prevents it from 
sl@0: 		 detecting content's type.
sl@0: 
sl@0: 		 @param aHeaderData			Header data of WMDRM content.
sl@0: 		 @param aFileMimeType 		Used to return the mime type of the content to the caller.
sl@0: 		 @param aContentMimeType	Used to return the mime type of the content embedded within the file to the caller. This field should be zero length if there is no embedded content.
sl@0: 	     @return					Whether or not the content was recognized.
sl@0:  		 @return ETrue 				If the content is handled by this agent. The aFileMimeType and aContentMimeType were updated.
sl@0: 		 @return EFalse 			If the content was not recognized by this agent.
sl@0: 		 */
sl@0: 		IMPORT_C virtual TBool RecognizeContentL(const TDesC8& aHeaderData, TDes8& aFileMimeType, TDes8& aContentMimeType) const;
sl@0: 		
sl@0: 		/**  Get an attribute from WMDRM content.
sl@0: 	
sl@0: 		@param aHeaderData	Header data of WMDRM content.
sl@0: 		@param aAttribute	The attribute to retrieve from ContentAccess::TAttribute.
sl@0: 		@param aValue		Used to return the value of the attribute.
sl@0: 		
sl@0: 		@return				KErrNone if the attribute value was updated.
sl@0: 		@return				KErrCANotSupported if the requested attribute is not supported for this content.
sl@0: 		@return				Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 
sl@0: 							other system-wide error codes for any other errors.
sl@0: 		@capability DRM 	Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted. 
sl@0: 		*/
sl@0: 		IMPORT_C virtual TInt GetAttribute(const TDesC8& aHeaderData, TInt aAttribute, TInt& aValue);
sl@0: 		
sl@0: 		/** Get a set of attributes from WMDRM content.
sl@0: 
sl@0: 		@param aHeaderData		Header data of WMDRM content.
sl@0: 		@param aAttributeSet	The set of attributes to query and update.
sl@0: 		
sl@0: 		@return 				KErrNone if the attribute set was updated successfully.
sl@0: 		@return 				Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 
sl@0: 								other system-wide error codes for any other errors.
sl@0: 		@capability DRM 		Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted. 
sl@0: 		*/
sl@0: 		IMPORT_C virtual TInt GetAttributeSet(const TDesC8& aHeaderData, RAttributeSet& aAttributeSet);
sl@0: 		
sl@0: 		
sl@0: 		/**  Get text string attributes or meta-data from WMDRM content.
sl@0: 
sl@0: 		@param aHeaderData	Header data of WMDRM content.
sl@0: 		@param aAttribute	The attribute to retrieve from ContentAccess::TStringAttribute.
sl@0: 		@param aValue		Used to return the value of the attribute.
sl@0: 		
sl@0: 		@return				KErrNone if the attribute was retrieved successfully.
sl@0: 		@return				KErrNotFound if the content object does not exist.
sl@0: 		@return				KErrCANotSupported if the requested attribute does not apply to this content object.
sl@0: 		@return				KErrOverflow if the buffer was not large enough to return the result.
sl@0: 		@return				Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 
sl@0: 							other system-wide error codes for any other errors.
sl@0: 		@capability DRM 	Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted. 
sl@0: 		*/
sl@0: 		IMPORT_C virtual TInt GetStringAttribute(const TDesC8& aHeaderData, TInt aAttribute, TDes& aValue);
sl@0: 		
sl@0: 		/** Used to obtain a set of string attributes from WMDRM content.
sl@0: 
sl@0: 		@param aStringAttributeSet	The set of attributes to query and update.
sl@0: 		@param aHeaderData			Header data of WMDRM content.
sl@0: 	
sl@0: 		@return 					KErrNone if the attribute set was updated successfully.
sl@0: 		@return 					KErrNotFound if the object with the given virtual path was not found.
sl@0: 		@return 					Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 
sl@0: 									other system-wide error codes for any other errors.
sl@0: 		@capability DRM 			Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted. 
sl@0: 		*/
sl@0: 		IMPORT_C virtual TInt GetStringAttributeSet(const TDesC8& aHeaderData, RStringAttributeSet& aStringAttributeSet);
sl@0: 
sl@0: 
sl@0: #endif //#ifdef SYMBIAN_ENABLE_SDP_WMDRM_SUPPORT
sl@0: 		
sl@0: 		};
sl@0: 
sl@0: 		
sl@0: 	/** 
sl@0: 	Manages and retrieves rights objects from an agent.
sl@0: 
sl@0:  	@publishedPartner
sl@0: 	@released
sl@0: 	*/
sl@0: 	class CAgentRightsManager  : public CBase
sl@0: 		{
sl@0: 	public:
sl@0: 		/** List all rights held by the agent 
sl@0: 		@param aArray The client supplied array used to store the CRightsInfo objects. The agent will add CRightsInfo objects to the supplied array.
sl@0: 		@leave KErrPermissionDenied If the agent does not permit the client to access rights information.
sl@0: 		@leave ...		One of the CAF error codes defined in \c caferr.h  
sl@0: 		 				or one of the other system-wide error codes 
sl@0: 						for any other errors.				
sl@0: 		@capability DRM Access to DRM rights is not permitted for processes without DRM capability. 
sl@0: 		*/
sl@0: 		virtual void ListAllRightsL(RStreamablePtrArray<CRightsInfo>& aArray) const = 0;
sl@0: 
sl@0: 		/** List all rights associated with a particular file
sl@0: 		@param aArray The client supplied array used to store the CRightsInfo objects. The agent will add CRightsInfo objects to the supplied array.
sl@0: 		@param aUri The name of the file.
sl@0: 		@leave KErrPermissionDenied If the agent does not permit the client to access rights information.
sl@0: 		@leave ...		One of the CAF error codes defined in \c caferr.h  
sl@0: 		 				or one of the other system-wide error codes 
sl@0: 						for any other errors.				
sl@0: 		@capability DRM Access to DRM rights is not permitted for processes without DRM capability. 
sl@0: 		*/
sl@0: 		virtual void ListRightsL(RStreamablePtrArray<CRightsInfo>& aArray, const TDesC& aUri) const = 0;
sl@0: 
sl@0: 		/** List all rights associated with a particular content object
sl@0: 		@param aArray The client supplied array used to store the CRightsInfo objects. The agent will add CRightsInfo objects to the supplied array.
sl@0: 		@param aVirtualPath The content object.
sl@0: 		@leave KErrPermissionDenied If the agent does not permit the client to access rights information.
sl@0: 		@leave ...		One of the CAF error codes defined in \c caferr.h  
sl@0: 		 				or one of the other system-wide error codes 
sl@0: 						for any other errors.				
sl@0: 		@capability DRM Access to DRM rights is not permitted for processes without DRM capability. 
sl@0: 		*/
sl@0: 		virtual void ListRightsL(RStreamablePtrArray<CRightsInfo>& aArray, TVirtualPathPtr& aVirtualPath) const = 0;
sl@0: 
sl@0: 		/** List all rights associated with a particular content object in a file specified by file handle. Can be used when the source file is in the client's private directory.
sl@0: 		
sl@0: 		@param aArray  		The client supplied array used to store the CRightsInfo objects. The agent will add CRightsInfo objects to the supplied array.
sl@0: 		@param aFile  		The file handle for the file containing the content object.
sl@0: 		@param aUniqueId	The unique id of the content object.
sl@0: 		@leave KErrCANotSupported if the feature not supported.
sl@0: 		@leave KErrPermissionDenied If the agent does not permit the client to access rights information.
sl@0: 		@leave ...		One of the CAF error codes defined in \c caferr.h  
sl@0: 		 				or one of the other system-wide error codes 
sl@0: 						for any other errors.				
sl@0: 		@capability DRM Access to DRM rights is not permitted for processes without DRM capability. 
sl@0: 		*/
sl@0: 		IMPORT_C virtual void ListRightsL(RStreamablePtrArray<CRightsInfo>& aArray, RFile& aFile, const TDesC& aUniqueId) const;			
sl@0: 
sl@0: 		/** List all content associated with a particular rights object
sl@0: 		@param aArray The client supplied array used to store the list of content objects. The agent will add CVirtualPath objects to the supplied array.
sl@0: 		@param aRightsInfo The rights object.
sl@0: 		@leave KErrPermissionDenied If the agent does not permit the client to access rights information.
sl@0: 		@leave ...		One of the CAF error codes defined in \c caferr.h  
sl@0: 		 				or one of the other system-wide error codes 
sl@0: 						for any other errors.				
sl@0: 		@capability DRM Access to DRM rights is not permitted for processes without DRM capability. 
sl@0: 		*/
sl@0: 		virtual void ListContentL(RStreamablePtrArray<CVirtualPath>& aArray, CRightsInfo& aRightsInfo) const = 0;
sl@0: 		
sl@0: 		/** This will be used by applications to retrieve an agent specific rights object
sl@0: 		@param aRightsInfo The rights object.
sl@0: 		@return An agent specific rights object.
sl@0: 		@leave KErrPermissionDenied If the agent does not permit the client to access rights information.
sl@0: 		@leave ...		One of the CAF error codes defined in \c caferr.h  
sl@0: 		 				or one of the other system-wide error codes 
sl@0: 						for any other errors.				
sl@0: 		@capability DRM Access to DRM rights is not permitted for processes without DRM capability. 
sl@0: 		*/
sl@0: 		virtual MAgentRightsBase* GetRightsDataL(const CRightsInfo& aRightsInfo) const = 0;
sl@0: 
sl@0: 		/** Asks the DRM agent to delete a rights object 
sl@0: 
sl@0: 		The agent may display a dialog asking the user to confirm the delete. Execution
sl@0: 		will be blocked until the dialog is complete. Applications can request 
sl@0: 		to disable the agents user interface using the SetProperty() command
sl@0: 	
sl@0: 		@param aRightsInfo The rights object.
sl@0: 		@return The outcome of the delete operation.
sl@0: 		@return KErrNone if the rights were deleted.
sl@0: 		@return KErrCancel if the user cancels an agent supplied confirmation dialog.
sl@0: 		@return KErrNotFound if the rights object does not exist.
sl@0: 		@return KErrPermissionDenied if the agent does not permit the client to access rights information.
sl@0: 		@capability DRM Access to DRM rights is not permitted for processes without DRM capability. 
sl@0: 		*/
sl@0: 		virtual TInt DeleteRightsObject(const CRightsInfo& aRightsInfo) = 0;
sl@0: 		
sl@0: 		/** Deletes all rights associated with a particular content object
sl@0: 
sl@0: 		The agent may display a dialog asking the user to confirm the delete. Execution
sl@0: 		will be blocked until the dialog is complete. Applications can request 
sl@0: 		to disable the agents user interface using the SetProperty() command
sl@0: 
sl@0: 		@param aVirtualPath The path of the content object.
sl@0: 		@return The outcome of the delete operation.
sl@0: 		@return KErrNone if the rights were deleted.
sl@0: 		@return KErrNotFound if no rights objects exist for the specified content object.
sl@0: 		@return KErrCancel if the user cancels an agent supplied confirmation dialog.
sl@0: 		@return KErrPermissionDenied if the agent does not permit the client to access rights information.
sl@0: 		@capability DRM Access to DRM rights is not permitted for processes without DRM capability. 
sl@0: 		*/
sl@0: 		virtual TInt DeleteAllRightsObjects(const TVirtualPathPtr& aVirtualPath) = 0;
sl@0: 
sl@0: 		/** Deletes all rights associated with a particular content object in a file specified by file handle. Can be used when the source file is in the client's private directory.
sl@0: 
sl@0: 		The agent may display a dialog asking the user to confirm the delete. Execution
sl@0: 		will be blocked until the dialog is complete. Applications can request 
sl@0: 		to disable the agents user interface using the SetProperty() command.
sl@0: 
sl@0: 		@param aFile The file handle for the file containing the content object.
sl@0: 		@param aUniqueId The unique id of the content object.
sl@0: 		@return The outcome of the delete operation.
sl@0: 		@return KErrNone if the rights were deleted.
sl@0: 		@return KErrNotFound if no rights objects exist for the specified content object.
sl@0: 		@return KErrCancel if the user cancels an agent supplied confirmation dialog.
sl@0: 		@return KErrPermissionDenied if the agent does not permit the client to access rights information.
sl@0: 		@return KErrCANotSupported if the feature not supported.
sl@0: 		@capability DRM Access to DRM rights is not permitted for processes without DRM capability. 
sl@0: 		*/
sl@0: 		IMPORT_C virtual TInt DeleteAllRightsObjects (RFile& aFile, const TDesC& aUniqueId); 
sl@0: 			
sl@0: 		/** 
sl@0: 		Allows an application to request the modification of a property 
sl@0: 		within the agent. The agent may or may not permit the property to be changed
sl@0: 		 	
sl@0: 		@param aProperty The property to set.
sl@0: 		@param aValue The value of the property.
sl@0: 		@return KErrNone if the property was set.
sl@0: 		@return KErrCANotSupported if the agent does not support the property or value.
sl@0: 		@return KErrAccessDenied if the agent does not permit the property to be changed.
sl@0: 		@return KErrPermissionDenied if the application does not have the necessary capability to change the property.
sl@0: 		@capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted 
sl@0: 		*/
sl@0:  		virtual TInt SetProperty(TAgentProperty aProperty, TInt aValue) = 0;
sl@0: 		};
sl@0: 
sl@0: 
sl@0: } // namespace ContentAccess
sl@0: #endif // __AGENTINTERFACE_H__
sl@0: