sl@0: /* sl@0: * Copyright (c) 2003-2008 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: /** sl@0: @file sl@0: sl@0: @publishedAll sl@0: @released sl@0: */ sl@0: sl@0: sl@0: #ifndef __DATA_H__ sl@0: #define __DATA_H__ sl@0: sl@0: #include sl@0: #include sl@0: #include sl@0: sl@0: namespace ContentAccess sl@0: { sl@0: class CAgentFactory; sl@0: class CAgentInfo; sl@0: class TVirtualPathPtr; sl@0: class CAgentData; sl@0: class RAttributeSet; sl@0: class RStringAttributeSet; sl@0: sl@0: sl@0: /** sl@0: Allows clients to read data from a content object. sl@0: sl@0: This class is initialised with an agent implementation that is sl@0: responsible for this content object. sl@0: sl@0: */ sl@0: class CData : public CBase sl@0: { sl@0: public: sl@0: /** sl@0: Creates a new CData object. sl@0: sl@0: @param aVirtualPath The content object to read sl@0: @param aIntent The intended use of the content. sl@0: @param aShareMode The file share mode used to open this content. sl@0: @return The new CData object. sl@0: sl@0: @leave KErrNotFound The content object with the given UniqueId does not exist. sl@0: @leave KErrCAPendingRights The rights have not yet arrived but are expected soon. sl@0: @leave KErrCANoPermission Rights exist but the specified intent is not permitted. sl@0: @leave KErrCANoRights No rights exist for the content object. sl@0: @leave KErrCANotSupported Unable to open the object with the specified UniqueId, it may be a container object. sl@0: @leave KErrPermissionDenied The agent does not allow the client to access the content object. sl@0: @leave KErrAccessDenied The content is already in use. sl@0: @leave ... 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: IMPORT_C static CData* NewL(const TVirtualPathPtr& aVirtualPath, sl@0: TIntent aIntent, TContentShareMode aShareMode); sl@0: sl@0: /** sl@0: Creates a new CData object. sl@0: sl@0: @param aVirtualPath The content object to read. sl@0: @param aShareMode The file share mode used to open this content. sl@0: @return The new CData object. sl@0: sl@0: @leave KErrNotFound The content object with the given UniqueId does not exist. sl@0: @leave KErrCAPendingRights The rights have not yet arrived but are expected soon. sl@0: @leave KErrCANoPermission Rights exist but the specified intent is not permitted. sl@0: @leave KErrCANoRights No rights exist for the content object. sl@0: @leave KErrCANotSupported Unable to open the object with the specified UniqueId, it may be a container object. sl@0: @leave KErrPermissionDenied The agent does not allow the client to access the content object. sl@0: @leave KErrAccessDenied The content is already in use. sl@0: @leave ... One of the other CAF error codes defined in \c caferr.h sl@0: or one of the other system-wide error codes for sl@0: any other errors. sl@0: */ sl@0: IMPORT_C static CData* NewL(const TVirtualPathPtr& aVirtualPath, sl@0: TContentShareMode aShareMode); sl@0: sl@0: sl@0: /** sl@0: Creates a new CData object sl@0: sl@0: @param aVirtualPath The content object to read. sl@0: @param aIntent The intended use of the content. sl@0: @param aShareMode The file share mode used to open this content. sl@0: @return The new CData object. sl@0: sl@0: @leave KErrNotFound The content object with the given UniqueId does not exist. sl@0: @leave KErrCAPendingRights The rights have not yet arrived but are expected soon. sl@0: @leave KErrCANoPermission Rights exist but the specified intent is not permitted. sl@0: @leave KErrCANoRights No rights exist for the content object. sl@0: @leave KErrCANotSupported Unable to open the object with the specified UniqueId, it may be a container object. sl@0: @leave KErrPermissionDenied The agent does not allow the client to access the content object. sl@0: @leave KErrAccessDenied The content is already in use. sl@0: @leave ... One of the other CAF error codes defined in \c caferr.h sl@0: or one of the other system-wide error codes for sl@0: any other errors. sl@0: */ sl@0: IMPORT_C static CData* NewLC(const TVirtualPathPtr& aVirtualPath, sl@0: TIntent aIntent, TContentShareMode aShareMode); sl@0: sl@0: /** sl@0: Creates a new CData object sl@0: sl@0: @param aVirtualPath The content object to read. sl@0: @param aShareMode The file share mode used to open this content. sl@0: @return The new CData object. sl@0: sl@0: @leave KErrNotFound The content object with the given UniqueId does not exist. sl@0: @leave KErrCAPendingRights The rights have not yet arrived but are expected soon. sl@0: @leave KErrCANoPermission Rights exist but the specified intent is not permitted. sl@0: @leave KErrCANoRights No rights exist for the content object. sl@0: @leave KErrCANotSupported Unable to open the object with the specified UniqueId, it may be a container object. sl@0: @leave KErrPermissionDenied The agent does not allow the client to access the content object. sl@0: @leave KErrAccessDenied The content is already in use. sl@0: @leave ... One of the other CAF error codes defined in \c caferr.h sl@0: or one of the other system-wide error codes for sl@0: any other errors. sl@0: */ sl@0: IMPORT_C static CData* NewLC(const TVirtualPathPtr& aVirtualPath, sl@0: TContentShareMode aShareMode); sl@0: sl@0: sl@0: /** sl@0: Creates a new CData object. sl@0: sl@0: @param aFile An open RFile handle, the agent will make a duplicate of this handle. sl@0: 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. sl@0: @param aUniqueId The content object to read. sl@0: @param aIntent The intended use of the content. sl@0: @return The new CData object. sl@0: sl@0: @leave KErrNotFound The content object with the given UniqueId does not exist. sl@0: @leave KErrCAPendingRights The rights have not yet arrived but are expected soon. sl@0: @leave KErrCANoPermission Rights exist but the specified intent is not permitted. sl@0: @leave KErrCANoRights No rights exist for the content object. sl@0: @leave KErrCANotSupported Unable to open the object with the specified UniqueId, it may be a container object. sl@0: @leave KErrPermissionDenied The agent does not allow the client to access the content object. sl@0: @leave KErrAccessDenied The content is already in use. sl@0: @leave ... One of the other CAF error codes defined in \c caferr.h sl@0: or one of the other system-wide error codes for sl@0: any other errors. sl@0: */ sl@0: IMPORT_C static CData* NewL(RFile& aFile, const TDesC& aUniqueId, TIntent aIntent); sl@0: sl@0: /** sl@0: Creates a new CData object. sl@0: sl@0: @param aFile An open RFile handle, the agent will make a duplicate of this handle. sl@0: 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. sl@0: @param aUniqueId The content object to read. sl@0: @return The new CData object. sl@0: sl@0: @leave KErrNotFound The content object with the given UniqueId does not exist. sl@0: @leave KErrCAPendingRights The rights have not yet arrived but are expected soon. sl@0: @leave KErrCANoPermission Rights exist but the specified intent is not permitted. sl@0: @leave KErrCANoRights No rights exist for the content object. sl@0: @leave KErrCANotSupported Unable to open the object with the specified UniqueId, it may be a container object. sl@0: @leave KErrPermissionDenied The agent does not allow the client to access the content object. sl@0: @leave KErrAccessDenied The content is already in use. sl@0: @leave ... One of the other CAF error codes defined in \c caferr.h sl@0: or one of the other system-wide error codes for sl@0: any other errors. sl@0: */ sl@0: IMPORT_C static CData* NewL(RFile& aFile, const TDesC& aUniqueId); sl@0: sl@0: /** sl@0: Creates a new CData object. sl@0: sl@0: @param aFile An open RFile handle, the agent will make a duplicate of this handle. sl@0: 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. sl@0: @param aUniqueId The content object to read. sl@0: @param aIntent The intended use of the content. sl@0: @return The new CData object. sl@0: sl@0: @leave KErrNotFound The content object with the given UniqueId does not exist. sl@0: @leave KErrCAPendingRights The rights have not yet arrived but are expected soon. sl@0: @leave KErrCANoPermission Rights exist but the specified intent is not permitted. sl@0: @leave KErrCANoRights No rights exist for the content object. sl@0: @leave KErrCANotSupported Unable to open the object with the specified UniqueId, it may be a container object. sl@0: @leave KErrPermissionDenied The agent does not allow the client to access the content object. sl@0: @leave KErrAccessDenied The content is already in use. sl@0: @leave ... 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: IMPORT_C static CData* NewLC(RFile& aFile, const TDesC& aUniqueId, TIntent aIntent); sl@0: sl@0: /** sl@0: Creates a new CData object. sl@0: sl@0: @param aFile An open RFile handle, the agent will make a duplicate of this handle. sl@0: 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. sl@0: @param aUniqueId The content object to read. sl@0: @return The new CData object. sl@0: sl@0: @leave KErrNotFound The content object with the given UniqueId does not exist. sl@0: @leave KErrCAPendingRights The rights have not yet arrived but are expected soon. sl@0: @leave KErrCANoPermission Rights exist but the specified intent is not permitted. sl@0: @leave KErrCANoRights No rights exist for the content object. sl@0: @leave KErrCANotSupported Unable to open the object with the specified UniqueId, it may be a container object. sl@0: @leave KErrPermissionDenied The agent does not allow the client to access the content object. sl@0: @leave KErrAccessDenied The content is already in use. sl@0: @leave ... 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: IMPORT_C static CData* NewLC(RFile& aFile, const TDesC& aUniqueId); sl@0: sl@0: /** sl@0: Creates a new CData object. sl@0: sl@0: @param aAgentUid The agent determined to support this content. sl@0: @param aVirtualPath The content object to read. sl@0: @param aIntent The intended use of the content. sl@0: @param aShareMode The file share mode used to open this content. sl@0: @return The new CData object. sl@0: sl@0: @leave KErrNotFound The content object with the given UniqueId does not exist. sl@0: @leave KErrCAPendingRights The rights have not yet arrived but are expected soon. sl@0: @leave KErrCANoPermission Rights exist but the specified intent is not permitted. sl@0: @leave KErrCANoRights No rights exist for the content object. sl@0: @leave KErrCANotSupported Unable to open the object with the specified UniqueId, it may be a container object. sl@0: @leave KErrPermissionDenied The agent does not allow the client to access the content object. sl@0: @leave KErrAccessDenied The content is already in use. sl@0: @leave ... 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: static CData* NewLC(TUid aAgentUid, const TVirtualPathPtr& aVirtualPath, sl@0: TIntent aIntent, TContentShareMode aShareMode); sl@0: sl@0: /** sl@0: Creates a new CData object. sl@0: sl@0: @param aAgentUid The Uid of the agent who supports this content. sl@0: @param aFile An open RFile handle, the agent will make a duplicate of this handle. sl@0: 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. sl@0: @param aUniqueId The content object to read. sl@0: @param aIntent The intended use of the content. sl@0: @return The new CData object. sl@0: sl@0: @leave KErrNotFound The content object with the given UniqueId does not exist. sl@0: @leave KErrCAPendingRights The rights have not yet arrived but are expected soon. sl@0: @leave KErrCANoPermission Rights exist but the specified intent is not permitted. sl@0: @leave KErrCANoRights No rights exist for the content object. sl@0: @leave KErrCANotSupported Unable to open the object with the specified UniqueId, it may be a container object. sl@0: @leave KErrPermissionDenied The agent does not allow the client to access the content object. sl@0: @leave KErrAccessDenied The content is already in use. sl@0: @leave ... One of the other CAF error codes defined in \c caferr.h sl@0: or one of the other system-wide error codes for sl@0: any other errors. sl@0: sl@0: */ sl@0: static CData* NewLC(TUid aAgentUid, RFile& aFile, const TDesC& aUniqueId, TIntent aIntent); sl@0: sl@0: #ifdef SYMBIAN_ENABLE_SDP_WMDRM_SUPPORT sl@0: sl@0: /** sl@0: Creates a new CData object. sl@0: @param aHeaderData Header data of WMDRM file/stream content. sl@0: @return CData object. sl@0: @leave One of the CAF error codes defined in caferr.h or one of the sl@0: system-wide error for any other errors. 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: sl@0: IMPORT_C static CData* NewL(const TDesC8& aHeaderData); sl@0: sl@0: /** sl@0: Creates a new CData object. sl@0: @param aHeaderData Header data of WMDRM file/stream content. sl@0: @param aIntent The intended use of the content. sl@0: @return CData object. sl@0: @leave One of the CAF error codes defined in caferr.h or one of the sl@0: system-wide error for any other errors. 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: sl@0: IMPORT_C static CData* NewL(const TDesC8& aHeaderData, TIntent aIntent); sl@0: sl@0: /** sl@0: Creates a new CData object. sl@0: @param aHeaderData Header data of WMDRM file/stream content. sl@0: @return CData object. sl@0: @leave One of the CAF error codes defined in caferr.h or one of the sl@0: system-wide error for any other errors. 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: sl@0: IMPORT_C static CData* NewLC(const TDesC8& aHeaderData); sl@0: sl@0: /** sl@0: Creates a new CData object. sl@0: @param aHeaderData Header data of WMDRM file/stream content. sl@0: @param aIntent The intended use of the content. sl@0: @return CData object. sl@0: @leave One of the CAF error codes defined in caferr.h or one of the sl@0: system-wide error for any other errors. 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: sl@0: IMPORT_C static CData* NewLC(const TDesC8& aHeaderData, TIntent aIntent); sl@0: sl@0: /** sl@0: Creates a new CData object. sl@0: @param aAgentUid UID of an agent which supports this content. sl@0: @param aHeaderData Header data of WMDRM file/stream content. sl@0: @param aIntent The intended use of the content. sl@0: @return CData object. sl@0: @leave One of the CAF error codes defined in caferr.h or one of the sl@0: system-wide error for any other errors. 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: */ sl@0: sl@0: static CData* NewLC(TUid aAgentUid, const TDesC8& aHeaderData, TIntent aIntent); sl@0: sl@0: #endif //SYMBIAN_ENABLE_SDP_WMDRM_SUPPORT sl@0: sl@0: /** destructor */ sl@0: virtual ~CData(); 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. sl@0: @return 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: IMPORT_C TInt Read(TDes8& aDes) const; sl@0: sl@0: /** sl@0: Reads from a content object up to the specified length of the sl@0: descriptor or the end of the content object. 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: IMPORT_C TInt Read(TDes8& aDes,TInt aLength) const; sl@0: sl@0: /** sl@0: Read content asynchronously up to the maximum length of the descriptor sl@0: or until the end of the content object is reached. sl@0: NB: It is important that the descriptor passed to sl@0: aDes remains in scope until the request has completed. 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: IMPORT_C void Read(TDes8& aDes, TRequestStatus& aStatus) const; sl@0: sl@0: /** sl@0: Read content asynchronously up to the specified length sl@0: or until the end of the content object is reached. sl@0: NB: It is important that the descriptor passed to sl@0: aDes remains in scope until the request has completed. 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: IMPORT_C void Read(TDes8& aDes, TInt aLength, TRequestStatus& aStatus) const; 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 void ReadCancel(TRequestStatus &aStatus) const; sl@0: sl@0: #ifdef SYMBIAN_ENABLE_64_BIT_FILE_SERVER_API 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: NB: It is important that the descriptor passed to sl@0: aDes remains in scope until the request has completed. sl@0: If agent does not support 64bit, fallback to 32bit Read is provided automatically by CAF 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 KErrArgument if a negative offset is supplied. 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 TInt Read(TInt64 aPos, TDes8& aDes, TInt aLength, TRequestStatus& aStatus) const; sl@0: #else 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 KErrArgument if a negative offset is supplied. 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 TInt Read(TInt aPos, TDes8& aDes, TInt aLength, TRequestStatus& aStatus) const; sl@0: #endif //SYMBIAN_ENABLE_64_BIT_FILE_SERVER_API sl@0: 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: IMPORT_C void DataSizeL(TInt& aSize); sl@0: sl@0: #ifdef SYMBIAN_ENABLE_64_BIT_FILE_SERVER_API sl@0: /** sl@0: This is the 64bit version of CData::DataSizeL sl@0: Client can call this function instead of CData::DataSizeL. If it's not implemented by the agent, sl@0: fallback to 32bit counterpart will be provided automatically sl@0: sl@0: @see DataSizeL(TInt& aSize) sl@0: */ sl@0: IMPORT_C void DataSize64L(TInt64& aSize); sl@0: #endif //SYMBIAN_ENABLE_64_BIT_FILE_SERVER_API 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: NOTE: Some operations may fail if the content data is sourced over a network connection. 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: IMPORT_C TInt Seek(TSeek aMode,TInt& aPos) const; sl@0: sl@0: #ifdef SYMBIAN_ENABLE_64_BIT_FILE_SERVER_API sl@0: /** sl@0: This is the 64bit version of CData::Seek sl@0: Client can call this function instead of CData::Seek. If it's not implemented by the agent, sl@0: fallback to 32bit counterpart will be provided automatically sl@0: sl@0: @see Seek(TSeek aMode,TInt& aPos) sl@0: */ sl@0: IMPORT_C TInt Seek64(TSeek aMode,TInt64& aPos) const; sl@0: #endif //SYMBIAN_ENABLE_64_BIT_FILE_SERVER_API sl@0: sl@0: /** Request the agent handling this content to set a property value. If the property is set sl@0: it is only set for this CData session and does not impact other CAF users. sl@0: sl@0: For example setting the buffer-size to 256 bytes can be achieved as follows: sl@0: sl@0: @code sl@0: MyData->SetProperty(EAgentPropertyBufferSize, 256); sl@0: @endcode sl@0: sl@0: @see ContentAccess::TAgentProperty 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: IMPORT_C TInt SetProperty(TAgentProperty aProperty, TInt aValue); 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: @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: @see ContentAccess::TIntent 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: @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 TInt EvaluateIntent(TIntent aIntent); 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 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: IMPORT_C TInt ExecuteIntent(TIntent aIntent); sl@0: sl@0: /** Get an attribute for the content object sl@0: sl@0: @see ContentAccess::TAttribute sl@0: sl@0: @code sl@0: CContent* content = CContent::NewL(uri); sl@0: CData* data = content->OpenContentL(EPlay, uniqueId); sl@0: delete content; sl@0: sl@0: TInt value = 0; sl@0: TInt err = data->GetAttribute(EIsProtected, value); sl@0: if(err == KErrNone && value) sl@0: { sl@0: DisplayPadLock(); sl@0: } sl@0: sl@0: delete data; sl@0: @endcode 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: IMPORT_C TInt GetAttribute(TInt aAttribute, TInt& aValue) const; sl@0: sl@0: /** Get a set of attributes for the content object sl@0: sl@0: @see ContentAccess::TAttribute sl@0: sl@0: The following example determines whether the content object sl@0: is protected and has rights that will enable it to be viewed by the sl@0: user sl@0: sl@0: @code sl@0: // CData* data = a data object sl@0: sl@0: RAttributeSet attributeSet; sl@0: CleanupClosePushL(attributeSet); sl@0: attributeSet->AddL(EProtected); sl@0: attributeSet->AddL(ECanView); sl@0: sl@0: User::LeaveIfError(data->GetAttributeSet(attributeSet); sl@0: sl@0: TInt err = attributeSet.GetValue(EProtected, value); sl@0: if(err == KErrNone && value) sl@0: { sl@0: // file is DRM protected sl@0: } sl@0: sl@0: err = attributeSet.GetValue(ECanView, value); sl@0: if(err == KErrNone && value) sl@0: { sl@0: // File has rights that allow it to be displayed on screen sl@0: } sl@0: sl@0: // Finished sl@0: CleanupStack::PopAndDestroy(); // attributeSet.Close() sl@0: @endcode sl@0: 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: IMPORT_C TInt GetAttributeSet(RAttributeSet& aAttributeSet) const; sl@0: sl@0: sl@0: /** Get text string attributes or meta-data for the content object sl@0: sl@0: @see ContentAccess::TStringAttribute sl@0: sl@0: @code sl@0: CContent* content = CContent::NewLC(uri); sl@0: CData* data = content->OpenContentLC(EPlay, uniqueId); sl@0: CleanupStack::PopAndDestroy(content); sl@0: sl@0: TBuf previewUri; sl@0: TInt err = data->GetStringAttribute(EPreviewURI, previewUri); sl@0: if(err == KErrNone) sl@0: { sl@0: DisplayPreview(previewUri); sl@0: } sl@0: sl@0: CleanupStack::PopAndDestroy(data); sl@0: @endcode 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: IMPORT_C TInt GetStringAttribute(TInt aAttribute, TDes& aValue) const; sl@0: sl@0: sl@0: sl@0: /** Obtain a set of string attributes for the content object sl@0: sl@0: @see ContentAccess::TStringAttribute sl@0: sl@0: @code sl@0: CContent* content = CContent::NewLC(uri); sl@0: CData* data = content->OpenContentLC(EPlay, uniqueId); sl@0: sl@0: // create the attribute set, add the attributes we are interested in sl@0: RStringAttributeSet stringAttributeSet; sl@0: CleanupClosePushL(stringAttributeSet); sl@0: stringAttributeSet.AddL(EPreviewURI); sl@0: stringAttributeSet.AddL(ETitle); sl@0: sl@0: User::LeaveIfError(data->GetStringAttributeSet(stringAttributeSet)); sl@0: sl@0: // Pass the value of the string attribute to DisplayPreview() sl@0: TFileName previewUri; sl@0: TInt err = stringAttributeSet.GetValue(EPreviewURI, previewUri); sl@0: if(err == KErrNone) sl@0: { sl@0: DisplayPreview(previewUri); sl@0: } sl@0: sl@0: CleanupStack::PopAndDestroy(3); // content, data, stringAttributeSet sl@0: @endcode sl@0: 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: IMPORT_C TInt GetStringAttributeSet(RStringAttributeSet& aStringAttributeSet) const; sl@0: sl@0: sl@0: #ifndef REMOVE_CAF1 sl@0: /** Set Qos attribute sl@0: @param aQosAttr The Qos attribute to set. sl@0: @param aValue The value of the attribute. sl@0: @deprecated sl@0: */ sl@0: IMPORT_C void SetQosL(TQosAttribute aQosAttr, TInt aValue); sl@0: sl@0: /** Get the mime type of the content sl@0: @param aMimeType Buffer to store the mime type provided by the agent. sl@0: @return ETrue if the mime type was retrieved successfully. sl@0: @deprecated sl@0: */ sl@0: IMPORT_C TBool GetMimeTypeL(TDes8& aMimeType) const; sl@0: #endif // REMOVE_CAF1 sl@0: sl@0: #ifdef SYMBIAN_ENABLE_SDP_WMDRM_SUPPORT sl@0: /** sl@0: Decrypts the encrypted input data packet. 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.KErrInsufficientDataPacketLength if a part of input packet is provided, sl@0: 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: sl@0: IMPORT_C TInt Read(const TDesC8& aEncryptedInputDataPacket, TDes8& aDecryptedOutputDataPacket) const; sl@0: sl@0: /** sl@0: Decrypts the encrypted input data packet asynchronously. 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.KErrInsufficientDataPacketLength if a sl@0: part of input packet is provided, 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 void Read(const TDesC8& aEncryptedInputDataPacket, TDes8& aDecryptedOutputDataPacket, TRequestStatus& aStatus) const; sl@0: sl@0: #endif //#ifdef SYMBIAN_ENABLE_SDP_WMDRM_SUPPORT sl@0: sl@0: private: sl@0: CData(); sl@0: void ConstructL(RFile& aFile, const TDesC& aUniqueId, TIntent aIntent); sl@0: void ConstructL(const TVirtualPathPtr& aVirtualPath, TIntent aIntent, TContentShareMode aShareMode); sl@0: void ConstructL(TUid aAgentUid, RFile& aFile, const TDesC& aUniqueId, TIntent aIntent); sl@0: void ConstructL(TUid aAgentUid, const TVirtualPathPtr& aVirtualPath, TIntent aIntent, TContentShareMode aShareMode); sl@0: sl@0: void ConstructL(RFile& aFile, const TDesC& aUniqueId); sl@0: void ConstructL(const TVirtualPathPtr& aVirtualPath, TContentShareMode aShareMode); sl@0: void ConstructL(TUid aAgentUid, RFile& aFile, const TDesC& aUniqueId); sl@0: void ConstructL(TUid aAgentUid, const TVirtualPathPtr& aVirtualPath, TContentShareMode aShareMode); sl@0: sl@0: #ifdef SYMBIAN_ENABLE_SDP_WMDRM_SUPPORT sl@0: sl@0: void ConstructL(TUid aAgentUid, const TDesC8& aHeaderData, TIntent aIntent); sl@0: void ConstructL(const TDesC8& aHeaderData); sl@0: void ConstructL(const TDesC8& aHeaderData, TIntent aIntent); sl@0: void ConstructL(TUid aAgentUid, const TDesC8& aHeaderData); sl@0: sl@0: #endif //#ifdef SYMBIAN_ENABLE_SDP_WMDRM_SUPPORT sl@0: sl@0: #ifdef SYMBIAN_ENABLE_64_BIT_FILE_SERVER_API sl@0: /* sl@0: * This is the obselete 32bit Read and replaced by its 64bit counterpart sl@0: * TInt Read(TInt64 aPos, TDes8& aDes, TInt aLength, TRequestStatus& aStatus) const sl@0: * However, this function still exits at its original ordinal to avoid BC break. sl@0: * Upgrade to 64bit Read is done automatically upon recompling the client code which uses CAF interfaces sl@0: */ sl@0: IMPORT_C TInt Read_Unused(TInt aPos, TDes8& aDes, TInt aLength, TRequestStatus& aStatus) const; sl@0: #endif //SYMBIAN_ENABLE_64_BIT_FILE_SERVER_API sl@0: sl@0: private: sl@0: // The agent handling this content sl@0: CAgentData* iAgentData; sl@0: sl@0: // Defacto ECOM session handle sl@0: CAgentFactory* iAgentFactory; sl@0: sl@0: // Uid of the agent sl@0: TUid iAgentUid; sl@0: }; sl@0: sl@0: } // namespace ContentAccess sl@0: #endif /* __DATA_H__ */ sl@0: