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