/*

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

* All rights reserved.

* This component and the accompanying materials are made available

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

* which accompanies this distribution, and is available

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

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description: 

*

*/

/** 

@file

@publishedPartner

@released

*/

#ifndef __DATA_H__

#define __DATA_H__

#include <e32base.h>

#include <f32file.h>

#include <caf/caftypes.h>

namespace ContentAccess

{

	class CAgentFactory;

	class CAgentInfo;

	class TVirtualPathPtr;

	class CAgentData;

	class RAttributeSet;

	class RStringAttributeSet;

	/**

 	Allows clients to read data from a content object. 

 	This class is initialised with an agent implementation that is

 	responsible for this content object.

 	@publishedPartner

 	@released

 	*/

	class CData : public CBase

		{

	public:

		/** 

		 Creates a new CData object. 

		 @param aVirtualPath The content object to read

		 @param aIntent	The intended use of the content.

		 @param aShareMode The file share mode used to open this content.

		 @return The new CData object.

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

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

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

		 @leave KErrCANoRights		No rights exist for the content object.

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

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

		 @leave KErrAccessDenied	The content is already in use.

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

		 				or one of the other system-wide error codes 

						for any other errors.

		 */

		IMPORT_C static CData* NewL(const TVirtualPathPtr& aVirtualPath,

							TIntent aIntent, TContentShareMode aShareMode); 

		/** 

		 Creates a new CData object. 

		 @param aVirtualPath The content object to read.

		 @param aShareMode The file share mode used to open this content.

		 @return The new CData object.

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

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

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

		 @leave KErrCANoRights		No rights exist for the content object.

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

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

		 @leave KErrAccessDenied	The content is already in use.

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

		 				or one of the other system-wide error codes for 

						any other errors.		 

		 */

		IMPORT_C static CData* NewL(const TVirtualPathPtr& aVirtualPath,

							TContentShareMode aShareMode); 

		/** 

		 Creates a new CData object 

		 @param aVirtualPath The content object to read.

		 @param aIntent	The intended use of the content.

		 @param aShareMode The file share mode used to open this content.

		 @return The new CData object.

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

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

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

		 @leave KErrCANoRights		No rights exist for the content object.

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

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

		 @leave KErrAccessDenied	The content is already in use.

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

		 				or one of the other system-wide error codes for 

						any other errors.

		 */

		IMPORT_C static CData* NewLC(const TVirtualPathPtr& aVirtualPath,

							TIntent aIntent, TContentShareMode aShareMode); 

		/** 

		 Creates a new CData object 

		 @param aVirtualPath The content object to read.

		 @param aShareMode The file share mode used to open this content.

		 @return The new CData object.

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

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

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

		 @leave KErrCANoRights		No rights exist for the content object.

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

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

		 @leave KErrAccessDenied	The content is already in use.

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

		 					or one of the other system-wide error codes for 

							any other errors.

		 */					

		IMPORT_C static CData* NewLC(const TVirtualPathPtr& aVirtualPath,

							TContentShareMode aShareMode); 

		/** 

		 Creates a new CData object. 

		 @param aFile An open RFile handle, the agent will make a duplicate of this handle. 

		 The underlying RFs session should be shared for transfer to other processes using RFs::ShareProtected(), since the agent may use transfer this handle to its own or one of the system servers.

		 @param aUniqueId The content object to read.

		 @param aIntent	The intended use of the content.

		 @return The new CData object.

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

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

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

		 @leave KErrCANoRights		No rights exist for the content object.

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

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

		 @leave KErrAccessDenied	The content is already in use.

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

		 					or one of the other system-wide error codes for 

							any other errors.

		 */

		IMPORT_C static CData* NewL(RFile& aFile, const TDesC& aUniqueId, TIntent aIntent);

		/** 

		 Creates a new CData object. 

		 @param aFile An open RFile handle, the agent will make a duplicate of this handle. 

		 The underlying RFs session should be shared for transfer to other processes using RFs::ShareProtected(), since the agent may use transfer this handle to its own or one of the system servers.

		 @param aUniqueId The content object to read.

		 @return The new CData object.

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

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

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

		 @leave KErrCANoRights		No rights exist for the content object.

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

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

		 @leave KErrAccessDenied	The content is already in use.

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

		 					or one of the other system-wide error codes for 

							any other errors.

		 */

		IMPORT_C static CData* NewL(RFile& aFile, const TDesC& aUniqueId);

		/** 

		 Creates a new CData object. 

		 @param aFile An open RFile handle, the agent will make a duplicate of this handle. 

		 The underlying RFs session should be shared for transfer to other processes using RFs::ShareProtected(), since the agent may use transfer this handle to its own or one of the system servers.

		 @param aUniqueId The content object to read.

		 @param aIntent	The intended use of the content.

		 @return The new CData object.

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

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

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

		 @leave KErrCANoRights		No rights exist for the content object.

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

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

		 @leave KErrAccessDenied	The content is already in use.

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

		 						or one of the other system-wide error codes 

								for any other errors.

		 */

		IMPORT_C static CData* NewLC(RFile& aFile, const TDesC& aUniqueId, TIntent aIntent);

		/** 

		 Creates a new CData object. 

		 @param aFile An open RFile handle, the agent will make a duplicate of this handle. 

		 The underlying RFs session should be shared for transfer to other processes using RFs::ShareProtected(), since the agent may use transfer this handle to its own or one of the system servers.

		 @param aUniqueId The content object to read.

		 @return The new CData object.

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

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

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

		 @leave KErrCANoRights		No rights exist for the content object.

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

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

		 @leave KErrAccessDenied	The content is already in use.

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

		 						or one of the other system-wide error codes 

								for any other errors.

		 */

		IMPORT_C static CData* NewLC(RFile& aFile, const TDesC& aUniqueId);

		/** 

		 Creates a new CData object. 

		 @param aAgentUid The agent determined to support this content.

		 @param aVirtualPath The content object to read.

		 @param aIntent	The intended use of the content.

		 @param aShareMode The file share mode used to open this content.

		 @return The new CData object.

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

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

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

		 @leave KErrCANoRights		No rights exist for the content object.

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

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

		 @leave KErrAccessDenied	The content is already in use.

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

		 						or one of the other system-wide error codes 

								for any other errors.

		@internalComponent

		@released

		 */

		static CData* NewLC(TUid aAgentUid, const TVirtualPathPtr& aVirtualPath,

							TIntent aIntent, TContentShareMode aShareMode); 

		/** 

		 Creates a new CData object. 

		 @param aAgentUid The Uid of the agent who supports this content.

		 @param aFile An open RFile handle, the agent will make a duplicate of this handle. 

		 The underlying RFs session should be shared for transfer to other processes using RFs::ShareProtected(), since the agent may use transfer this handle to its own or one of the system servers.

		 @param aUniqueId The content object to read.

		 @param aIntent	The intended use of the content.

		 @return The new CData object.

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

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

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

		 @leave KErrCANoRights		No rights exist for the content object.

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

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

		 @leave KErrAccessDenied	The content is already in use.

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

		 						or one of the other system-wide error codes for 

								any other errors.

		@internalComponent

		@released

		 */

		static CData* NewLC(TUid aAgentUid, RFile& aFile, const TDesC& aUniqueId, TIntent aIntent);

		/** destructor */

		virtual ~CData();

		/** 

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

		 descriptor or the end of the content object.

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

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

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

		 through content, the end has been reached when the

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

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

		  				contents are overwritten. On return, its length is set

		 				to the number of bytes read.

		 @return		KErrNone if successful.

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

		 				one of the other system-wide error codes.

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

		*/

		IMPORT_C TInt Read(TDes8& aDes) const;

		/** 

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

		 descriptor or the end of the content object.

		 @see Read(TDes8& aDes)

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

		  				contents are overwritten. On return, its length is set

		 				to the number of bytes read.

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

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

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

		 @return		KErrNone if successful.

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

		 				one of the other system-wide error codes.

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

		*/

