williamr@2: /* williamr@4: * Copyright (c) 2003-2008 Nokia Corporation and/or its subsidiary(-ies). williamr@2: * All rights reserved. williamr@2: * This component and the accompanying materials are made available williamr@2: * under the terms of the License "Eclipse Public License v1.0" williamr@2: * which accompanies this distribution, and is available williamr@2: * at the URL "http://www.eclipse.org/legal/epl-v10.html". williamr@2: * williamr@2: * Initial Contributors: williamr@2: * Nokia Corporation - initial contribution. williamr@2: * williamr@2: * Contributors: williamr@2: * williamr@2: * Description: williamr@2: * williamr@2: */ williamr@2: williamr@2: williamr@2: williamr@2: /** williamr@2: @file williamr@2: williamr@4: @publishedAll williamr@2: @released williamr@2: */ williamr@2: williamr@2: williamr@2: #ifndef __DATA_H__ williamr@2: #define __DATA_H__ williamr@2: williamr@2: #include williamr@2: #include williamr@2: #include williamr@2: williamr@2: namespace ContentAccess williamr@2: { williamr@2: class CAgentFactory; williamr@2: class CAgentInfo; williamr@2: class TVirtualPathPtr; williamr@2: class CAgentData; williamr@2: class RAttributeSet; williamr@2: class RStringAttributeSet; williamr@2: williamr@2: williamr@2: /** williamr@2: Allows clients to read data from a content object. williamr@2: williamr@2: This class is initialised with an agent implementation that is williamr@2: responsible for this content object. williamr@2: williamr@2: */ williamr@2: class CData : public CBase williamr@2: { williamr@2: public: williamr@2: /** williamr@2: Creates a new CData object. williamr@2: williamr@2: @param aVirtualPath The content object to read williamr@2: @param aIntent The intended use of the content. williamr@2: @param aShareMode The file share mode used to open this content. williamr@2: @return The new CData object. williamr@2: williamr@2: @leave KErrNotFound The content object with the given UniqueId does not exist. williamr@2: @leave KErrCAPendingRights The rights have not yet arrived but are expected soon. williamr@2: @leave KErrCANoPermission Rights exist but the specified intent is not permitted. williamr@2: @leave KErrCANoRights No rights exist for the content object. williamr@2: @leave KErrCANotSupported Unable to open the object with the specified UniqueId, it may be a container object. williamr@2: @leave KErrPermissionDenied The agent does not allow the client to access the content object. williamr@2: @leave KErrAccessDenied The content is already in use. williamr@2: @leave ... One of the other CAF error codes defined in \c caferr.h williamr@2: or one of the other system-wide error codes williamr@2: for any other errors. williamr@2: */ williamr@2: IMPORT_C static CData* NewL(const TVirtualPathPtr& aVirtualPath, williamr@2: TIntent aIntent, TContentShareMode aShareMode); williamr@2: williamr@2: /** williamr@2: Creates a new CData object. williamr@2: williamr@2: @param aVirtualPath The content object to read. williamr@2: @param aShareMode The file share mode used to open this content. williamr@2: @return The new CData object. williamr@2: williamr@2: @leave KErrNotFound The content object with the given UniqueId does not exist. williamr@2: @leave KErrCAPendingRights The rights have not yet arrived but are expected soon. williamr@2: @leave KErrCANoPermission Rights exist but the specified intent is not permitted. williamr@2: @leave KErrCANoRights No rights exist for the content object. williamr@2: @leave KErrCANotSupported Unable to open the object with the specified UniqueId, it may be a container object. williamr@2: @leave KErrPermissionDenied The agent does not allow the client to access the content object. williamr@2: @leave KErrAccessDenied The content is already in use. williamr@2: @leave ... One of the other CAF error codes defined in \c caferr.h williamr@2: or one of the other system-wide error codes for williamr@2: any other errors. williamr@2: */ williamr@2: IMPORT_C static CData* NewL(const TVirtualPathPtr& aVirtualPath, williamr@2: TContentShareMode aShareMode); williamr@2: williamr@2: williamr@2: /** williamr@2: Creates a new CData object williamr@2: williamr@2: @param aVirtualPath The content object to read. williamr@2: @param aIntent The intended use of the content. williamr@2: @param aShareMode The file share mode used to open this content. williamr@2: @return The new CData object. williamr@2: williamr@2: @leave KErrNotFound The content object with the given UniqueId does not exist. williamr@2: @leave KErrCAPendingRights The rights have not yet arrived but are expected soon. williamr@2: @leave KErrCANoPermission Rights exist but the specified intent is not permitted. williamr@2: @leave KErrCANoRights No rights exist for the content object. williamr@2: @leave KErrCANotSupported Unable to open the object with the specified UniqueId, it may be a container object. williamr@2: @leave KErrPermissionDenied The agent does not allow the client to access the content object. williamr@2: @leave KErrAccessDenied The content is already in use. williamr@2: @leave ... One of the other CAF error codes defined in \c caferr.h williamr@2: or one of the other system-wide error codes for williamr@2: any other errors. williamr@2: */ williamr@2: IMPORT_C static CData* NewLC(const TVirtualPathPtr& aVirtualPath, williamr@2: TIntent aIntent, TContentShareMode aShareMode); williamr@2: williamr@2: /** williamr@2: Creates a new CData object williamr@2: williamr@2: @param aVirtualPath The content object to read. williamr@2: @param aShareMode The file share mode used to open this content. williamr@2: @return The new CData object. williamr@2: williamr@2: @leave KErrNotFound The content object with the given UniqueId does not exist. williamr@2: @leave KErrCAPendingRights The rights have not yet arrived but are expected soon. williamr@2: @leave KErrCANoPermission Rights exist but the specified intent is not permitted. williamr@2: @leave KErrCANoRights No rights exist for the content object. williamr@2: @leave KErrCANotSupported Unable to open the object with the specified UniqueId, it may be a container object. williamr@2: @leave KErrPermissionDenied The agent does not allow the client to access the content object. williamr@2: @leave KErrAccessDenied The content is already in use. williamr@2: @leave ... One of the other CAF error codes defined in \c caferr.h williamr@2: or one of the other system-wide error codes for williamr@2: any other errors. williamr@2: */ williamr@2: IMPORT_C static CData* NewLC(const TVirtualPathPtr& aVirtualPath, williamr@2: TContentShareMode aShareMode); williamr@2: williamr@2: williamr@2: /** williamr@2: Creates a new CData object. williamr@2: williamr@2: @param aFile An open RFile handle, the agent will make a duplicate of this handle. williamr@2: 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. williamr@2: @param aUniqueId The content object to read. williamr@2: @param aIntent The intended use of the content. williamr@2: @return The new CData object. williamr@2: williamr@2: @leave KErrNotFound The content object with the given UniqueId does not exist. williamr@2: @leave KErrCAPendingRights The rights have not yet arrived but are expected soon. williamr@2: @leave KErrCANoPermission Rights exist but the specified intent is not permitted. williamr@2: @leave KErrCANoRights No rights exist for the content object. williamr@2: @leave KErrCANotSupported Unable to open the object with the specified UniqueId, it may be a container object. williamr@2: @leave KErrPermissionDenied The agent does not allow the client to access the content object. williamr@2: @leave KErrAccessDenied The content is already in use. williamr@2: @leave ... One of the other CAF error codes defined in \c caferr.h williamr@2: or one of the other system-wide error codes for williamr@2: any other errors. williamr@2: */ williamr@2: IMPORT_C static CData* NewL(RFile& aFile, const TDesC& aUniqueId, TIntent aIntent); williamr@2: williamr@2: /** williamr@2: Creates a new CData object. williamr@2: williamr@2: @param aFile An open RFile handle, the agent will make a duplicate of this handle. williamr@2: 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. williamr@2: @param aUniqueId The content object to read. williamr@2: @return The new CData object. williamr@2: williamr@2: @leave KErrNotFound The content object with the given UniqueId does not exist. williamr@2: @leave KErrCAPendingRights The rights have not yet arrived but are expected soon. williamr@2: @leave KErrCANoPermission Rights exist but the specified intent is not permitted. williamr@2: @leave KErrCANoRights No rights exist for the content object. williamr@2: @leave KErrCANotSupported Unable to open the object with the specified UniqueId, it may be a container object. williamr@2: @leave KErrPermissionDenied The agent does not allow the client to access the content object. williamr@2: @leave KErrAccessDenied The content is already in use. williamr@2: @leave ... One of the other CAF error codes defined in \c caferr.h williamr@2: or one of the other system-wide error codes for williamr@2: any other errors. williamr@2: */ williamr@2: IMPORT_C static CData* NewL(RFile& aFile, const TDesC& aUniqueId); williamr@2: williamr@2: /** williamr@2: Creates a new CData object. williamr@2: williamr@2: @param aFile An open RFile handle, the agent will make a duplicate of this handle. williamr@2: 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. williamr@2: @param aUniqueId The content object to read. williamr@2: @param aIntent The intended use of the content. williamr@2: @return The new CData object. williamr@2: williamr@2: @leave KErrNotFound The content object with the given UniqueId does not exist. williamr@2: @leave KErrCAPendingRights The rights have not yet arrived but are expected soon. williamr@2: @leave KErrCANoPermission Rights exist but the specified intent is not permitted. williamr@2: @leave KErrCANoRights No rights exist for the content object. williamr@2: @leave KErrCANotSupported Unable to open the object with the specified UniqueId, it may be a container object. williamr@2: @leave KErrPermissionDenied The agent does not allow the client to access the content object. williamr@2: @leave KErrAccessDenied The content is already in use. williamr@2: @leave ... One of the other CAF error codes defined in \c caferr.h williamr@2: or one of the other system-wide error codes williamr@2: for any other errors. williamr@2: */ williamr@2: IMPORT_C static CData* NewLC(RFile& aFile, const TDesC& aUniqueId, TIntent aIntent); williamr@2: williamr@2: /** williamr@2: Creates a new CData object. williamr@2: williamr@2: @param aFile An open RFile handle, the agent will make a duplicate of this handle. williamr@2: 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. williamr@2: @param aUniqueId The content object to read. williamr@2: @return The new CData object. williamr@2: williamr@2: @leave KErrNotFound The content object with the given UniqueId does not exist. williamr@2: @leave KErrCAPendingRights The rights have not yet arrived but are expected soon. williamr@2: @leave KErrCANoPermission Rights exist but the specified intent is not permitted. williamr@2: @leave KErrCANoRights No rights exist for the content object. williamr@2: @leave KErrCANotSupported Unable to open the object with the specified UniqueId, it may be a container object. williamr@2: @leave KErrPermissionDenied The agent does not allow the client to access the content object. williamr@2: @leave KErrAccessDenied The content is already in use. williamr@2: @leave ... One of the other CAF error codes defined in \c caferr.h williamr@2: or one of the other system-wide error codes williamr@2: for any other errors. williamr@2: */ williamr@2: IMPORT_C static CData* NewLC(RFile& aFile, const TDesC& aUniqueId); williamr@2: williamr@2: /** williamr@2: Creates a new CData object. williamr@2: williamr@2: @param aAgentUid The agent determined to support this content. williamr@2: @param aVirtualPath The content object to read. williamr@2: @param aIntent The intended use of the content. williamr@2: @param aShareMode The file share mode used to open this content. williamr@2: @return The new CData object. williamr@2: williamr@2: @leave KErrNotFound The content object with the given UniqueId does not exist. williamr@2: @leave KErrCAPendingRights The rights have not yet arrived but are expected soon. williamr@2: @leave KErrCANoPermission Rights exist but the specified intent is not permitted. williamr@2: @leave KErrCANoRights No rights exist for the content object. williamr@2: @leave KErrCANotSupported Unable to open the object with the specified UniqueId, it may be a container object. williamr@2: @leave KErrPermissionDenied The agent does not allow the client to access the content object. williamr@2: @leave KErrAccessDenied The content is already in use. williamr@2: @leave ... One of the other CAF error codes defined in \c caferr.h williamr@2: or one of the other system-wide error codes williamr@2: for any other errors. williamr@2: */ williamr@2: static CData* NewLC(TUid aAgentUid, const TVirtualPathPtr& aVirtualPath, williamr@2: TIntent aIntent, TContentShareMode aShareMode); williamr@2: williamr@2: /** williamr@2: Creates a new CData object. williamr@2: williamr@2: @param aAgentUid The Uid of the agent who supports this content. williamr@2: @param aFile An open RFile handle, the agent will make a duplicate of this handle. williamr@2: 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. williamr@2: @param aUniqueId The content object to read. williamr@2: @param aIntent The intended use of the content. williamr@2: @return The new CData object. williamr@2: williamr@2: @leave KErrNotFound The content object with the given UniqueId does not exist. williamr@2: @leave KErrCAPendingRights The rights have not yet arrived but are expected soon. williamr@2: @leave KErrCANoPermission Rights exist but the specified intent is not permitted. williamr@2: @leave KErrCANoRights No rights exist for the content object. williamr@2: @leave KErrCANotSupported Unable to open the object with the specified UniqueId, it may be a container object. williamr@2: @leave KErrPermissionDenied The agent does not allow the client to access the content object. williamr@2: @leave KErrAccessDenied The content is already in use. williamr@2: @leave ... One of the other CAF error codes defined in \c caferr.h williamr@2: or one of the other system-wide error codes for williamr@2: any other errors. williamr@2: williamr@2: */ williamr@2: static CData* NewLC(TUid aAgentUid, RFile& aFile, const TDesC& aUniqueId, TIntent aIntent); williamr@4: williamr@4: #ifdef SYMBIAN_ENABLE_SDP_WMDRM_SUPPORT williamr@2: williamr@4: /** williamr@4: Creates a new CData object. williamr@4: @param aHeaderData Header data of WMDRM file/stream content. williamr@4: @return CData object. williamr@4: @leave One of the CAF error codes defined in caferr.h or one of the williamr@4: system-wide error for any other errors. williamr@4: @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. williamr@4: Access to unprotected content is unrestricted. williamr@4: */ williamr@4: williamr@4: IMPORT_C static CData* NewL(const TDesC8& aHeaderData); williamr@4: williamr@4: /** williamr@4: Creates a new CData object. williamr@4: @param aHeaderData Header data of WMDRM file/stream content. williamr@4: @param aIntent The intended use of the content. williamr@4: @return CData object. williamr@4: @leave One of the CAF error codes defined in caferr.h or one of the williamr@4: system-wide error for any other errors. williamr@4: @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. williamr@4: Access to unprotected content is unrestricted. williamr@4: */ williamr@4: williamr@4: IMPORT_C static CData* NewL(const TDesC8& aHeaderData, TIntent aIntent); williamr@4: williamr@4: /** williamr@4: Creates a new CData object. williamr@4: @param aHeaderData Header data of WMDRM file/stream content. williamr@4: @return CData object. williamr@4: @leave One of the CAF error codes defined in caferr.h or one of the williamr@4: system-wide error for any other errors. williamr@4: @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. williamr@4: Access to unprotected content is unrestricted. williamr@4: */ williamr@4: williamr@4: IMPORT_C static CData* NewLC(const TDesC8& aHeaderData); williamr@4: williamr@4: /** williamr@4: Creates a new CData object. williamr@4: @param aHeaderData Header data of WMDRM file/stream content. williamr@4: @param aIntent The intended use of the content. williamr@4: @return CData object. williamr@4: @leave One of the CAF error codes defined in caferr.h or one of the williamr@4: system-wide error for any other errors. williamr@4: @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. williamr@4: Access to unprotected content is unrestricted. williamr@4: */ williamr@4: williamr@4: IMPORT_C static CData* NewLC(const TDesC8& aHeaderData, TIntent aIntent); williamr@4: williamr@4: /** williamr@4: Creates a new CData object. williamr@4: @param aAgentUid UID of an agent which supports this content. williamr@4: @param aHeaderData Header data of WMDRM file/stream content. williamr@4: @param aIntent The intended use of the content. williamr@4: @return CData object. williamr@4: @leave One of the CAF error codes defined in caferr.h or one of the williamr@4: system-wide error for any other errors. williamr@4: @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. williamr@4: Access to unprotected content is unrestricted. williamr@4: williamr@4: */ williamr@4: williamr@4: static CData* NewLC(TUid aAgentUid, const TDesC8& aHeaderData, TIntent aIntent); williamr@4: williamr@4: #endif //SYMBIAN_ENABLE_SDP_WMDRM_SUPPORT williamr@4: williamr@2: /** destructor */ williamr@2: virtual ~CData(); williamr@2: williamr@2: /** williamr@2: Reads from a content object up to the maximum length of the williamr@2: descriptor or the end of the content object. williamr@2: williamr@2: When an attempt is made to read beyond the end of the content, williamr@2: no error is returned. The descriptor’s length is set to the williamr@2: number of bytes that were read into it. Therefore, when reading williamr@2: through content, the end has been reached when the williamr@2: descriptor length (given by TDesC::Length()) is zero. williamr@2: williamr@2: @param aDes Descriptor into which binary data is read. Any existing williamr@2: contents are overwritten. On return, its length is set williamr@2: to the number of bytes read. williamr@2: @return KErrNone if successful. williamr@2: @return One of the CAF error codes defined in \c caferr.h or williamr@2: one of the other system-wide error codes. williamr@2: @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted williamr@2: */ williamr@2: IMPORT_C TInt Read(TDes8& aDes) const; williamr@2: williamr@2: /** williamr@2: Reads from a content object up to the specified length of the williamr@2: descriptor or the end of the content object. williamr@2: williamr@2: @see Read(TDes8& aDes) williamr@2: williamr@2: @param aDes Descriptor into which binary data is read. Any existing williamr@2: contents are overwritten. On return, its length is set williamr@2: to the number of bytes read. williamr@2: @param aLength The number of bytes to read from the file, williamr@2: or to the end of the file, whichever is encountered first. williamr@2: The length of the buffer is set to the number of bytes actually read. williamr@2: @return KErrNone if successful. williamr@2: @return Otherwise one of the CAF error codes defined in \c caferr.h or williamr@2: one of the other system-wide error codes. williamr@2: @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted williamr@2: */ williamr@2: IMPORT_C TInt Read(TDes8& aDes,TInt aLength) const; williamr@2: williamr@2: /** williamr@2: Read content asynchronously up to the maximum length of the descriptor williamr@2: or until the end of the content object is reached. williamr@2: NB: It is important that the descriptor passed to williamr@2: aDes remains in scope until the request has completed. williamr@2: williamr@2: @see Read(TDes8& aDes) williamr@2: williamr@2: @param aDes Descriptor into which binary data is read. Any williamr@2: existing contents are overwritten. On return, williamr@2: its length is set to the number of bytes read. williamr@2: @param aStatus Asynchronous request status. On completion this will contain one williamr@2: of the following error codes: KErrNone if the data was williamr@2: successfully read. Otherwise one of the CAF error codes defined in williamr@2: \c caferr.h or one of the other standard system-wide williamr@2: error codes for any other errors. williamr@2: @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted williamr@2: */ williamr@2: IMPORT_C void Read(TDes8& aDes, TRequestStatus& aStatus) const; williamr@2: williamr@2: /** williamr@2: Read content asynchronously up to the specified length williamr@2: or until the end of the content object is reached. williamr@2: NB: It is important that the descriptor passed to williamr@2: aDes remains in scope until the request has completed. williamr@2: williamr@2: @see Read(TDes8& aDes) williamr@2: williamr@2: @param aDes Descriptor into which binary data is read. Any williamr@2: existing contents are overwritten. On return, williamr@2: its length is set to the number of bytes read. williamr@2: @param aLength The number of bytes to read from the file, williamr@2: or to the end of the file, whichever is encountered first. williamr@2: The length of the buffer is set to the number of bytes actually read. williamr@2: @param aStatus Asynchronous request status. On completion this will contain one williamr@2: of the following error codes: KErrNone if the data was williamr@2: successfully read. Otherwise one of the CAF error codes defined in williamr@2: \c caferr.h or one of the other standard system-wide williamr@2: error codes for any other errors. williamr@2: @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted williamr@2: */ williamr@2: IMPORT_C void Read(TDes8& aDes, TInt aLength, TRequestStatus& aStatus) const; williamr@2: williamr@2: /** williamr@2: Cancels asynchronous read. williamr@2: williamr@2: @param aStatus Asynchronous request status. This parameter should have been supplied earlier to williamr@2: an asynchronous Read call. If it has not been previously supplied to a Read call, williamr@2: this function will not have any effect. williamr@2: @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted williamr@2: */ williamr@2: IMPORT_C void ReadCancel(TRequestStatus &aStatus) const; williamr@2: williamr@4: #ifdef SYMBIAN_ENABLE_64_BIT_FILE_SERVER_API williamr@2: /** williamr@2: Reads content asynchronously. The data is read from a specified offset williamr@2: up to a specified number of bytes or until the end of the content object williamr@2: is reached. The data is read into the descriptor buffer supplied. williamr@2: NB: It is important that the descriptor passed to williamr@4: aDes remains in scope until the request has completed. williamr@4: If agent does not support 64bit, fallback to 32bit Read is provided automatically by CAF williamr@4: williamr@2: @see Read(TDes8& aDes) williamr@4: williamr@2: @param aPos Position of first byte to be read. williamr@4: This is an offset from the start of the file. williamr@2: @param aDes Descriptor into which binary data is read. Any williamr@2: existing contents are overwritten. On return, williamr@2: its length is set to the number of bytes read. williamr@2: @param aLength The number of bytes to read from the file, williamr@2: or to the end of the file, whichever is encountered first. williamr@2: The length of the buffer is set to the number of bytes actually read. williamr@2: @param aStatus Asynchronous request status. On completion this will contain one williamr@2: of the following error codes: KErrNone if the data was williamr@2: successfully read. Otherwise one of the CAF error codes defined in williamr@2: \c caferr.h or one of the other standard system-wide williamr@2: error codes for any other errors. williamr@2: @return KErrNone if the async read request was successfully submitted. williamr@2: @return KErrArgument if a negative offset is supplied. williamr@2: @return KErrCANotSupported if the agent does not support this operation. williamr@2: @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted williamr@4: */ williamr@4: IMPORT_C TInt Read(TInt64 aPos, TDes8& aDes, TInt aLength, TRequestStatus& aStatus) const; williamr@4: #else williamr@4: /** williamr@4: Reads content asynchronously. The data is read from a specified offset williamr@4: up to a specified number of bytes or until the end of the content object williamr@4: is reached. The data is read into the descriptor buffer supplied. williamr@4: williamr@4: @see Read(TDes8& aDes) williamr@4: williamr@4: @param aPos Position of first byte to be read. williamr@4: This is an offset from the start of the file. williamr@4: @param aDes Descriptor into which binary data is read. Any williamr@4: existing contents are overwritten. On return, williamr@4: its length is set to the number of bytes read. williamr@4: @param aLength The number of bytes to read from the file, williamr@4: or to the end of the file, whichever is encountered first. williamr@4: The length of the buffer is set to the number of bytes actually read. williamr@4: @param aStatus Asynchronous request status. On completion this will contain one williamr@4: of the following error codes: KErrNone if the data was williamr@4: successfully read. Otherwise one of the CAF error codes defined in williamr@4: \c caferr.h or one of the other standard system-wide williamr@4: error codes for any other errors. williamr@4: @return KErrNone if the async read request was successfully submitted. williamr@4: @return KErrArgument if a negative offset is supplied. williamr@4: @return KErrCANotSupported if the agent does not support this operation. williamr@4: @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted williamr@4: */ williamr@2: IMPORT_C TInt Read(TInt aPos, TDes8& aDes, TInt aLength, TRequestStatus& aStatus) const; williamr@4: #endif //SYMBIAN_ENABLE_64_BIT_FILE_SERVER_API williamr@4: williamr@2: /** williamr@2: Gets the data size in bytes. williamr@2: williamr@2: @param aSize On return this will contain the size of the plaintext data in bytes. williamr@2: @leave KErrCASizeNotDetermined Size could not be determined by the managing agent. williamr@2: @leave ... One of the other CAF error codes defined in \c caferr.h or one of the williamr@2: system-wide error codes for any other errors. williamr@2: @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted williamr@2: */ williamr@2: IMPORT_C void DataSizeL(TInt& aSize); williamr@2: williamr@4: #ifdef SYMBIAN_ENABLE_64_BIT_FILE_SERVER_API williamr@4: /** williamr@4: This is the 64bit version of CData::DataSizeL williamr@4: Client can call this function instead of CData::DataSizeL. If it's not implemented by the agent, williamr@4: fallback to 32bit counterpart will be provided automatically williamr@4: williamr@4: @see DataSizeL(TInt& aSize) williamr@4: */ williamr@4: IMPORT_C void DataSize64L(TInt64& aSize); williamr@4: #endif //SYMBIAN_ENABLE_64_BIT_FILE_SERVER_API williamr@4: williamr@2: /** williamr@2: Changes or retrieves the location of the file pointer within williamr@2: the content object. williamr@2: williamr@2: NOTE: Some operations may fail if the content data is sourced over a network connection. williamr@2: williamr@2: There are four seek modes used: williamr@2: williamr@2: @li ESeekStart - Sets the file pointer aPos bytes from the start of the williamr@2: content object. aPos is not modified by the call to Seek() williamr@2: @li ESeekEnd - Sets the file pointer aPos bytes from the end of the williamr@2: content object. The aPos parameter supplied should be zero or negative williamr@2: when using ESeekEnd. Upon completion aPos is updated with the current williamr@2: position relative to the start of the content object. williamr@2: @li ESeekCurrent - Moves the file pointer aPos bytes from the current williamr@2: position. Upon completion aPos is updated with the new position relative williamr@2: to the start of the content object. Suppling a zero value for the aPos Parameter can be williamr@2: used to retrieve the current file pointer location williamr@2: @li ESeekAddress Sets the aPos parameter to the address of the byte williamr@2: aPos bytes from the start of the content object williamr@2: williamr@2: @see TSeek williamr@2: williamr@2: @param aMode Seek mode - controls the destination of the williamr@2: seek operation. williamr@2: williamr@2: @param aPos Offset from either the start, end or current position depending upon williamr@2: the seek mode. Negative offsets are used to seek before the current position or williamr@2: relative to the end of the file. williamr@2: williamr@2: @return KErrNone if successful. williamr@2: @return Otherwise one of the CAF error codes defined in \c caferr.h or one williamr@2: of the other system-wide error codes. williamr@2: @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted williamr@2: */ williamr@2: IMPORT_C TInt Seek(TSeek aMode,TInt& aPos) const; williamr@2: williamr@4: #ifdef SYMBIAN_ENABLE_64_BIT_FILE_SERVER_API williamr@4: /** williamr@4: This is the 64bit version of CData::Seek williamr@4: Client can call this function instead of CData::Seek. If it's not implemented by the agent, williamr@4: fallback to 32bit counterpart will be provided automatically williamr@4: williamr@4: @see Seek(TSeek aMode,TInt& aPos) williamr@4: */ williamr@4: IMPORT_C TInt Seek64(TSeek aMode,TInt64& aPos) const; williamr@4: #endif //SYMBIAN_ENABLE_64_BIT_FILE_SERVER_API williamr@2: williamr@2: /** Request the agent handling this content to set a property value. If the property is set williamr@2: it is only set for this CData session and does not impact other CAF users. williamr@2: williamr@2: For example setting the buffer-size to 256 bytes can be achieved as follows: williamr@2: williamr@2: @code williamr@2: MyData->SetProperty(EAgentPropertyBufferSize, 256); williamr@2: @endcode williamr@2: williamr@2: @see ContentAccess::TAgentProperty williamr@2: williamr@2: @param aProperty The property to set. williamr@2: @param aValue The value of the property. williamr@2: @return Whether or not the property was set. williamr@2: @return KErrNone if the property was set. williamr@2: @return KErrCANotSupported if the agent does not support the property or value. williamr@2: @return KErrAccessDenied if the agent does not permit the property to be changed. williamr@2: @return KErrPermissionDenied if the application does not have the necessary capability to change the property. williamr@2: @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted. williamr@2: */ williamr@2: IMPORT_C TInt SetProperty(TAgentProperty aProperty, TInt aValue); williamr@2: williamr@2: /** williamr@2: Allows a client to verify that the intent is supported by the williamr@2: current rights for the data object. williamr@2: williamr@2: @note Since the intent is only evaluated the agent will not decrement williamr@2: any rights-state such as play counts. williamr@2: williamr@2: @see ContentAccess::TIntent williamr@2: williamr@2: @param aIntent The intended way the content will be used. williamr@2: @return Whether rights exist allowing the content to be used for this intent. williamr@2: @return KErrNone if the intent is permitted. williamr@2: @return KErrNoRights if no rights exist for the specified content object. williamr@2: @return KErrCANoPermission if rights exist but the specified intent is not permitted. williamr@2: @return KErrCAPendingRights if the rights have not yet arrived but are expected soon. williamr@2: @return KErrNoPermission if rights exist but none permit the specified intent. williamr@2: @return KErrPermissionDenied if the client is not allowed to use this content object. williamr@2: @return Otherwise one of the other CAF error codes defined in \c caferr.h or one of the williamr@2: other system-wide error codes for any other errors. williamr@2: @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted williamr@2: */ williamr@2: IMPORT_C TInt EvaluateIntent(TIntent aIntent); williamr@2: williamr@2: /** williamr@2: Execute intent allows the application to signal it is about to carry out williamr@2: the specified intent on protected content.The agent will decrement applicable williamr@2: stateful rights such as play counts where necessary. williamr@2: williamr@2: Applications should be very careful to use this function correctly. williamr@2: @li If ExecuteIntent() is never called stateful rights will never be decremented. Users will be able to use the content forever williamr@2: @li If ExecuteIntent() is called too often stateful rights may be consumed prematurely. williamr@2: williamr@2: Usually it would be best to call ExecuteIntent immediately before the content williamr@2: is displayed or the instant playback begins. ExecuteIntent should not be considered a williamr@2: prerequisite for calling the Read functions. It is valid for an application to read from williamr@2: the file before calling ExecuteIntent. williamr@2: williamr@2: @note Since rights are executed here the agent will decrement any rights-state such as williamr@2: play counts that apply. williamr@2: williamr@2: @param aIntent The intent indicator. williamr@2: @return The result of attempting executing the intent. williamr@2: @return KErrNone if the intent is permitted and stateful rights may have been decremented. williamr@2: @return KErrNoRights if no rights exist for the specified content object. williamr@2: @return KErrCANoPermission if rights exist but the specified intent is not permitted. williamr@2: @return KErrCAPendingRights if the rights have not yet arrived but are expected soon. williamr@2: @return KErrNoPermission if rights exist but none permit the specified intent. williamr@2: @return KErrPermissionDenied if the client is not allowed to use this content object. williamr@2: @return Otherwise one of the other CAF error codes defined in \c caferr.h or one of the. williamr@2: other system-wide error codes for any other errors. williamr@2: @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted williamr@2: */ williamr@2: IMPORT_C TInt ExecuteIntent(TIntent aIntent); williamr@2: williamr@2: /** Get an attribute for the content object williamr@2: williamr@2: @see ContentAccess::TAttribute williamr@2: williamr@2: @code williamr@2: CContent* content = CContent::NewL(uri); williamr@2: CData* data = content->OpenContentL(EPlay, uniqueId); williamr@2: delete content; williamr@2: williamr@2: TInt value = 0; williamr@2: TInt err = data->GetAttribute(EIsProtected, value); williamr@2: if(err == KErrNone && value) williamr@2: { williamr@2: DisplayPadLock(); williamr@2: } williamr@2: williamr@2: delete data; williamr@2: @endcode williamr@2: williamr@2: @param aAttribute The attribute to query, from ContentAccess::TAttribute. williamr@2: @param aValue Used to return the attribute value. williamr@2: @return Whether the attribute was updated. williamr@2: @return KErrNone if the value of the attribute was updated. williamr@2: @return KErrCANotSupported if the requested attribute does not exist. williamr@2: @return KErrPermissionDenied if the access to the protected content is not permitted by the CAF Agent. williamr@2: @return Otherwise one of the other CAF error codes defined in \c caferr.h or one of the williamr@2: other system-wide error codes for any other errors. williamr@2: @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted williamr@2: */ williamr@2: IMPORT_C TInt GetAttribute(TInt aAttribute, TInt& aValue) const; williamr@2: williamr@2: /** Get a set of attributes for the content object williamr@2: williamr@2: @see ContentAccess::TAttribute williamr@2: williamr@2: The following example determines whether the content object williamr@2: is protected and has rights that will enable it to be viewed by the williamr@2: user williamr@2: williamr@2: @code williamr@2: // CData* data = a data object williamr@2: williamr@2: RAttributeSet attributeSet; williamr@2: CleanupClosePushL(attributeSet); williamr@2: attributeSet->AddL(EProtected); williamr@2: attributeSet->AddL(ECanView); williamr@2: williamr@2: User::LeaveIfError(data->GetAttributeSet(attributeSet); williamr@2: williamr@2: TInt err = attributeSet.GetValue(EProtected, value); williamr@2: if(err == KErrNone && value) williamr@2: { williamr@2: // file is DRM protected williamr@2: } williamr@2: williamr@2: err = attributeSet.GetValue(ECanView, value); williamr@2: if(err == KErrNone && value) williamr@2: { williamr@2: // File has rights that allow it to be displayed on screen williamr@2: } williamr@2: williamr@2: // Finished williamr@2: CleanupStack::PopAndDestroy(); // attributeSet.Close() williamr@2: @endcode williamr@2: williamr@2: williamr@2: @param aAttributeSet The set of attributes to query and update. williamr@2: @return Whether the attribute set was updated. williamr@2: @return KErrNone if the attributes were retrieved successfully. williamr@2: @return KErrPermissionDenied if the access to the protected content is not permitted by the CAF Agent. williamr@2: @return Otherwise one of the CAF error codes defined in \c caferr.h or one of the williamr@2: other system-wide error codes for any other errors. williamr@2: @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted williamr@2: */ williamr@2: IMPORT_C TInt GetAttributeSet(RAttributeSet& aAttributeSet) const; williamr@2: williamr@2: williamr@2: /** Get text string attributes or meta-data for the content object williamr@2: williamr@2: @see ContentAccess::TStringAttribute williamr@2: williamr@2: @code williamr@2: CContent* content = CContent::NewLC(uri); williamr@2: CData* data = content->OpenContentLC(EPlay, uniqueId); williamr@2: CleanupStack::PopAndDestroy(content); williamr@2: williamr@2: TBuf previewUri; williamr@2: TInt err = data->GetStringAttribute(EPreviewURI, previewUri); williamr@2: if(err == KErrNone) williamr@2: { williamr@2: DisplayPreview(previewUri); williamr@2: } williamr@2: williamr@2: CleanupStack::PopAndDestroy(data); williamr@2: @endcode williamr@2: williamr@2: @param aAttribute The attribute to query, from ContentAccess::TStringAttribute. williamr@2: @param aValue Returns the value of the attribute. williamr@2: @return Whether the value was updated. williamr@2: @return KErrNone if the attribute was retrieved. williamr@2: @return KErrOverflow if the buffer was not large enough to return the result. williamr@2: @return KErrCANotSupported if the requested attribute does not exist. williamr@2: @return KErrPermissionDenied if the access to the protected content is not permitted by the CAF Agent. williamr@2: @return Otherwise one of the other CAF error codes defined in \c caferr.h or one of the williamr@2: other system-wide error codes for any other errors. williamr@2: @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted williamr@2: */ williamr@2: IMPORT_C TInt GetStringAttribute(TInt aAttribute, TDes& aValue) const; williamr@2: williamr@2: williamr@2: williamr@2: /** Obtain a set of string attributes for the content object williamr@2: williamr@2: @see ContentAccess::TStringAttribute williamr@2: williamr@2: @code williamr@2: CContent* content = CContent::NewLC(uri); williamr@2: CData* data = content->OpenContentLC(EPlay, uniqueId); williamr@2: williamr@2: // create the attribute set, add the attributes we are interested in williamr@2: RStringAttributeSet stringAttributeSet; williamr@2: CleanupClosePushL(stringAttributeSet); williamr@2: stringAttributeSet.AddL(EPreviewURI); williamr@2: stringAttributeSet.AddL(ETitle); williamr@2: williamr@2: User::LeaveIfError(data->GetStringAttributeSet(stringAttributeSet)); williamr@2: williamr@2: // Pass the value of the string attribute to DisplayPreview() williamr@2: TFileName previewUri; williamr@2: TInt err = stringAttributeSet.GetValue(EPreviewURI, previewUri); williamr@2: if(err == KErrNone) williamr@2: { williamr@2: DisplayPreview(previewUri); williamr@2: } williamr@2: williamr@2: CleanupStack::PopAndDestroy(3); // content, data, stringAttributeSet williamr@2: @endcode williamr@2: williamr@2: williamr@2: @param aStringAttributeSet The set of attributes to query and update. williamr@2: @return Whether the string attribute set was updated. williamr@2: @return KErrNone if the attributes were retrieved successfully. williamr@2: @return KErrNotFound if the default content object was not found. williamr@2: @return KErrPermissionDenied if the access to the protected content is not permitted by the CAF Agent. williamr@2: @return Otherwise one of the CAF error codes defined in \c caferr.h or one of the williamr@2: other system-wide error codes for any other errors. williamr@2: @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. Access to unprotected content is unrestricted williamr@2: */ williamr@2: IMPORT_C TInt GetStringAttributeSet(RStringAttributeSet& aStringAttributeSet) const; williamr@4: williamr@4: williamr@2: #ifndef REMOVE_CAF1 williamr@2: /** Set Qos attribute williamr@2: @param aQosAttr The Qos attribute to set. williamr@2: @param aValue The value of the attribute. williamr@2: @deprecated williamr@2: */ williamr@2: IMPORT_C void SetQosL(TQosAttribute aQosAttr, TInt aValue); williamr@2: williamr@2: /** Get the mime type of the content williamr@2: @param aMimeType Buffer to store the mime type provided by the agent. williamr@2: @return ETrue if the mime type was retrieved successfully. williamr@2: @deprecated williamr@2: */ williamr@2: IMPORT_C TBool GetMimeTypeL(TDes8& aMimeType) const; williamr@2: #endif // REMOVE_CAF1 williamr@2: williamr@4: #ifdef SYMBIAN_ENABLE_SDP_WMDRM_SUPPORT williamr@4: /** williamr@4: Decrypts the encrypted input data packet. williamr@4: williamr@4: @param aEncryptedInputDataPacket Buffer descriptor containing the encrypted data packet supplied by client application. williamr@4: @param aDecryptedOutputDataPacket Buffer descriptor supplied by the client application into which the decrypted data is written. williamr@4: The length of this descriptor must be equal to or greater than the input packet. williamr@4: @return KErrNone if successful.KErrInsufficientDataPacketLength if a part of input packet is provided, williamr@4: otherwise one of the CAF error codes defined in \c caferr.h or williamr@4: one of the other system-wide error codes. williamr@4: @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. williamr@4: Access to unprotected content is unrestricted. williamr@4: */ williamr@4: williamr@4: IMPORT_C TInt Read(const TDesC8& aEncryptedInputDataPacket, TDes8& aDecryptedOutputDataPacket) const; williamr@4: williamr@4: /** williamr@4: Decrypts the encrypted input data packet asynchronously. williamr@4: @param aEncryptedInputDataPacket Buffer descriptor containing the encrypted data packet supplied by client application. williamr@4: @param aDecryptedOutputDataPacket Buffer descriptor supplied by the client application into which the decrypted data is written. williamr@4: The length of this descriptor must be equal to or greater than the input packet. williamr@4: @param aStatus Asynchronous request status. On completion this will contain one of the following error codes: williamr@4: KErrNone if the data packet was successfully decrypted.KErrInsufficientDataPacketLength if a williamr@4: part of input packet is provided, otherwise one of the CAF error codes defined in \c caferr.h or williamr@4: one of the other system-wide error codes. williamr@4: @capability DRM Access to DRM protected content is not permitted for processes without DRM capability. williamr@4: Access to unprotected content is unrestricted. williamr@4: */ williamr@4: IMPORT_C void Read(const TDesC8& aEncryptedInputDataPacket, TDes8& aDecryptedOutputDataPacket, TRequestStatus& aStatus) const; williamr@4: williamr@4: #endif //#ifdef SYMBIAN_ENABLE_SDP_WMDRM_SUPPORT williamr@2: williamr@2: private: williamr@2: CData(); williamr@2: void ConstructL(RFile& aFile, const TDesC& aUniqueId, TIntent aIntent); williamr@2: void ConstructL(const TVirtualPathPtr& aVirtualPath, TIntent aIntent, TContentShareMode aShareMode); williamr@2: void ConstructL(TUid aAgentUid, RFile& aFile, const TDesC& aUniqueId, TIntent aIntent); williamr@2: void ConstructL(TUid aAgentUid, const TVirtualPathPtr& aVirtualPath, TIntent aIntent, TContentShareMode aShareMode); williamr@2: williamr@2: void ConstructL(RFile& aFile, const TDesC& aUniqueId); williamr@2: void ConstructL(const TVirtualPathPtr& aVirtualPath, TContentShareMode aShareMode); williamr@2: void ConstructL(TUid aAgentUid, RFile& aFile, const TDesC& aUniqueId); williamr@2: void ConstructL(TUid aAgentUid, const TVirtualPathPtr& aVirtualPath, TContentShareMode aShareMode); williamr@2: williamr@4: #ifdef SYMBIAN_ENABLE_SDP_WMDRM_SUPPORT williamr@4: williamr@4: void ConstructL(TUid aAgentUid, const TDesC8& aHeaderData, TIntent aIntent); williamr@4: void ConstructL(const TDesC8& aHeaderData); williamr@4: void ConstructL(const TDesC8& aHeaderData, TIntent aIntent); williamr@4: void ConstructL(TUid aAgentUid, const TDesC8& aHeaderData); williamr@4: williamr@4: #endif //#ifdef SYMBIAN_ENABLE_SDP_WMDRM_SUPPORT williamr@4: williamr@4: #ifdef SYMBIAN_ENABLE_64_BIT_FILE_SERVER_API williamr@4: /* williamr@4: * This is the obselete 32bit Read and replaced by its 64bit counterpart williamr@4: * TInt Read(TInt64 aPos, TDes8& aDes, TInt aLength, TRequestStatus& aStatus) const williamr@4: * However, this function still exits at its original ordinal to avoid BC break. williamr@4: * Upgrade to 64bit Read is done automatically upon recompling the client code which uses CAF interfaces williamr@4: */ williamr@4: IMPORT_C TInt Read_Unused(TInt aPos, TDes8& aDes, TInt aLength, TRequestStatus& aStatus) const; williamr@4: #endif //SYMBIAN_ENABLE_64_BIT_FILE_SERVER_API williamr@2: williamr@2: private: williamr@2: // The agent handling this content williamr@2: CAgentData* iAgentData; williamr@2: williamr@2: // Defacto ECOM session handle williamr@2: CAgentFactory* iAgentFactory; williamr@2: williamr@2: // Uid of the agent williamr@2: TUid iAgentUid; williamr@2: }; williamr@2: williamr@2: } // namespace ContentAccess williamr@2: #endif /* __DATA_H__ */ williamr@2: