--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/drm_plat/drm_utility_api/inc/drmuihandling.h Thu Dec 17 08:52:27 2009 +0200
@@ -0,0 +1,522 @@
+/*
+* Copyright (c) 2006-2007 Nokia Corporation and/or its subsidiary(-ies).
+* All rights reserved.
+* This component and the accompanying materials are made available
+* under the terms of "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: Utility API for DRM related UI
+ *
+*/
+
+
+#ifndef C_CDRMUIHANDLING_H
+#define C_CDRMUIHANDLING_H
+
+#include <e32base.h>
+#include <f32file.h>
+#include <caf/caftypes.h>
+#include <drmutilitytypes.h>
+
+//*** forward declarations go here:
+namespace ContentAccess
+ {
+ class CData;
+ }
+
+class CCoeEnv;
+
+namespace DRM
+ {
+
+ //*** forward declarations go here:
+ class CDrmUtility;
+ class MDrmErrorHandling;
+ class MDrmAsyncObserver;
+ class MDrmHandleErrorObserver;
+ class MDrmUiCheckRightsObserver;
+ class CDrmUiHandlingImpl;
+
+ /**
+ * Utility class for DRM related UI
+ *
+ * By using this class an application can resolve situation where there is
+ * no valid rights for the content, check status of rights and display
+ * an embedded rights details view.
+ *
+ * Usage:
+ * @code
+ * #include <DrmUiHandling.h>
+ *
+ * using namespace DRM;
+ *
+ * // Call NewLC() to create an instance of CDrmUiHandling.
+ * CDrmUiHandling* drmUiHandler = CDrmUiHandling::NewLC();
+ *
+ * // Handling the error got when tried to read the file
+ * drmHandlerError = drmUiHandler->HandleErrorL( file, error, NULL );
+ *
+ * // checking the status of the rights
+ * drmHandlerError = drmUiHandler->CheckRightsAmountL( file, NULL );
+ *
+ * // opening embedded details view
+ * drmHandlerError = drmUiHandler->ShowDetailsViewL( file );
+ *
+ * // delete the created instance of CDrmUiHandling
+ * CleanupStack::PopAndDestroy( drmUiHandler );
+ * @endcode
+ *
+ * @lib drmutilityuihandling.lib
+ * @since S60 v5.0
+ */
+NONSHARABLE_CLASS( CDrmUiHandling ) : public CBase
+ {
+
+public:
+
+ /**
+ * Creates a new CDrmUiHandling object and returns a pointer to it
+ *
+ * @param aCoeEnv A pointer to an instance of CCoeEnv. If the
+ * parameter is not provided the global instance
+ * will be used. In the case of a server process
+ * where the global instance is not available,
+ * global notes will be used.
+ *
+ * If no CCoeEnv instance is available, applications
+ * launched will be launched as standalone
+ * applications.
+ *
+ * @return A functional CDrmUiHandling -object
+ *
+ * @leave System wide error code
+ */
+ IMPORT_C static CDrmUiHandling* NewL( CCoeEnv* aCoeEnv = NULL );
+
+ /**
+ * Creates a new CDrmUiHandling object and returns a pointer to it
+ * Leaves the pointer to the cleanup stack
+ *
+ * @param aCoeEnv A pointer to an instance of CCoeEnv. If the
+ * parameter is not provided the global instance
+ * will be used. In the case of a server process
+ * where the global instance is not available,
+ * global notes will be used.
+ *
+ * If no CCoeEnv instance is available, applications
+ * launched will be launched as standalone
+ * applications.
+ *
+ * @return A functional CDrmUiHandling -object
+ *
+ * @leave System wide error code
+ */
+
+ IMPORT_C static CDrmUiHandling* NewLC( CCoeEnv* aCoeEnv = NULL );
+
+ /**
+ * Destructor
+ */
+ virtual ~CDrmUiHandling();
+
+
+ /**
+ * Returns a reference to a CDrmUtility instance. The ownership
+ * of the instance stays with the CDrmUiHandling -class
+ *
+ * @since S60 v5.0
+ *
+ * @return A reference to a functional CDrmUtility instance
+ *
+ * @leave None
+ *
+ * @see CDrmUtility
+ */
+ IMPORT_C CDrmUtility& GetUtility() const;
+
+
+ /**
+ * Returns a reference to a class which implements the
+ * MDrmErrorHandling interface. The ownership
+ * of the instance stays with the CDrmUiHandling -class
+ *
+ * @since S60 v5.0
+ *
+ * @return A reference to a functional object implementing the
+ * MDrmErrorHandling interface
+ *
+ * @leave None
+ *
+ * @see MDrmErrorHandling
+ */
+ IMPORT_C MDrmErrorHandling& GetErrorHandler() const;
+
+
+ /**
+ * Check how much rights there are left for the content.
+ * This method also displays appropriate notes, which observer can
+ * override, if rights are invalid. Asynchronous version, all errors
+ * are signalled using request status.
+ *
+ * @since S60 v5.0
+ * @param[in] aFile file of which rights are checked.
+ * @param[in] aIntent the CAF intent to be used for checking
+ * @param[in] aObserver reference to observer
+ *
+ * @return Operation Identifier for the async request
+ * required for cancelling an operation and
+ * identifying which request has been completed
+ *
+ * @leave System wide error code
+ * KErrArgument if file is not DRM protected.
+ *
+ * @see MDrmUiCheckRightsObserver
+ * @see ContentAccess::TIntent
+ */
+ IMPORT_C TInt CheckRightsAmountAsyncL(
+ RFile& aFile,
+ ContentAccess::TIntent aIntent,
+ MDrmUiCheckRightsObserver& aObserver );
+
+ /**
+ * Check how much rights there are left for the content.
+ * This method also displays appropriate notes, which observer can
+ * override, if rights are invalid. Synchronous version, leaves in case
+ * of error.
+ *
+ * @since S60 v5.0
+ * @param[in] aFile file of which rights are checked.
+ * @param[in] aIntent the CAF intent to be used for checking
+ * @param[in] aObserver pointer to observer, NULL if no observer
+ *
+ * @return none
+ * @leave System wide error code
+ * KErrArgument if file is not DRM protected.
+ *
+ * @see MDrmUiCheckRightsObserver
+ * @see ContentAccess::TIntent
+ */
+ IMPORT_C void CheckRightsAmountL(
+ RFile& aFile,
+ ContentAccess::TIntent aIntent,
+ MDrmUiCheckRightsObserver* aObserver );
+
+ /**
+ * Check how much rights there are left for the content.
+ * This method also displays appropriate notes, which observer can
+ * override, if rights are invalid. Asynchronous version, all errors
+ * are signalled using request status.
+ *
+ * @since S60 v5.0
+ * @param[in] aFile content of which rights are checked.
+ * @param[in] aIntent the CAF intent to be used for checking
+ * @param[in] aObserver reference to observer
+ *
+ * @return Operation Identifier for the async request
+ * required for cancelling an operation and
+ * identifying which request has been completed
+ *
+ * @leave System wide error code
+ * KErrArgument if file is not DRM protected.
+ *
+ * @see MDrmUiCheckRightsObserver
+ * @see ContentAccess::TIntent
+ */
+ IMPORT_C TInt CheckRightsAmountAsyncL(
+ ContentAccess::CData& aFile,
+ ContentAccess::TIntent aIntent,
+ MDrmUiCheckRightsObserver& aObserver );
+
+ /**
+ * Check how much rights there are left for the content.
+ * This method also displays appropriate notes, which observer can
+ * override, if rights are invalid. Synchronous version, leaves in case
+ * of error.
+ *
+ * @since S60 v5.0
+ * @param[in] aFile content of which rights are checked.
+ * @param[in] aIntent the CAF intent to be used for checking
+ * @param[in] aObserver pointer to observer, NULL if no observer
+ * @return none
+ * @leave System wide error code
+ * KErrArgument if file is not DRM protected.
+ *
+ * @see MDrmUiCheckRightsObserver
+ * @see ContentAccess::TIntent
+ */
+ IMPORT_C void CheckRightsAmountL(
+ ContentAccess::CData& aFile,
+ ContentAccess::TIntent aIntent,
+ MDrmUiCheckRightsObserver* aObserver );
+
+ /**
+ * Displays information about rights for given content.
+ * Asynchronous version.
+ *
+ * @since S60 v5.0
+ * @param[in] aFile file for which rights details are
+ * displayed.
+ * @param[in] aObserver reference to observer
+ *
+ * @return Operation Identifier for the async request
+ * required for cancelling an operation and
+ * identifying which request has been completed
+ *
+ * @leave System wide error code
+ */
+ IMPORT_C TInt ShowDetailsViewAsyncL( RFile& aFile,
+ MDrmAsyncObserver& aObserver );
+
+ /**
+ * Displays information about rights for given content.
+ * Synchronous version, leaves in case of error.
+ *
+ * @since S60 v5.0
+ * @param[in] aFile file for which rights details are
+ * displayed.
+ *
+ * @leave KErrArgument File is not DRM protected.
+ * @leave KErrCANoRights Rights object does not exist.
+ *
+ * @see caferr.h
+ */
+ IMPORT_C void ShowDetailsViewL( RFile& aFile );
+
+ /**
+ * Displays information about rights for given content.
+ * Asynchronous version.
+ *
+ * @since S60 v5.0
+ * @param[in] aFile content for which rights details are
+ * displayed.
+ * @param[in] aObserver reference to observer
+ *
+ * @return Operation Identifier for the async request
+ * required for cancelling an operation and
+ * identifying which request has been completed
+ *
+ * @leave System wide error code
+ */
+ IMPORT_C TInt ShowDetailsViewAsyncL( ContentAccess::CData& aFile,
+ MDrmAsyncObserver& aObserver );
+
+ /**
+ * Displays information about rights for given content.
+ * Synchronous version, leaves in case of error.
+ *
+ * @since S60 v5.0
+ * @param[in] aFile content for which rights details are displayed.
+ *
+ * @leave KErrArgument Content is not DRM protected.
+ * @leave KErrCANoRights Rights object does not exist.
+ * @leave System wide error code
+ *
+ * @see caferr.h
+ */
+ IMPORT_C void ShowDetailsViewL( ContentAccess::CData& aFile );
+
+
+ /**
+ * Handle the specific url defined by the file, such as InfoUrl
+ * Asynchronous method
+ *
+ * @since S60 v5.0
+ * @param[in] aFile file whose url is being handled
+ * @param[in] aType type of the requested url,
+ * only a single url may be requested
+ * at a time
+ * @param[in] aObserver reference to observer
+ *
+ * @return Operation Identifier for the async request
+ * required for cancelling an operation and
+ * identifying which request has been completed
+ *
+ * @leave KErrArgument File is not DRM protected.
+ * @leave KErrNotSupported Url type is not supported for the file
+ */
+ IMPORT_C TInt HandleUrlAsyncL(
+ RFile& aFile,
+ TDrmUiUrlType aType,
+ MDrmAsyncObserver& aObserver );
+
+
+ /**
+ * Handle the specific url defined by the file, such as InfoUrl
+ *
+ * @since S60 v5.0
+ * @param[in] aFile file whose url is being handled
+ * @param[in] aType type of the requested url,
+ * only a single url may be requested
+ * at a time
+ *
+ * @leave KErrArgument File is not DRM protected.
+ * @leave KErrNotSupported Url type is not supported for the file
+ */
+ IMPORT_C void HandleUrlL(
+ RFile& aFile,
+ TDrmUiUrlType aType );
+
+ /**
+ * Handle the specific url defined by the file, such as InfoUrl
+ * Asynchronous method
+ *
+ * @since S60 v5.0
+ * @param[in] aFile content whose url is being handled
+ * @param[in] aType type of the requested url,
+ * only a single url may be requested
+ * at a time
+ * @param[in] aObserver reference to observer
+ *
+ * @return Operation Identifier for the async request
+ * required for cancelling an operation and
+ * identifying which request has been completed
+ *
+ * @leave KErrArgument File is not DRM protected,
+ * or multiple url:s were requested
+ * @leave KErrNotSupported Url type is not supported for the file
+ */
+ IMPORT_C TInt HandleUrlAsyncL(
+ ContentAccess::CData& aFile,
+ TDrmUiUrlType aType,
+ MDrmAsyncObserver& aObserver );
+
+ /**
+ * Handle the specific url defined by the file, such as InfoUrl
+ *
+ * @since S60 v5.0
+ * @param[in] aFile content whose url is being handled
+ * @param[in] aType type of the requested url,
+ * only a single url may be requested
+ * at a time
+ *
+ * @leave KErrArgument File is not DRM protected.
+ * @leave KErrNotSupported Url type is not supported for the file
+ */
+ IMPORT_C void HandleUrlL(
+ ContentAccess::CData& aFile,
+ TDrmUiUrlType aType );
+
+
+ /**
+ * Get information of the available urls
+ * Asynchronous method
+ *
+ * @since S60 v5.0
+ * @param[in] aFile file whose url is being handled
+ * @param[out] aType A bitmask of the supported url types
+ * @param[in] aObserver reference to observer
+ *
+ * @return Operation Identifier for the async request
+ * required for cancelling an operation and
+ * identifying which request has been completed
+ *
+ * @leave KErrArgument File is not DRM protected.
+ */
+ IMPORT_C TInt AvailableUrlsAsyncL(
+ RFile& aFile,
+ TDrmUiUrlType& aType,
+ MDrmAsyncObserver& aObserver );
+
+ /**
+ * Get information of the available urls
+ *
+ * @since S60 v5.0
+ * @param[in] aFile file whose url is being handled
+ * @param[out] aType A bitmask of the supported url types
+ *
+ * @leave KErrArgument File is not DRM protected.
+ */
+ IMPORT_C void AvailableUrlsL(
+ RFile& aFile,
+ TDrmUiUrlType& aType );
+
+
+ /**
+ * Get information of the available urls
+ * Asynchronous method
+ *
+ * @since S60 v5.0
+ * @param[in] aFile content whose url is being handled
+ * @param[out] aType A bitmask of the supported url types
+ * @param[in] aObserver reference to observer
+ *
+ * @return Operation Identifier for the async request
+ * required for cancelling an operation and
+ * identifying which request has been completed
+ *
+ * @leave KErrArgument File is not DRM protected.
+ */
+ IMPORT_C TInt AvailableUrlsAsyncL(
+ ContentAccess::CData& aFile,
+ TDrmUiUrlType& aType,
+ MDrmAsyncObserver& aObserver );
+
+ /**
+ * Get information of the available urls
+ *
+ * @since S60 v5.0
+ * @param[in] aFile content whose url is being handled
+ * @param[out] aType A bitmask of the supported url types
+ *
+ * @leave KErrArgument File is not DRM protected.
+ */
+ IMPORT_C void AvailableUrlsL(
+ ContentAccess::CData& aFile,
+ TDrmUiUrlType& aType );
+
+
+ /**
+ * Cancel an asyncronous operation
+ *
+ * @since S60 v5.0
+ * @param[in] aOperationId identifier of the async operation
+ * to be cancelled
+ * @return KErrNotFound if the operation has already been executed
+ * or it does not exist
+ */
+ IMPORT_C TInt CancelOperation( TInt aOperationId );
+
+
+private:
+ /**
+ * Default Constructor
+ */
+ CDrmUiHandling();
+
+ /**
+ * 2nd phase constructor
+ */
+ void ConstructL( CCoeEnv* aCoeEnv );
+
+private: // data
+
+ /**
+ * Pointer to the implementation
+ * Owned
+ */
+ CDrmUiHandlingImpl* iImplementation;
+
+ /**
+ * Pointer to a CDrmUtility -Instance
+ * Owned
+ */
+ CDrmUtility* iUtility;
+
+ /**
+ * Pointer to an MDrmErrorHandling interface class instance
+ * Owned
+ */
+ MDrmErrorHandling* iErrorHandler;
+
+ };
+ }
+
+
+
+#endif // C_CDRMUIHANDLING_H