/*

* 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