		IMPORT_C TInt Read(TDes8& aDes,TInt aLength) const;

		/**

		 Read content asynchronously up to the maximum length of the descriptor

		 or until the end of the content object is reached.

		 NB: It is important that the descriptor passed to 

		 aDes remains in scope until the request has completed.		

		 @see Read(TDes8& aDes)

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

		  					existing contents are overwritten. On return,

		 					its length is set to the number of bytes read.

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

		 					of the following error codes: KErrNone if the data was 

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

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

							error codes for any other errors.

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

		*/	

		IMPORT_C void Read(TDes8& aDes, TRequestStatus& aStatus) const;

		/**

		 Read content asynchronously up to the specified length 

		 or until the end of the content object is reached.

		 NB: It is important that the descriptor passed to 

		 aDes remains in scope until the request has completed.		 	

		 @see Read(TDes8& aDes)

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

		  					existing contents are overwritten. On return,

		 					its length is set to the number of bytes read.

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

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

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

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

		 					of the following error codes: KErrNone if the data was 

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

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

							error codes for any other errors.

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

		*/

		IMPORT_C void Read(TDes8& aDes, TInt aLength, TRequestStatus& aStatus) const;

		/**

		 Cancels asynchronous read.

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

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

		 					this function will not have any effect.

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

		*/

		IMPORT_C void ReadCancel(TRequestStatus &aStatus) const;		

		/**

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

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

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

		 NB: It is important that the descriptor passed to 

		 aDes remains in scope until the request has completed.			

		 @see Read(TDes8& aDes)

		 @param aPos		Position of first byte to be read. 

		 					This is an offset from the start of the file. 

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

		  					existing contents are overwritten. On return,

		 					its length is set to the number of bytes read. 

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

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

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

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

		 					of the following error codes: KErrNone if the data was 

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

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

							error codes for any other errors.

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

		 @return KErrArgument if a negative offset is supplied.

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

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

		 */

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

		/**

		 Gets the data size in bytes.

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

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

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

						system-wide error codes for any other errors.		 

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

		 */

		IMPORT_C void DataSizeL(TInt& aSize);

		/**

		 Changes or retrieves the location of the file pointer within 

		 the content object.

 		 NOTE: Some operations may fail if the content data is sourced over a network connection.		 

		 There are four seek modes used: 

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

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

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

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

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

		 position relative to the start of the content object.

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

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

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

		 used to retrieve the current file pointer location 

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

		 aPos bytes from the start of the content object

		 @see TSeek

		 @param aMode	Seek mode - controls the destination of the

		  				seek operation.

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

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

		 relative to the end of the file.

		 @return		KErrNone if successful. 

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

		 				of the other system-wide error codes.

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

		*/

		IMPORT_C TInt Seek(TSeek aMode,TInt& aPos) const;

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

		it is only set for this CData session and does not impact other CAF	users.

		 For example setting the buffer-size to 256 bytes can be achieved as follows:

					@code

		  			MyData->SetProperty(EAgentPropertyBufferSize, 256);

		  			@endcode

  		@see ContentAccess::TAgentProperty

		@param aProperty The property to set.

		@param aValue The value of the property.

		@return Whether or not the property was set.

		@return KErrNone if the property was set.

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

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

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

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

		*/

		IMPORT_C TInt SetProperty(TAgentProperty aProperty, TInt aValue);

		/**

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

		 current rights for the data object. 

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

		 any rights-state such as play counts.

		 @see ContentAccess::TIntent

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

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

		 @return KErrNone if the intent is permitted.

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

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

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

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

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

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

				other system-wide error codes for any other errors.

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

		 */		

		IMPORT_C TInt EvaluateIntent(TIntent aIntent);

		/**

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

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

		 stateful rights such as play counts where necessary.

  		 Applications should be very careful to use this function correctly.

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

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

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

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

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

		 the file before calling ExecuteIntent. 

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

		 play counts that apply. 

		@param aIntent	The intent indicator.

		@return The result of attempting executing the intent.

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

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

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

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

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

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

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

				other system-wide error codes for any other errors.

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