/*

* Copyright (c) 2008 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:  Haptics server reservation handler header file 

*

*/

#ifndef C_HWRMHAPTICSRESERVATIONHANDLER_H

#define C_HWRMHAPTICSRESERVATIONHANDLER_H

#include <e32base.h>

class CHWRMHapticsService;

class CHWRMHapticsPolicy;

/**

 *  Handles reservations of haptics resource. 

 *

 *  @since S60 5.1

 */

class CHWRMHapticsReservationHandler : public CBase

    {

public:

    /**

     * Two-phased constructor.

     *

     * @param aPolicyFilename Policy file name without path.

     */

    IMPORT_C static CHWRMHapticsReservationHandler* NewL( 

            const TDesC& aPolicyFilename );

    /**

     * Destructor.

     */

    virtual ~CHWRMHapticsReservationHandler();

public:

    /**

     * Reserves haptics for the given service.

     *

     * @param aSid Secure Id identifying the reserving client.

     * @param aForceNoCCoeEnv Indicates if reservation is done in force 

     *        CCoeEnv mode.

     * @param aServiceCallback The callback of service requesting 

     *        reservation check. 

     * @leave KErrAccessDenied if trying to force no CCoeEnv and client 

     *        is not trusted.

     * @return Whether or not the reservation was suspended (i.e. some other 

     *         service with higher priority has an active reservation).

     */

    TBool ReserveL( TSecureId aSid, 

                    TBool aForceNoCCoeEnv, 

                    CHWRMHapticsService* aServiceCallback );

    /**

     * Release haptics for the given service.

     *

     * @param aServiceCallback The callback of service requesting release 

     * @return Whether or not there is an active reservation after the

     *         release of the given service.

     */

    TBool Release( CHWRMHapticsService* aServiceCallback );

    /**

     * Checks whether or not haptics is reserved for some other service

     * than the given one.

     *

     * @param aServiceCallback Service requesting reservation check.

     * @return ETrue if resource is reserved for some other service

     *         than the requester. EFalse otherwise.

     */

    TBool IsReserved( const CHWRMHapticsService* aServiceCallback ) const;

    /**

     * Checks whether or not haptics is reserved for the given client.

     *

     * @param aServiceCallback Service requesting reservation check.

     * @return ETrue if resource is reserved the given service.

     */

    TBool ActiveReservation( const CHWRMHapticsService* aServiceCallback ) const;

    /**

     * Checks whether or not the priority of the client who has 

     * active reservation has higher priority than the currently

     * calling one.

     *

     * @param aSid Secure ID of the calling client.

     * @return ETrue if reserved client's priority is higher or equal

     *         to caller's priority. EFalse if caller's priority is higher

     *         than that of current reservation.

     */

    TBool ReservedPriorityHigher( TSecureId aSid ) const;

    /**

     * Sets the priority of a client.

     *

     * @param aSid Secure ID identifying the calling client.

     * @param aPriority Priority value.

     */

    void SetPriorityL( TSecureId aSid, TInt aPriority );

    /**

     * Removes the priority of a client. This method is used in the

     * cleanup phase of a service object, so that no unnecessary

     * priority values would be stored in the server.

     *

     * @param aSid Secure ID identifying the calling client.

     */

    void RemovePriority( TSecureId aSid );

    /**

     * Fetches the priority of a client identified using the given

     * secure id. If the priority is not found from the internal 

     * priority array (i.e. client has not set it), the priority 

     * value in the policy file is used. If not found from the 

     * policy file either, default value is used.

     *

     * @param aSid Secure ID identifying the calling client.

     * @param aTrusted On return specifies whether or not 

     * the client with the given secure Id is trusted 

     * (i.e. its priority is defined in a policy file). 

     * The value is set to ETrue, if the client is trusted,

     * EFalse otherwise.

     * @param aPriority The priority of the client.

     */

    void GetPriority( TSecureId aSid, TBool& aTrusted, TInt &aPriority ) const;

private:

    /**

     * Embedded class to contain reservation data.

     * All data members are public as this is basically a struct.

     *

     * @since S60 5.1

     */

    class TReservationData

        {

    public:

        /**

         * C++ constructor.

         */

        TReservationData()

            : iCallback( NULL ), iPriority( KMaxTInt ), iSuspendedData( NULL )

            {

            // nothing to do

            };

    public: // data

        /**

         * Service callback of the reserver. Not owned.

         */

        CHWRMHapticsService* iCallback;

        /**

         * Priority of the reservation

         */

        TInt iPriority;

        /**

         * Link for first suspended data. Not owned.

         */

        TReservationData* iSuspendedData;

        };

    /**

     * Structure for storing priority values of a single client.

     *

     * @since S60 5.1

     */

    struct TPriority

        {

        /**

         * C++ constructor.

         */

        TPriority( TSecureId aSid, TInt aPriority )

            : iSid( aSid ), iPriority( aPriority )

            {

            // nothing to do

            };

        /**

         * Secure ID identifying the client.

         */

        TSecureId iSid;

        /**

         * Priority of a client.

         */

        TInt iPriority;

        };

private:

    /**

     * C++ constructor.

     */

    CHWRMHapticsReservationHandler();

    /**

     * By default Symbian 2nd phase constructor is private.

     *

     * @param aPolicyFilename Policy file name. Must not include path.

     */

    void ConstructL( const TDesC& aPolicyFilename );

    /**

     * Returns whether or not a reservation exists for the given service.

     *

     * @param aService Service object, which may already have a reservation.

     * @return ETrue if a reservation exists for the given service,

     *         EFalse otherwise

     */

    TBool AlreadyReserved( const CHWRMHapticsService* aService ) const;

    /**

     * Notifies the callback in the given reservation data about

     * suspension of its reservation.

     *

     * @aData Reservation data, whose callback is notified.

     */

    void NotifySuspend( TReservationData* aData ) const;

    /**

     * Notifies the callback in the given reservation data about

     * resume of its reservation.

     *

     * @aData Reservation data, whose callback is notified.

     */

    void NotifyResume( TReservationData* aData ) const;

private: // Data

    /**

     * Pointer to policy. Owned.

     */

    CHWRMHapticsPolicy* iPolicy;

    /**

     * Reservation data. Suspended reservations are linked via 

     * iSuspendedData -pointers. Suspended reservations arrange in 

     * priority order. If NULL, there are no reservations.

     */

    TReservationData* iReservation;

    /**

     * Array of priorities or all clients received from SetPriority -commands.

     * If the priority is not found from this array nor in the priority file,

     * default priority is used for that client.

     */

    RArray<TPriority> iPriorities;

    };

#endif // C_HWRMHAPTICSRESERVATIONHANDLER_H 

// End of File