diff -r 000000000000 -r 95b198f216e5 drm_plat/drm_utility_api/inc/drmautomatedusage.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/drm_plat/drm_utility_api/inc/drmautomatedusage.h Thu Dec 17 08:52:27 2009 +0200 @@ -0,0 +1,587 @@ +/* +* Copyright (c) 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: Provides operations for automated usage of DRM content +* +*/ + + +#ifndef CDRMAUTOMATEDUSAGE_H +#define CDRMAUTOMATEDUSAGE_H + +#include +#include + +#include +#include + +#include +#include +#include +#include + + + +class CCoeEnv; + +namespace DRM +{ +class CDrmAutomatedUsageImpl; + +/** +* Utility class for DRM related automated usage handling +* +* Usage: +* @code +* #include +* // Instantiate class CDrmAutomatedUsage +* DRM::CDrmAutomatedUsage* iAutomatedUsage = +* DRM::CDrmAutomatedUsage::NewLC(); +* // ... +* // RFile myRingToneFile; +* // open my Ringtone for reading +* // ... +* ContentAccess::CData* myDataObject = ContentAccess::CData::NewL( +* myRingToneFile, +* ContentAccess::KDefaultContentObject, +* ContentAccess::EPeek ); +* // check if content can be set as automated +* if ( iAutomatedUsage->CanSetAutomatedL( +* myDataObject, +* ContentAccess::EPlay, +* DRM::EAUAutomatedTypeRingingTone ) ) +* { +* // automated usage allowed +* +* // we register content as ringing tone in this example +* iAutomatedUsage->SetAutomated( +* myDataObject, +* ContentAccess::EPlay, +* DRM::EAUAutomatedTypeRingingTone, +* DRM::EAUPassive ); +* +* } +* else +* { +* // automated usage not allowed +* } +* @endcode +* +* @lib drmautomatedusage.lib +* @since S60 5.0 +*/ +NONSHARABLE_CLASS( CDrmAutomatedUsage ) : public CBase + { +public: + + /** + * Creates a new CDrmAutomatedUsage object and returns a pointer to it + * + * @since S60 5.0 + * + * @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 CDrmAutomatedUsage -object + * + * @leave System wide error code + * + * @see CCoeEnv + * + */ + IMPORT_C static CDrmAutomatedUsage* NewL( CCoeEnv* aCoeEnv = NULL ); + + + /** + * Creates a new CDrmAutomatedUsage object and returns a pointer to it + * Leaves the pointer to the cleanup stack + * + * @since S60 5.0 + * + * @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 CDrmAutomatedUsage -object + * + * @leave System wide error code + * + * @see CCoeEnv + * + */ + IMPORT_C static CDrmAutomatedUsage* NewLC( CCoeEnv* aCoeEnv = NULL ); + + + /** + * Destructor + */ + virtual ~CDrmAutomatedUsage(); + + + /** + * Returns a reference to a CDrmUtility instance. The ownership + * of the instance stays with the CDrmAutomatedUsage -class + * + * @since S60 5.0 + * + * @return A reference to a functional CDrmUtility instance + * + * @see DRM::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 CDrmAutomatedUsage -class + * + * @since S60 5.0 + * + * @return A reference to a functional object implementing the + * MDrmErrorHandling interface + * + * @see DRM::MDrmErrorHandling + */ + IMPORT_C MDrmErrorHandling& GetErrorHandler() const; + + + /** + * Checks if given content can be set as an automated content. + * + * @since S60 5.0 + * + * @param[in] aFile file handle to the file + * @param[in] aIntent See ContentAccess::Intent + * @param[in] AutomatedType Usage intention of the automated content + * + * @return ETrue if the content can be set as automated content + * EFalse if the content can't be set as automated content + * + * @leave System wide or DRM specific error code. + * + * @see RFile + * @see ContentAccess::TIntent + * @see DRM::TDrmAutomatedType + */ + IMPORT_C TBool CanSetAutomatedL( + RFile& aFile, + const ContentAccess::TIntent aIntent, + const TDrmAutomatedType aAutomatedType ); + + + /** + * Checks if given content can be set as an automated content. + * + * @since S60 5.0 + * + * @param[in] aData CData object to the protected content + * @param[in] aIntent See ContentAccess::Intent + * @param[in] AutomatedType Usage intention of the automated content + * + * @return ETrue if the content can be set as automated content + * EFalse if the content can't be set as automated content + * + * @leave System wide or DRM specific error code. + * + * @see ContentAccess::CData + * @see ContentAccess::TIntent + * @see DRM::TDrmAutomatedType + */ + IMPORT_C TBool CanSetAutomatedL( + const ContentAccess::CData& aData, + const ContentAccess::TIntent aIntent, + const TDrmAutomatedType aAutomatedType ); + + + /** + * Registers given content to be used as an automated content. + * + * @since S60 5.0 + * + * @param[in] aFile file handle to the file + * @param[in] aIntent See ContentAccess::Intent + * @param[in] aAutomatedType Usage intention of the automated content + * @param[in] aServiceType default: EAUActive + * + * @leave System wide or DRM specific error code. + * + * @see RFile + * @see ContentAccess::TIntent + * @see DRM::TDrmAutomatedType + * @see DRM::TDrmAutomatedServiceType + */ + IMPORT_C void SetAutomatedL( + RFile& aFile, + const ContentAccess::TIntent aIntent, + const TDrmAutomatedType aAutomatedType, + const TDrmAutomatedServiceType aServiceType = EAUActive ); + + + /** + * Registers given content to be used as an automated content. + * + * @since S60 5.0 + * + * @param[in] aFile file handle to the file + * @param[in] aIntent See ContentAccess::Intent + * @param[in] aAutomatedType Usage intention of the automated content + * @param[in] aObserver Async callback observer + * @param[in] aServiceType default: EAUActive + * + * @return Operation Identifier for the async request + * required for cancelling an operation and + * identifying which request has been completed + * + * @leave System wide or DRM specific error code. + * + * @see RFile + * @see ContentAccess::TIntent + * @see DRM::TDrmAutomatedType + * @see DRM::MDrmAsyncObserver + * @see DRM::TDrmAutomatedServiceType + * + */ + IMPORT_C TInt SetAutomatedAsyncL( + RFile& aFile, + const ContentAccess::TIntent aIntent, + const TDrmAutomatedType aAutomatedType, + MDrmAsyncObserver& aObserver, + const TDrmAutomatedServiceType aServiceType = EAUActive ); + + + /** + * Registers given content to be used as an automated content. + * + * @since S60 5.0 + * + * @param[in] aData CData object to the protected content + * @param[in] aIntent See ContentAccess::Intent + * @param[in] aAutomatedType Usage intention of the automated content + * @param[in] aServiceType default: EAUActive + * + * @leave System wide or DRM specific error code. + * + * @see ContentAccess::CData + * @see ContentAccess::TIntent + * @see DRM::TDrmAutomatedType + * @see DRM::TDrmAutomatedServiceType + */ + IMPORT_C void SetAutomatedL( + const ContentAccess::CData& aData, + const ContentAccess::TIntent aIntent, + const TDrmAutomatedType aAutomatedType, + const TDrmAutomatedServiceType aServiceType = EAUActive ); + + + /** + * Registers given content to be used as an automated content. + * + * @since S60 5.0 + * + * @param[in] aData CData object to the protected content + * @param[in] aIntent See ContentAccess::Intent + * @param[in] aAutomatedType Usage intention of the automated content + * @param[in] aObserver Async callback observer + * @param[in] aServiceType default: EAUActive + * + * @return Operation Identifier for the async request + * required for cancelling an operation and + * identifying which request has been completed + * + * @leave System wide or DRM specific error code. + * + * @see ContentAccess::CData + * @see ContentAccess::TIntent + * @see DRM::TDrmAutomatedType + * @see DRM::MDrmAsyncObserver + * @see DRM::TDrmAutomatedServiceType + */ + IMPORT_C TInt SetAutomatedAsyncL( + const ContentAccess::CData& aData, + const ContentAccess::TIntent aIntent, + const TDrmAutomatedType aAutomatedType, + MDrmAsyncObserver& aObserver, + const TDrmAutomatedServiceType aServiceType = EAUActive ); + + + /** + * Unregisters given content from being used as an automated content. + * + * @since S60 5.0 + * + * @param[in] aFile file handle to the file + * @param[in] aIntent See ContentAccess::Intent + * @param[in] aAutomatedType Usage intention of the automated content + * @param[in] aServiceType default: EAUActive + * + * @leave System wide or DRM specific error code. + * + * @see RFile + * @see ContentAccess::TIntent + * @see DRM::TDrmAutomatedType + * @see DRM::TDrmAutomatedServiceType + */ + IMPORT_C void RemoveAutomatedL( + RFile& aFile, + const ContentAccess::TIntent aIntent, + const TDrmAutomatedType aAutomatedType, + const TDrmAutomatedServiceType aServiceType = EAUActive ); + + + /** + * Unregisters given content from being used as an automated content. + * + * @since S60 5.0 + * + * @param[in] aFile file handle to the file + * @param[in] aIntent See ContentAccess::Intent + * @param[in] aAutomatedType Usage intention of the automated content + * @param[in] aObserver Async callback observer + * @param[in] aServiceType default: EAUActive + * + * @return Operation Identifier for the async request + * required for cancelling an operation and + * identifying which request has been completed + * + * @leave System wide or DRM specific error code. + * + * @see RFile + * @see ContentAccess::TIntent + * @see DRM::TDrmAutomatedType + * @see DRM::MDrmAsyncObserver + * @see DRM::TDrmAutomatedServiceType + */ + IMPORT_C TInt RemoveAutomatedAsyncL( + RFile& aFile, + const ContentAccess::TIntent aIntent, + const TDrmAutomatedType aAutomatedType, + MDrmAsyncObserver& aObserver, + const TDrmAutomatedServiceType aServiceType = EAUActive ); + + + /** + * Unregisters given content from being used as an automated content. + * + * @since S60 5.0 + * + * @param[in] aData CData object to the protected content + * @param[in] aIntent See ContentAccess::Intent + * @param[in] aAutomatedType Usage intention of the automated content + * @param[in] aServiceType default: EAUActive + * + * @leave System wide or DRM specific error code. + * + * @see ContentAccess::CData + * @see ContentAccess::TIntent + * @see DRM::TDrmAutomatedType + * @see DRM::TDrmAutomatedServiceType + */ + IMPORT_C void RemoveAutomatedL( + const ContentAccess::CData& aData, + const ContentAccess::TIntent aIntent, + const TDrmAutomatedType aAutomatedType, + const TDrmAutomatedServiceType aServiceType = EAUActive ); + + + /** + * Unregisters given content from being used as an automated content. + * + * @since S60 5.0 + * + * @param[in] aData CData object to the protected content + * @param[in] aIntent See ContentAccess::Intent + * @param[in] aAutomatedType Usage intention of the automated content + * @param[in] aObserver Async callback observer + * @param[in] aServiceType default: EAUActive + * + * @return Operation Identifier for the async request + * required for cancelling an operation and + * identifying which request has been completed + * + * @leave System wide or DRM specific error code. + * + * @see ContentAccess::CData + * @see ContentAccess::TIntent + * @see DRM::TDrmAutomatedType + * @see DRM::MDrmAsyncObserver + * @see DRM::TDrmAutomatedServiceType + */ + IMPORT_C TInt RemoveAutomatedAsyncL( + const ContentAccess::CData& aData, + const ContentAccess::TIntent aIntent, + const TDrmAutomatedType aAutomatedType, + MDrmAsyncObserver& aObserver, + const TDrmAutomatedServiceType aServiceType = EAUActive ); + + + /** + * Unregisters given content from being used as an automated content. + * + * @since S60 5.0 + * + * @param[in] aUniqueId unique content id + * @param[in] aIntent See ContentAccess::Intent + * @param[in] aAutomatedType Usage intention of the automated content + * @param[in] aServiceType default: EAUActive + * + * @leave System wide or DRM specific error code. + * + * @see ContentAccess::TIntent + * + * @see ContentAccess::CData::GetStringAttribute() + * @see ContentAccess::TStringAttribute + * @see ContentAccess::TIntent + * @see DRM::TDrmAutomatedType + * @see DRM::TDrmAutomatedServiceType + */ + IMPORT_C void RemoveAutomatedL( + const TDesC& aUniqueId, + const ContentAccess::TIntent aIntent, + const TDrmAutomatedType aAutomatedType, + const TDrmAutomatedServiceType aServiceType = EAUActive ); + + + /** + * Unregisters given content from being used as an automated content. + * + * @since S60 5.0 + * + * @param[in] aUniqueId unique content id + * @param[in] aIntent See ContentAccess::Intent + * @param[in] aAutomatedType Usage intention of the automated content + * @param[in] aObserver Async callback observer + * @param[in] aServiceType default: EAUActive + * + * @return Operation Identifier for the async request + * required for cancelling an operation and + * identifying which request has been completed + * + * @leave System wide or DRM specific error code. + * + * @see ContentAccess::CData::GetStringAttribute() + * @see ContentAccess::TStringAttribute + * @see ContentAccess::TIntent + * @see DRM::TDrmAutomatedType + * @see DRM::MDrmAsyncObserver + * @see DRM::TDrmAutomatedServiceType + */ + IMPORT_C TInt RemoveAutomatedAsyncL( + const TDesC& aUniqueId, + const ContentAccess::TIntent aIntent, + const TDrmAutomatedType aAutomatedType, + MDrmAsyncObserver& aObserver, + const TDrmAutomatedServiceType aServiceType = EAUActive ); + + + /** + * Registers client to listen events related to automated usage. If + * the client doesn't do this, all the events are handled automatically + * according to the S60 style. + * + * The observer registered with this function needs to be unregistered + * before it is deleted. + * + * @since S60 5.0 + * + * @param[in] aObserver + * + * @leave System wide or DRM specific error code. + * + * @see DRM::MDrmAutomatedUsageObserver + */ + IMPORT_C void RegisterEventObserverL( + MDrmAutomatedUsageObserver& aObserver ); + + + /** + * Unregisters client from listening to events related to automated usage. + * + * If register event observer has been called, it must be unregistered + * before the observer object is deleted. + * + * @since S60 5.0 + * + * @param[in] aObserver + * + * @leave System wide or DRM specific error code. + * + * @see DRM::MDrmAutomatedUsageObserver + */ + IMPORT_C void UnregisterEventObserverL( + MDrmAutomatedUsageObserver& aObserver ); + + + /** + * Cancel an asyncronous operation + * + * @since S60 5.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: // member functions + + /** + * Default constructor + */ + CDrmAutomatedUsage(); + + + /** + * Second phase constructor + */ + void ConstructL( CCoeEnv* aCoeEnv ); + + +private: // data members + /** + * Implementation class pointer + * Owned + */ + CDrmAutomatedUsageImpl* iImplementation; + + /** + * Implementation class pointer + * Owned + */ + MDrmErrorHandling* iErrorHandler; + + /** + * Implementation class pointer + * Owned + */ + CDrmUtility* iUtility; + }; +} + + +#endif // CDRMAUTOMATEDUSAGE_H