/*

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

* All rights reserved.

* This component and the accompanying materials are made available

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

* which accompanies this distribution, and is available

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

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description: 

*

*/

/** 

@file

@publishedPartner

@released

*/

#ifndef __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;		

#ifdef SYMBIAN_ENABLE_64_BIT_FILE_SERVER_API

		/**

		 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.

		 If agent does not support 64bit, fallback to 32bit Read is provided automatically by CAF			

		 @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(TInt64 aPos, TDes8& aDes, TInt aLength, TRequestStatus& aStatus) const;

#else

			/**

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

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

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

		 @see Read(TDes8& aDes)

		 @param aPos		Position of first byte to be read. 

							This is an offset from the start of the file. 

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

		  					existing contents are overwritten. On return,

		 					its length is set to the number of bytes read. 

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

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

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

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

		 					of the following error codes: KErrNone if the data was 

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

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

							error codes for any other errors.

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

		 @return 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;

#endif //SYMBIAN_ENABLE_64_BIT_FILE_SERVER_API

		/**

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

#ifdef SYMBIAN_ENABLE_64_BIT_FILE_SERVER_API

		/**

		 This is the 64bit version of CData::DataSizeL

		 Client can call this function instead of CData::DataSizeL. If it's not implemented by the agent,

		 fallback to 32bit counterpart will be provided automatically

		 @see DataSizeL(TInt& aSize)

		*/

		IMPORT_C void DataSize64L(TInt64& aSize);

#endif //SYMBIAN_ENABLE_64_BIT_FILE_SERVER_API

		/**

		 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;