/*

* Copyright (c) 2004 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:  Reactive authorization request interface.

*

*/

#ifndef __MPENGAUTHORIZATIONREQUEST_H

#define __MPENGAUTHORIZATIONREQUEST_H

//  INCLUDES

#include <E32Std.h>

// FORWARD DECLARATIONS

class MPEngAuthorizationRequestExt;

// CLASS DECLARATION

/**

 * Interface for reactive authorization request.

 *

 * @since 3.0

 */

class MPEngAuthorizationRequest

    {

    public: // Authorization Request State

        /**

         * Reactive authorization request state.

         *

         * @since 3.0

         */

        enum TPEngAuthorizationRequestState

            {

            // Authorization request is waiting for answer

            EPEngAuthPending        = 0x00001,

            // Authorization request was already answered

            EPEngAuthAnswered       = 0x00002

            };

        /**

         * Reactive authorization responses.

         *

         * @since 3.0

         */

        enum TPEngAuthorizationResponseType

            {

            //Authorization isn't yet responded

            EPEngAuthUndefined      = 0x00000,

            //Authorization was accepted

            EPEngAuthAccepted       = 0x00001,

            //Authorization was denied

            EPEngAuthDenied         = 0x00002,

            //Authorization was canceled

            EPEngAuthCanceled       = 0x00003

            };

    public: // Access to authorization request details

        /**

         * Identification of requesting user.

         *

         * Gets identification of requesting user.

         *

         * @since 3.0

         * @return Id of the requesting user.

         */

        virtual const TDesC& UserId() const = 0;

        /**

         * List of requested attributes.

         *

         * Gets list of requested attributes.

         *

         * @since 3.0

         * @return Array of requested attributes.

         */

        virtual const RArray<TUint32>& RequestedAttributes() const = 0;

        /**

         * State of the authorization request.

         *

         * Gets state of the authorization request.

         *

         * @since 3.0

         * @return State of the authorization request.

         */

        virtual TPEngAuthorizationRequestState AuthorizationState() const = 0;

        /**

         * State of the authorization response

         *

         * Gets state of the authorization response.

         *

         * If authorization response state is EPEngAuthUndefined,

         * it means that there has not been yet any response to this

         * authorization request.

         *

         * If authorization request was reissued by networ server,

         * authorization is put again in EPEngAuthPending state,

         * and response state remains in last authorization response.

         *

         * @since 3.0

         * @return state of the authorization

         */

        virtual TPEngAuthorizationResponseType AuthorizationResponse() const = 0;

        /**

         * List of authorized attributes.

         *

         * Gets the list of currently authorized attributes.

         *

         * @since 3.0

         * @return The list of currently authorized attributes.

         */

        virtual const RArray<TUint32>& AuthorizedAttributes() const = 0;

    public: //Authorization response handling

        /**

         * Authorizes the request with given attribute set.

         *

         * Authorizes the request with attribute set.

         * Pending authorization request can be:

         *  - Authorized with SetAuthorizedAttributesL()

         *  - Denied with DenyAuthorizationL()

         *

         * Already responded authorization request can be:

         *  - Reauthorized: SetAuthorizedAttributesL()

         *    New authorization overwrites previous response.

         *  - Canceled: CancelAuthorizationL()

         *

         * Prior client can perform response handling operations,

         * it needs to have open MPEngAuthorizationRespond object.

         * Individual authorization responses are buffered to

         * MPEngAuthorizationRespond object from which thay are

         * published to network at once.

         *

         * @since 3.0

         * @param aAttributes Attributes to be authorized.

         * @param aKeepOldAuthorization If ETrue, then

         *        already authorized attributes are kept.

         *        If EFalse, new attribute set overwrites

         *        previous attribute set.

         */

        virtual void SetAuthorizedAttributesL(

            TArray<TUint32>& aAttributes,

            TBool aKeepOldAuthorization = ETrue ) = 0;

        /**

         * Denies authorization request.

         *

         * @since 3.0

         * @see SetAuthorizedAttributesL()

         */

        virtual void DenyAuthorizationL() = 0;

        /**

         * Cancels existing authorization.

         *

         * @since 3.0

         * @see SetAuthorizedAttributesL()

         */

        virtual void CancelAuthorizationL() = 0;

        /**

         * Undo the authorization response.

         *

         * Undo the authorization response.

         * Removes response from among other

         * buffered responses.

         *

         * @since 3.0

         */

        virtual void RemoveAuthorizationResponse() = 0;

    private: //Extensions interfaces

        /**

         * Reactive authorization request extension interface.

         *

         * @since 3.0

         * @return Reactive authorization request extension.

         */

        virtual MPEngAuthorizationRequestExt* Extension() = 0;

        virtual const MPEngAuthorizationRequestExt* Extension() const = 0;

    protected:  //Destructor

        /**

         * Virtual inline destructor.

         * Protected destructor to prohibits deletion

         * through the interface.

         */

        virtual ~MPEngAuthorizationRequest() {};

    };

#endif      //  __MPENGAUTHORIZATIONREQUEST_H

//  End of File