williamr@2: /*
williamr@4: * Copyright (c) 2003-2009 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: @file
williamr@2: 
williamr@4: @publishedAll
williamr@2: @released
williamr@2: */
williamr@2: 
williamr@2: 
williamr@2: #ifndef __CONTENT_H__
williamr@2: #define __CONTENT_H__
williamr@2: 
williamr@2: #include <e32base.h>
williamr@2: #include <f32file.h>
williamr@2: 
williamr@2: #include <caf/caftypes.h>
williamr@2: #include <caf/agent.h>
williamr@2: #include <caf/streamableptrarray.h>
williamr@2: #include <caf/virtualpathptr.h>
williamr@2: 
williamr@2: namespace ContentAccess
williamr@2: 	{
williamr@2: 	class CAgentResolver;
williamr@2: 	class CAgentFactory;
williamr@2: 	class CAgentContent;
williamr@2: 	class CData;
williamr@2: 	class CEmbeddedObject;
williamr@2: 	class RAttributeSet;
williamr@2: 	class RStringAttributeSet;
williamr@2: 
williamr@2: 	
williamr@2: 
williamr@2: #ifndef REMOVE_CAF1
williamr@2: 	class CAttribute;
williamr@2: #endif
williamr@2: 	
williamr@2: 
williamr@2: /**
williamr@2:    CContent allows applications to browse the content objects contained within a 
williamr@2:    single file and construct a CData object for reading that content.
williamr@2:  
williamr@2:   Applications will use an object of this type rather than the traditional 
williamr@2:   RFile mechanisms. They will, however, be  required to indicate 
williamr@2:   <i>DRM Intent</i> - something that determines whether (and how) access to
williamr@2:   the content should be permitted by a Content-Access agent.
williamr@2:  
williamr@2:   CContent allows direct access to meta-data such as the attributes of 
williamr@2:   the content and indirect access to the plaintext data itself through 
williamr@2:   the CData class. 
williamr@2:   
williamr@2:   Applications can use CContent to browse the hierarchy of content objects 
williamr@2:   within a file containing several content objects.
williamr@2:    
williamr@2:   During construction CContent loads the correct CAF Agent plugin to handle 
williamr@2:   the file specified by the URI.
williamr@2:  */
williamr@2: 	class CContent :  public CBase
williamr@2: 		{
williamr@2: 	public:
williamr@2: 
williamr@2: 		/**
williamr@2: 		 Constructs a new CContent object with a given URI. The URI can be in the same format as a virtual path for more information see CVirtualPath and TVirtualPathPtr
williamr@2: 
williamr@2: 		 @param aURI	The filename, URI or virtual path of the DRM file.
williamr@2: 		 @return a new CContent object.
williamr@2: 		 @leave KErrNotFound If the file at the given URI does not exist or if an invalid URI or virtual path have been supplied.
williamr@2: 		 @leave KErrPermissionDenied If the access to the protected content is not permitted by the CAF Agent.
williamr@2: 		 @leave ...		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 static CContent* NewLC(const TDesC& aURI);
williamr@2: 
williamr@2: 		/**
williamr@2: 		 Constructs a new CContent object with a given URI. The URI can be in the same format as a virtual path for more information see CVirtualPath and TVirtualPathPtr
williamr@2: 
williamr@2: 		 @param aURI	The filename, URI or virtual path of the DRM file.
williamr@2: 		 @return a new CContent object.
williamr@2: 		 @leave KErrNotFound If the file at the given URI does not exist or if an invalid URI or virtual path have been supplied.
williamr@2: 		 @leave KErrPermissionDenied If the access to the protected content is not permitted by the CAF Agent.
williamr@2: 		 @leave ...			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 static CContent* NewL(const TDesC& aURI);
williamr@2: 		
williamr@2: 		/**
williamr@2: 		 Constructs a new CContent object with a given URI. The URI can be in the same format as a virtual path for more information see CVirtualPath and TVirtualPathPtr
williamr@2: 
williamr@2: 		 @param aURI	The filename, URI or virtual path of the DRM file.
williamr@2: 		 @param aShareMode The sharing mode used when accessing the content.
williamr@2: 		 @return a new CContent object.
williamr@2: 		 @leave KErrNotFound If the file at the given URI does not exist or if an invalid URI or virtual path have been supplied.
williamr@2: 		 @leave KErrAccessDenied If the file is already open with a different share mode.
williamr@2: 		 @leave KErrPermissionDenied If the access to the protected content is not permitted by the CAF Agent.
williamr@2: 		 @leave ...			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 static CContent* NewLC(const TDesC& aURI, TContentShareMode aShareMode);
williamr@2: 		
williamr@2: 		/** 
williamr@2: 		Constructs a new CContent object with a given URI. The URI can be in the same format as a virtual path for more information see CVirtualPath and TVirtualPathPtr
williamr@2: 
williamr@2: 		@param aURI	The filename, URI or virtual path of the DRM file.
williamr@2: 		@param aShareMode The sharing mode used when accessing the content.
williamr@2: 		@return a new CContent object.
williamr@2: 		@leave KErrNotFound If the file at the given URI does not exist or if an invalid URI or virtual path have been supplied.
williamr@2: 		@leave KErrAccessDenied If the file is already open with a different share mode.
williamr@2: 		@leave KErrPermissionDenied If the access to the protected content is not permitted by the CAF Agent.
williamr@2: 		@leave ...			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 static CContent* NewL(const TDesC& aURI, TContentShareMode aShareMode);
williamr@2: 
williamr@2: 		/**
williamr@2: 		 Constructs a new CContent object with an open file handle.
williamr@2: 
williamr@2:   		 CContent will use a duplicate of this file handle, the client is 
williamr@2: 		 free to close its file handle any time after creating the CContent 
williamr@2: 		 object.
williamr@2: 
williamr@2: 		 @param aFile The file handle. The file must already be open before calling NewLC. 
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: 		 @return a new CContent object.
williamr@2: 		 @leave KErrPermissionDenied If the access to the protected content is not permitted by the CAF Agent.
williamr@2: 		 @leave ...			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 static CContent* NewLC(RFile& aFile);
williamr@2: 		
williamr@2: 		/** 
williamr@2: 		 Constructs a new CContent object with an open file handle.
williamr@2: 
williamr@2:   		 CContent will use a duplicate of this file handle, the client is 
williamr@2: 		 free to close its file handle any time after creating the CContent 
williamr@2: 		 object.
williamr@2: 
williamr@2: 		 @param aFile The file handle. The file must already be open before calling this method. 
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: 		 @return a new CContent object.
williamr@2: 		 @leave KErrPermissionDenied If the access to the protected content is not permitted by the CAF Agent.	 
williamr@2: 		 @leave ...			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 static CContent* NewL(RFile& aFile);
williamr@2: 
williamr@4: #ifdef SYMBIAN_ENABLE_SDP_WMDRM_SUPPORT		
williamr@4: 		/** 
williamr@4: 		 Constructs a new CContent object.
williamr@4: 
williamr@4:   		 @param aHeaderData	Header data of WMDRM file/stream content. 
williamr@4: 		 @return 			CContent object.
williamr@4: 		 @leave 			KErrMissingHeaderData if the header data is NULL or one of the CAF error codes defined in caferr.h  
williamr@4: 		 					or one of the system-wide error codes for any other errors.
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@4: 		IMPORT_C static CContent* NewL(const TDesC8& aHeaderData);
williamr@4: 		
williamr@4: 		/** 
williamr@4: 		 Constructs a new CContent object.
williamr@4:   		 
williamr@4:   		 @param aHeaderData	Header data of WMDRM file/stream content.  
williamr@4: 		 @return 			CContent object.
williamr@4: 		 @leave 			KErrMissingHeaderData if the header data is NULL or one of the CAF error codes defined in caferr.h  or one of the 
williamr@4: 							system-wide error codes for any other errors.
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@4: 		IMPORT_C static CContent* NewLC(const TDesC8& aHeaderData);
williamr@4: 		
williamr@4: #endif //#ifdef SYMBIAN_ENABLE_SDP_WMDRM_SUPPORT
williamr@4: 
williamr@2: 		/** destructor */
williamr@2: 		virtual ~CContent();
williamr@2: 
williamr@2:  		/** Open a Container object within the file.
williamr@2:  		
williamr@2:  		Allows an application to access the content objects and 
williamr@2:  		any nested container objects within the specified container.
williamr@2:   		
williamr@2:  		@param aUniqueId The container object's unique ID.
williamr@2: 		@return Whether the container was opened.
williamr@2:  		@return KErrNone if the container was opened successfully.
williamr@2:  		@return KErrNotFound if the container 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 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 OpenContainer(const TDesC& aUniqueId);
williamr@2: 
williamr@2:  		/** Close the current container object and go back to previous enclosing
williamr@2:  		container within the file.
williamr@2:  		
williamr@2:  		Allows an application to access the content objects and 
williamr@2:  		any nested container objects within parent container.
williamr@2:   		
williamr@2: 		@return Whether the container was closed.
williamr@2:   		@return KErrNone if the container was closed.
williamr@2:   		@return KErrNotFound if there is no enclosing container.
williamr@2:   		@return KErrPermissionDenied if the access to the protected content is not permitted by the CAF Agent.		 		
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 CloseContainer();
williamr@2: 
williamr@2: 		/** List all the embedded container objects and content objects within the 
williamr@2: 		current container
williamr@2:  		 		
williamr@2: 		The UniqueId() member of CEmbeddedObject can be used to refer directly to 
williamr@2: 		a particular object within the file.
williamr@2: 		
williamr@2: 		@code
williamr@2: 		// Create a ccontent object for the file of interest
williamr@2: 		CContent* content = CContent::NewLC(uri);
williamr@2: 		
williamr@2: 		// Define an array to store the results
williamr@2: 		RStreamablePtrArray <CEmbeddedObject> array;
williamr@2: 		CleanupClosePushL(array);
williamr@2: 		
williamr@2: 		// Find all the content and container objects within the current container
williamr@2: 		content->GetEmbeddedObjectsL(array);
williamr@2: 		
williamr@2: 		// Do something with the array
williamr@2: 		....
williamr@2: 		
williamr@2: 		// Finished
williamr@2: 		CleanupStack::PopAndDestroy(2);
williamr@2: 		@endcode
williamr@2: 		
williamr@2: 		@param aArray The array to be populated with the embedded objects. 
williamr@2: 		@leave KErrPermissionDenied if the access to the protected content is not permitted by the CAF Agent.		 
williamr@2: 		@leave ...			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 void GetEmbeddedObjectsL(RStreamablePtrArray<CEmbeddedObject>& aArray) const;
williamr@2: 
williamr@2: 		/** List all the embedded objects within the current container that
williamr@2: 		are of the specified type
williamr@2: 
williamr@2: 		@code
williamr@2: 		// Create a ccontent object for the file of interest
williamr@2: 		CContent* content = CContent::NewLC(uri);
williamr@2: 		
williamr@2: 		// Define an array to store the results
williamr@2: 		RStreamablePtrArray <CEmbeddedObject> array;
williamr@2: 		CleanupClosePushL(array);
williamr@2: 		
williamr@2: 		// Find all the content objects within the current container
williamr@2: 		content->GetEmbeddedObjectsL(array, EContentObject);
williamr@2: 		
williamr@2: 		// Do something with the array
williamr@2: 		....
williamr@2: 		
williamr@2: 		// Finished
williamr@2: 		CleanupStack::PopAndDestroy(2);
williamr@2: 		@endcode
williamr@2:  		 		
williamr@2: 		@param aArray The array to be populated with the embedded objects. 
williamr@2: 		@param aType The type of objects to list.
williamr@2: 		@leave KErrPermissionDenied If the access to the protected content is not permitted by the CAF Agent.		 
williamr@2: 		@leave ...			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 void GetEmbeddedObjectsL(RStreamablePtrArray<CEmbeddedObject>& aArray, TEmbeddedType aType) const;
williamr@2: 		
williamr@2: 		/** Search the current container for content objects with a particular mime type
williamr@2: 
williamr@2: 		@code
williamr@2: 		_LIT8(KTextPlainMimeType, "text/plain");
williamr@2: 		
williamr@2: 		// Create a ccontent object for the file of interest
williamr@2: 		CContent* content = CContent::NewLC(uri);
williamr@2: 		
williamr@2: 		// Define an array to store the results
williamr@2: 		RStreamablePtrArray <CEmbeddedObject> array;
williamr@2: 		CleanupClosePushL(array);
williamr@2: 		
williamr@2: 		// Recursively search for all the content objects with the 
williamr@2: 		// specified mime type
williamr@2: 		User::LeaveIfError(content->Search(array, KTextPlainMimeType(), ETrue));
williamr@2: 		
williamr@2: 		// Do something with the array
williamr@2: 		....
williamr@2: 		
williamr@2: 		// Finished
williamr@2: 		CleanupStack::PopAndDestroy(2);
williamr@2: 		@endcode
williamr@2: 
williamr@2:   		@param aArray The array to store the results of the search. The agent will add CEmbeddedObject objects to the supplied array.
williamr@2: 		@param aMimeType The mime type to search for.
williamr@2: 		@param aRecursive ETrue to search inside containers embedded within the current container, EFalse to search only the current container.
williamr@2: 		@return The result of the search.
williamr@2: 		@return KErrNone if the search was successful, even if no content objects were 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 Search(RStreamablePtrArray<CEmbeddedObject>& aArray, const TDesC8& aMimeType, TBool aRecursive);
williamr@2: 
williamr@2: 
williamr@2: 		/**  Get an attribute for the default content object within the file
williamr@2: 
williamr@2:   		@see ContentAccess::TAttribute
williamr@2: 
williamr@2: 		@code
williamr@2: 		TInt value = 0;
williamr@2: 		CContent* c = CContent::NewL(uri);
williamr@2: 		TInt err =c->GetAttribute(EIsProtected, value);
williamr@2: 		if(err == KErrNone && value)
williamr@2: 			{
williamr@2: 			DisplayPadLock();
williamr@2: 			}
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 value was updated.
williamr@2: 		@return KErrNone if the value of the attribute was updated.
williamr@2: 		@return KErrNotFound if the object with the given UniqueId was not found.
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 an attribute for an object within the file
williamr@2: 
williamr@2: 		@see ContentAccess::TAttribute
williamr@2: 
williamr@2: 		@code
williamr@2: 		TInt value = 0;
williamr@2: 		CContent* c = CContent::NewL(uri);
williamr@2: 		TInt err =c->GetAttribute(EIsProtected, value, uniqueId);
williamr@2: 		if(err == KErrNone && value)
williamr@2: 			{
williamr@2: 			DisplayPadLock();
williamr@2: 			}
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: 		@param aUniqueId The UniqueId of the object within the file.
williamr@2: 		@return Whether the attribute value was updated.
williamr@2: 		@return KErrNone if the value of the attribute was updated.
williamr@2: 		@return KErrNotFound if the object with the given UniqueId was not found.
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 TDesC& aUniqueId) const;
williamr@2: 		
williamr@2: 
williamr@2: 		/** Get a set of attributes for the default content object within the file
williamr@2: 
williamr@2: 		@see ContentAccess::TAttribute
williamr@2: 
williamr@2: 		The following example determines whether the default 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: 		CContent* content = CContent::NewLC(uri);
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(content->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(2); // content, 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 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 GetAttributeSet(RAttributeSet& aAttributeSet) const;		
williamr@2: 		
williamr@2: 		/** Get a set of attributes from an object within the file
williamr@2: 
williamr@2: 		@see ContentAccess::TAttribute
williamr@2: 
williamr@2: 		The following example determines whether the default 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: 		CContent* content = CContent::NewLC(uri);
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(content->GetAttributeSet(attributeSet, uniqueId);
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(2); // content, attributeSet.Close()
williamr@2: 		@endcode
williamr@2: 
williamr@2: 
williamr@2: 		@param aAttributeSet The set of attributes to query and update.
williamr@2: 		@param aUniqueId The unique ID of the object within the file.
williamr@2: 		@return Whether that 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 GetAttributeSet(RAttributeSet& aAttributeSet, const TDesC& aUniqueId) const;
williamr@2: 		
williamr@2: 		/**  Get text string attributes or meta-data for the default content object within the file
williamr@2: 	
williamr@2: 		@see ContentAccess::TStringAttribute
williamr@2: 
williamr@2: 		@code
williamr@2: 		TInt err = KErrNone;
williamr@2: 		
williamr@2: 		CContent* c = CContent::NewL(uri);
williamr@2: 		TBuf <MAX_PATH> previewUri;
williamr@2: 		err = c->GetStringAttribute(EPreviewURI, previewUri);
williamr@2: 		if(err == KErrNone)
williamr@2: 			{
williamr@2: 			DisplayPreview(previewUri);
williamr@2: 			}
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 attribute value was updated.
williamr@2: 		@return KErrNone if the attribute was retrieved.
williamr@2: 		@return KErrNotFound if the default content object was not found.
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: 		/** Get text string attributes or meta-data for an object within the file
williamr@2: 
williamr@2: 		@see ContentAccess::TStringAttribute
williamr@2: 
williamr@2: 		@code
williamr@2: 		TInt err = KErrNone;
williamr@2: 		
williamr@2: 		CContent* c = CContent::NewL(uri);
williamr@2: 		TBuf <MAX_PATH> previewUri;
williamr@2: 		err = c->GetStringAttribute(EPreviewURI, previewUri, uniqueId);
williamr@2: 		if(err == KErrNone)
williamr@2: 			{
williamr@2: 			DisplayPreview(previewUri);
williamr@2: 			}
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: 		@param aUniqueId The UniqueId of the object within the file. 
williamr@2: 		@return Whether the attribute value was updated.
williamr@2: 		@return KErrNone if the attribute was retrieved.
williamr@2: 		@return KErrNotFound if the object with the given UniqueId was not found.
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 TDesC& aUniqueId) const;
williamr@2: 		
williamr@2: 		/** Obtain a set of string attributes for the default content object within the file
williamr@2: 
williamr@2: 		@see ContentAccess::TStringAttribute
williamr@2: 	  
williamr@2: 		@code
williamr@2: 		CContent* content = CContent::NewLC(uri);
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(content->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(2); // content, stringAttributeSet.Close()
williamr@2: 		@endcode
williamr@2: 	
williamr@2: 
williamr@2: 		@param aStringAttributeSet 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 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@2: 	
williamr@2: 		/** Used to obtain a set of string attributes for an object within the file
williamr@2: 
williamr@2: 		@see ContentAccess::TStringAttribute
williamr@2: 	
williamr@2: 		@code
williamr@2: 		CContent* content = CContent::NewLC(uri);
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(content->GetStringAttributeSet(stringAttributeSet, uniqueId));
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(2); // content, stringAttributeSet.Close()
williamr@2: 		@endcode
williamr@2: 	
williamr@2: 
williamr@2: 		@param aStringAttributeSet The set of attributes to query and update.
williamr@2: 		@param aUniqueId The UniqueId of the container or content. 
williamr@2: 		@return Whether the attribute set was updated.
williamr@2: 		@return KErrNone if the attributes were retrieved successfully.
williamr@2: 		@return KErrNotFound if the object with the given UniqueId 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 TDesC& aUniqueId) const;
williamr@2: 
williamr@2: 		/** Allows extended synchronous calls to the CAF agent handling this file
williamr@2: 		
williamr@2: 		Applications familiar with the agent can pass objects in and out using serialization.
williamr@2: 
williamr@2: 		@param aCommand The agent defined command.
williamr@2: 		@param aInputBuffer Non modifyable input data buffer.
williamr@2: 		@param aOutputBuffer Modifyable output buffer to hold the result of the command.
williamr@2: 		@return The outcome of the agent specific command.
williamr@2: 		@return KErrCANotSupported if the agent does not recognize the command.
williamr@2: 		@return KErrOverflow if the output buffer supplied is too small.
williamr@2: 		@return KErrPermissionDenied if the agent does not allow the client to execute the command.
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 AgentSpecificCommand(TInt aCommand, const TDesC8& aInputBuffer, TDes8& aOutputBuffer);
williamr@2: 
williamr@2: 		/** Allows extended synchronous calls to the CAF agent handling this file
williamr@2: 		Applications familiar with the agent can pass objects in and out using serialization.
williamr@2: 		NB: It is important that the descriptor passed to 
williamr@2: 		aOutputBuffer remains in scope until the request has completed.		
williamr@2: 
williamr@2: 		@param aCommand The agent defined command.
williamr@2: 		@param aInputBuffer Non modifyable input data buffer.
williamr@2: 		@param aOutputBuffer Modifyable output buffer to hold the result of the command.
williamr@2: 		@param aStatus Asynchronous request status. On completion this will contain 
williamr@2: 						one of the following error codes:
williamr@2: 						KErrNone if the command was successfully executed.
williamr@2: 						KErrCANotSupported  if the agent does not recognize the command.
williamr@2: 						KErrOverflow if the output buffer supplied is too small.
williamr@2: 						KErrPermissionDenied if the agent does not allow the client 
williamr@2: 						to execute the command. Otherwise one of the other CAF error codes defined 
williamr@2: 						in \c caferr.h  or one of the other system-wide error codes 
williamr@2: 						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 AgentSpecificCommand(TInt aCommand, const TDesC8& aInputBuffer, TDes8& aOutputBuffer, TRequestStatus& aStatus);
williamr@2: 
williamr@2: 
williamr@2: 		/** Request notification for an event for the default content object within the file
williamr@2: 
williamr@2: 		@see ContentAccess::TEventMask
williamr@2: 
williamr@2: 		@param aMask Bitmask of events the caller is interested in.	
williamr@2: 		@param aStatus The TRequestStatus object to complete if the event occurs.
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 NotifyStatusChange(TEventMask aMask, TRequestStatus& aStatus);
williamr@2: 
williamr@2: 		/** Request notification for an event for an object within the file
williamr@2: 
williamr@2: 		@see ContentAccess::TEventMask
williamr@2: 
williamr@2: 		@param aMask Bitmask of events the caller is interested in.
williamr@2: 		@param aStatus The TRequestStatus object to complete if the event occurs.
williamr@2: 		@param aUniqueId The UniqueId of the container or content. 						 
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 NotifyStatusChange(TEventMask aMask, TRequestStatus& aStatus, const TDesC& aUniqueId);
williamr@2: 
williamr@2: 		/** Cancel a previous notification request for the default content object
williamr@2: 
williamr@2: 		@param aStatus The TRequestStatus supplied in the call to NotifyStatusChange().
williamr@2: 		@return The outcome of the cancel request.
williamr@2: 		@return KErrNone if the request was cancelled.
williamr@2: 		@return KErrNotFound if there was no matching request outstanding.
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 CancelNotifyStatusChange(TRequestStatus& aStatus);
williamr@2: 
williamr@2: 		/** Cancel a previous notification request
williamr@2: 
williamr@2: 		@param aStatus The TRequestStatus supplied in the call to NotifyStatusChange().
williamr@2: 		@param aUniqueId The UniqueId of the content object within the file.
williamr@2: 		@return The outcome of the cancel request.
williamr@2: 		@return KErrNone if the request was cancelled.
williamr@2: 		@return KErrNotFound if there was no matching request outstanding.
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 CancelNotifyStatusChange(TRequestStatus& aStatus, const TDesC& aUniqueId);
williamr@2: 		
williamr@2: 		/** Request the agent to obtain rights for the default content object
williamr@2: 
williamr@2: 		This request may be handled differently by different agents. 
williamr@2: 		Some agents may open a browser and direct the user to a URL. Others may 
williamr@2: 		download and install the rights in the background.
williamr@2: 
williamr@2: 		The call should not block execution, applications can wait for a notification 
williamr@2: 		if they are interested in the outcome.
williamr@2: 
williamr@2: 		@param aStatus Asynchronous request status. On completion this will contain 
williamr@2: 						one of the following error codes:
williamr@2: 						KErrNone if the rights request was successful.
williamr@2: 						KErrCANotSupported  if the agent does not allow rights requests.
williamr@2: 						Otherwise 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: 		@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 RequestRights(TRequestStatus& aStatus);
williamr@2: 
williamr@2: 		/** Request the agent to obtain rights for a protected content object
williamr@2: 
williamr@2: 		This request may be handled differently by different agents. 
williamr@2: 		Some agents may open a browser and direct the user to a URL. Others may 
williamr@2: 		download and install the rights in the background.
williamr@2: 
williamr@2: 		The call should not block execution, applications can wait for a notification 
williamr@2: 		if they are interested in the outcome.
williamr@2: 
williamr@2: 		@param aStatus Asynchronous request status. On completion this will contain 
williamr@2: 						one of the following error codes:
williamr@2: 						KErrNone if the rights request was successful.
williamr@2: 						KErrCANotSupported  if the agent does not allow rights requests.
williamr@2: 						Otherwise 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: 		@param aUniqueId The unique id of the object within the file.					
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 RequestRights(TRequestStatus& aStatus, const TDesC& aUniqueId);
williamr@2: 
williamr@2: 
williamr@2: 		/** Cancel a previous RequestRights() request for the default content object
williamr@2: 
williamr@2: 		@param aStatus The TRequestStatus that was supplied to the RequestRights() function.
williamr@2: 		@return The result of the cancel rights request.
williamr@2: 		@return KErrNone if the rights request was cancelled.
williamr@2: 		@return KErrNotFound if there was no matching rights request outstanding.
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 CancelRequestRights(TRequestStatus& aStatus);
williamr@2: 
williamr@2: 		/** Cancel a previous RequestRights() request
williamr@2: 
williamr@2: 		@param aStatus The TRequestStatus that was supplied to the RequestRights() function.
williamr@2: 		@param aUniqueId The objects Unique Id that was supplied to the RequestRights() function.
williamr@2: 		@return The result of the cancel rights request.
williamr@2: 		@return KErrNone if the rights request was cancelled.
williamr@2: 		@return KErrNotFound if there was no matching rights request outstanding.
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 CancelRequestRights(TRequestStatus& aStatus, const TDesC& aUniqueId);
williamr@2: 
williamr@2: 		/** View information associated with the default content object
williamr@2: 	
williamr@2: 		This call blocks execution and only returns once the display is dismissed 
williamr@2: 		by the user.
williamr@2: 
williamr@2: 		@see ContentAccess::TDisplayInfo
williamr@2: 
williamr@2: 		@param aInfo The information to display.
williamr@2: 		@leave KErrCANotSupported if information cannot be displayed or does not exist.
williamr@2: 		@leave ...			One of the other CAF error codes defined in \c caferr.h  
williamr@2: 							or one of the system-wide error codes for 
williamr@2: 							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 DisplayInfoL(TDisplayInfo aInfo) const;
williamr@2: 		
williamr@2: 		/** View information associated with a single content object
williamr@2: 		
williamr@2: 		This call blocks execution and only returns once the display is dismissed 
williamr@2: 		by the user.
williamr@2: 
williamr@2: 		@see ContentAccess::TDisplayInfo
williamr@2: 
williamr@2: 		@param aInfo The information to display.
williamr@2: 		@param aUniqueId The unique id of the object within the file.
williamr@2: 		@leave KErrCANotSupported if information cannot be displayed or does not exist.
williamr@2: 		@leave ...			One of the other CAF error codes defined in \c caferr.h  
williamr@2: 							or one of the system-wide error codes for 
williamr@2: 							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 DisplayInfoL(TDisplayInfo aInfo, const TDesC& aUniqueId) const;
williamr@2: 
williamr@2: 
williamr@2: 		/** Request the agent handling this content to set a property value. If 
williamr@2: 		the property is set it is only set for this CContent session and does not 
williamr@2: 		impact other CAF users and is not set for CData products created by the 
williamr@2: 		CContent.
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 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: 		 Grants read access to the default content object based on 
williamr@2: 		 evaluation of the supplied intent information. 
williamr@2: 		 
williamr@2: 		 Note that the intent is simply evaluated and not executed. 
williamr@2: 		 To force the intent to be executed, clients must use the call
williamr@2: 		 ContentAccess::CData::ExecuteIntent(). 
williamr@2: 		 
williamr@2: 		 A CData object can be obtained as follows:
williamr@2: 		 @code
williamr@2: 		 CData* MyData = myContent->OpenContentL(ChosenIntent);
williamr@2: 		 ...
williamr@2: 		 delete MyData; // when finished accessing plaintext content
williamr@2: 		 @endcode
williamr@2: 
williamr@2: 		 @see ContentAccess::TIntent
williamr@2: 
williamr@2: 		 @param aIntent	The intent indicator.
williamr@2: 		 @return A CData instance. The caller gets ownership of this 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 any other 
williamr@2: 								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 CData* OpenContentL(TIntent aIntent);
williamr@2: 
williamr@2: 		/** 
williamr@2: 		 Grants read access to the default content object based on 
williamr@2: 		 evaluation of the supplied intent information. 
williamr@2: 	
williamr@2: 		 Note that the intent is simply evaluated and not executed. 
williamr@2: 		 To force the intent to be executed, clients must use the call
williamr@2: 		 ContentAccess::CData::ExecuteIntent(). 
williamr@2: 		 
williamr@2: 		 A CData object can be obtained as follows:
williamr@2: 		 @code
williamr@2: 		 CData* myData = myContent->OpenContentLC(ChosenIntent);
williamr@2: 		 ...
williamr@2: 		 // when finished accessing plaintext content
williamr@2: 		 CleanupStack::PopAndDestroy(myData); 
williamr@2: 		 @endcode
williamr@2: 
williamr@2: 		 @see ContentAccess::TIntent
williamr@2: 
williamr@2: 		 @param aIntent	The intent indicator.
williamr@2: 		 @return A CData instance. The caller gets ownership of this 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 any other 
williamr@2: 								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 CData* OpenContentLC(TIntent aIntent);
williamr@2: 		
williamr@2: 		/** 
williamr@2: 		 Grants read access to the content object based on evaluation of the
williamr@2: 		 supplied intent information. 
williamr@2: 		 
williamr@2: 		 Note that the intent is simply evaluated and not executed. 
williamr@2: 		 To force the intent to be executed, clients must use the call
williamr@2: 		 ContentAccess::CData::ExecuteIntent(). 
williamr@2: 		 
williamr@2: 		 A CData object can be obtained as follows:
williamr@2: 		 @code
williamr@2: 		 CData* MyData = myContent->OpenContentL(ChosenIntent, uniqueId);
williamr@2: 		 ...
williamr@2: 		 delete MyData; // when finished accessing plaintext content
williamr@2: 		 @endcode
williamr@2: 		 	
williamr@2: 		 @see ContentAccess::TIntent
williamr@2: 
williamr@2: 		 @param aIntent	The intent indicator.
williamr@2: 		 @param aUniqueId The object to open for reading. If the UniqueId is set to KNullDesC16() the entire file will be opened for reading with no transformation.
williamr@2: 		 @return A CData instance. The caller gets ownership of this 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 any other 
williamr@2: 								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 CData* OpenContentL(TIntent aIntent, const TDesC& aUniqueId);
williamr@2: 
williamr@2: 
williamr@2: 		/** 
williamr@2: 		 Grants read access to the content object based on evaluation of the
williamr@2: 		 supplied intent information. 
williamr@2: 		 
williamr@2: 		 Note that the intent is simply evaluated and not executed. 
williamr@2: 		 To force the intent to be executed, clients must use the call
williamr@2: 		 ContentAccess::CData::ExecuteIntent(). 
williamr@2: 		 
williamr@2: 		 A CData object can be obtained as follows:
williamr@2: 		 @code
williamr@2: 		 CData* MyData = myContent->OpenContentLC(ChosenIntent, uniqueId);
williamr@2: 		 ...
williamr@2: 		 PopAndDestroy(MyData); // when finished accessing plaintext content
williamr@2: 		 @endcode
williamr@2: 		 	
williamr@2: 		 @see ContentAccess::TIntent
williamr@2: 
williamr@2: 		 @param aIntent	The intent indicator.
williamr@2: 		 @param aUniqueId The object to open for reading. If the UniqueId is set to KNullDesC16() the entire file will be opened for reading with no transformation.
williamr@2: 		 @return A CData instance. The caller gets ownership of this 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 any other 
williamr@2: 								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 CData* OpenContentLC(TIntent aIntent, const TDesC& aUniqueId);
williamr@2: 
williamr@2: 
williamr@2: 		/** Find out which agent is handling this file
williamr@2: 		@return The agent handling the File
williamr@2: 		*/
williamr@2: 		IMPORT_C const TAgent& Agent() const;
williamr@2: 		
williamr@4: 		/** Indicates the mode in which the content is shared.
williamr@4: 			@return The content sharing mode
williamr@4: 		*/
williamr@4: 		inline TContentShareMode ShareMode() const;
williamr@4: 		
williamr@2: #ifndef REMOVE_CAF1
williamr@2: 		/** Create a CData object for reading the content 
williamr@2: 
williamr@2: 		@see ContentAccess::TIntent
williamr@2: 		@param aIntent The intended use of the content
williamr@2: 		@param aShareMode The mode used to open the file. If EContentShareExclusive is required, use CData::NewL() instead
williamr@2: 		@return A new CData object
williamr@2: 		@leave One of the CAF error codes defined in \c caferr.h  or one of the system-wide error codes for any errors.
williamr@2: 		@capability DRM Access to DRM agents is not permitted for processes without DRM capability
williamr@2: 		@deprecated
williamr@2: 		*/
williamr@2: 		IMPORT_C CData* OpenContentL(TIntent aIntent, TContentShareMode aShareMode);
williamr@2: 
williamr@2: 		/** Create a CAttribute object to determine the attributes of the default content object
williamr@2: 		
williamr@2: 		@return The agent handling the File
williamr@2: 		@capability DRM Access to DRM agents is not permitted for processes without DRM capability
williamr@2: 		@deprecated 
williamr@2: 		*/
williamr@2: 		IMPORT_C CAttribute* NewAttributeL(TBool aPreloaded);
williamr@2: 
williamr@2: 		/** Create a CAttribute object to determine the attributes of the default content object
williamr@2: 		
williamr@2: 		@return The agent handling the File
williamr@2: 		@capability DRM Access to DRM agents is not permitted for processes without DRM capability
williamr@2: 		@deprecated 
williamr@2: 		*/
williamr@2: 		IMPORT_C CAttribute* NewAttributeL(TBool aPreloaded, TContentShareMode aShareMode);
williamr@2: 
williamr@2: #endif  // REMOVE_CAF1
williamr@2: 		
williamr@2: 	private:
williamr@2: 		CContent(); 
williamr@2: 		void ConstructL(RFile& aFile); 
williamr@2: 		void ConstructL(const TDesC& aURI, TContentShareMode aShareMode); 
williamr@2: 		
williamr@4: #ifdef SYMBIAN_ENABLE_SDP_WMDRM_SUPPORT
williamr@4: 		void ConstructL(const TDesC8& aHeaderData);
williamr@4: 
williamr@4: 		/**
williamr@4: 		Create a CData object for reading WMDRM content.
williamr@4: 		
williamr@4: 		@param	aIntent		The intended use of the content.
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 system-wide error codes for any errors.
williamr@4: 		@capability DRM 	Access to DRM agents is not permitted for processes without DRM capability.
williamr@4: 		*/
williamr@4: 		
williamr@4: 		CData* OpenContentL(TIntent aIntent, const TDesC8& aHeaderData);
williamr@4: 		
williamr@4: 		/**
williamr@4: 		Create a CData object for reading WMDRM content.
williamr@4: 		
williamr@4: 		@param	aIntent		The intended use of the content.
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 system-wide error codes for any errors.
williamr@4: 		@capability DRM 	Access to DRM agents is not permitted for processes without DRM capability.
williamr@4: 		*/
williamr@4: 		CData* OpenContentLC(TIntent aIntent, const TDesC8& aHeaderData);
williamr@4: 		
williamr@4: #endif //#ifdef SYMBIAN_ENABLE_SDP_WMDRM_SUPPORT
williamr@4: 
williamr@2: 	private:	
williamr@2: 	
williamr@2: 		/** CAgentFactory object is effectively the	ECOM session handle */
williamr@2: 		CAgentFactory* iAgentFactory;
williamr@2: 
williamr@2: 		/** 
williamr@2: 		 Agent object used for browsing the contents of a file
williamr@2: 		 */
williamr@2: 		CAgentContent* iAgentContent;
williamr@2: 
williamr@2: 		/** Points to the default content object if the file is opened by name */
williamr@2: 		CVirtualPath* iVirtualPath;
williamr@2: 
williamr@2: 		/** The content object referred to by CContent, either points to iVirtualPath
williamr@2: 		or points to (KNullDesC(), KDefaultContentObject()) 
williamr@2: 		*/
williamr@2: 		TVirtualPathPtr iDefaultVirtualPath;
williamr@2: 
williamr@2: 		/* Stores the name and UID of the agent
williamr@2: 		*/
williamr@2: 		TAgent iAgent;
williamr@2: 		
williamr@2: 		/** The share mode used to open the content file*/
williamr@2: 		TContentShareMode iShareMode;
williamr@2: 
williamr@2: 		/** Reference to the file handle if the content was opened with a file handle */
williamr@4: #ifdef SYMBIAN_ENABLE_64_BIT_FILE_SERVER_API
williamr@4: 		RFile64 iFile;
williamr@4: #else
williamr@2: 		RFile iFile;
williamr@4: #endif //SYMBIAN_ENABLE_64_BIT_FILE_SERVER_API
williamr@4: 
williamr@4: #ifdef SYMBIAN_ENABLE_SDP_WMDRM_SUPPORT
williamr@4: 		HBufC8* iHeaderData;
williamr@4: #endif //#ifdef SYMBIAN_ENABLE_SDP_WMDRM_SUPPORT
williamr@4: 
williamr@2: 		};
williamr@2: 
williamr@4: #include <caf/content.inl>
williamr@2: 	} // namespace ContentAccess
williamr@4: 
williamr@4: #endif // __CONTENT_H__ 
williamr@4: