1 /*

     2 * Copyright (c) 2008 Nokia Corporation and/or its subsidiary(-ies). 

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  Haptics server reservation handler header file 

    15 *

    16 */

    17 

    18 

    19 #ifndef C_HWRMHAPTICSRESERVATIONHANDLER_H

    20 #define C_HWRMHAPTICSRESERVATIONHANDLER_H

    21 

    22 #include <e32base.h>

    23 

    24 class CHWRMHapticsService;

    25 class CHWRMHapticsPolicy;

    26 

    27 

    28 /**

    29  *  Handles reservations of haptics resource. 

    30  *

    31  *  @since S60 5.1

    32  */

    33 class CHWRMHapticsReservationHandler : public CBase

    34     {

    35 public:

    36         

    37     /**

    38      * Two-phased constructor.

    39      *

    40      * @param aPolicyFilename Policy file name without path.

    41      */

    42     IMPORT_C static CHWRMHapticsReservationHandler* NewL( 

    43             const TDesC& aPolicyFilename );

    44         

    45     /**

    46      * Destructor.

    47      */

    48     virtual ~CHWRMHapticsReservationHandler();

    49         

    50 public:

    51     

    52     /**

    53      * Reserves haptics for the given service.

    54      *

    55      * @param aSid Secure Id identifying the reserving client.

    56      * @param aForceNoCCoeEnv Indicates if reservation is done in force 

    57      *        CCoeEnv mode.

    58      * @param aServiceCallback The callback of service requesting 

    59      *        reservation check. 

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

    61      *        is not trusted.

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

    63      *         service with higher priority has an active reservation).

    64      */

    65     TBool ReserveL( TSecureId aSid, 

    66                     TBool aForceNoCCoeEnv, 

    67                     CHWRMHapticsService* aServiceCallback );

    68 

    69     /**

    70      * Release haptics for the given service.

    71      *

    72      * @param aServiceCallback The callback of service requesting release 

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

    74      *         release of the given service.

    75      */

    76     TBool Release( CHWRMHapticsService* aServiceCallback );

    77 

    78     /**

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

    80      * than the given one.

    81      *

    82      * @param aServiceCallback Service requesting reservation check.

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

    84      *         than the requester. EFalse otherwise.

    85      */

    86     TBool IsReserved( const CHWRMHapticsService* aServiceCallback ) const;

    87 

    88     /**

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

    90      *

    91      * @param aServiceCallback Service requesting reservation check.

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

    93      */

    94     TBool ActiveReservation( const CHWRMHapticsService* aServiceCallback ) const;

    95     

    96     /**

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

    98      * active reservation has higher priority than the currently

    99      * calling one.

   100      *

   101      * @param aSid Secure ID of the calling client.

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

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

   104      *         than that of current reservation.

   105      */

   106     TBool ReservedPriorityHigher( TSecureId aSid ) const;

   107     

   108     /**

   109      * Sets the priority of a client.

   110      *

   111      * @param aSid Secure ID identifying the calling client.

   112      * @param aPriority Priority value.

   113      */

   114     void SetPriorityL( TSecureId aSid, TInt aPriority );

   115 

   116     /**

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

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

   119      * priority values would be stored in the server.

   120      *

   121      * @param aSid Secure ID identifying the calling client.

   122      */

   123     void RemovePriority( TSecureId aSid );

   124 

   125     /**

   126      * Fetches the priority of a client identified using the given

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

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

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

   130      * policy file either, default value is used.

   131      *

   132      * @param aSid Secure ID identifying the calling client.

   133      * @param aTrusted On return specifies whether or not 

   134      * the client with the given secure Id is trusted 

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

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

   137      * EFalse otherwise.

   138      * @param aPriority The priority of the client.

   139      */

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

   141 

   142 private:

   143     

   144     /**

   145      * Embedded class to contain reservation data.

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

   147      *

   148      * @since S60 5.1

   149      */

   150     class TReservationData

   151         {

   152     public:

   153 

   154         /**

   155          * C++ constructor.

   156          */

   157         TReservationData()

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

   159             {

   160             // nothing to do

   161             };

   162 

   163     public: // data

   164                 

   165         /**

   166          * Service callback of the reserver. Not owned.

   167          */

   168         CHWRMHapticsService* iCallback;

   169 

   170         /**

   171          * Priority of the reservation

   172          */

   173         TInt iPriority;

   174         

   175         /**

   176          * Link for first suspended data. Not owned.

   177          */

   178         TReservationData* iSuspendedData;

   179         };

   180 

   181     /**

   182      * Structure for storing priority values of a single client.

   183      *

   184      * @since S60 5.1

   185      */

   186     struct TPriority

   187         {

   188         /**

   189          * C++ constructor.

   190          */

   191         TPriority( TSecureId aSid, TInt aPriority )

   192             : iSid( aSid ), iPriority( aPriority )

   193             {

   194             // nothing to do

   195             };

   196 

   197         /**

   198          * Secure ID identifying the client.

   199          */

   200         TSecureId iSid;

   201 

   202         /**

   203          * Priority of a client.

   204          */

   205         TInt iPriority;

   206         };

   207 

   208 private:

   209 

   210     /**

   211      * C++ constructor.

   212      */

   213     CHWRMHapticsReservationHandler();

   214 

   215     /**

   216      * By default Symbian 2nd phase constructor is private.

   217      *

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

   219      */

   220     void ConstructL( const TDesC& aPolicyFilename );

   221     

   222     /**

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

   224      *

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

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

   227      *         EFalse otherwise

   228      */

   229     TBool AlreadyReserved( const CHWRMHapticsService* aService ) const;

   230 

   231     /**

   232      * Notifies the callback in the given reservation data about

   233      * suspension of its reservation.

   234      *

   235      * @aData Reservation data, whose callback is notified.

   236      */

   237     void NotifySuspend( TReservationData* aData ) const;

   238 

   239     /**

   240      * Notifies the callback in the given reservation data about

   241      * resume of its reservation.

   242      *

   243      * @aData Reservation data, whose callback is notified.

   244      */

   245     void NotifyResume( TReservationData* aData ) const;

   246 

   247 private: // Data

   248     

   249     /**

   250      * Pointer to policy. Owned.

   251      */

   252     CHWRMHapticsPolicy* iPolicy;

   253     

   254     /**

   255      * Reservation data. Suspended reservations are linked via 

   256      * iSuspendedData -pointers. Suspended reservations arrange in 

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

   258      */

   259     TReservationData* iReservation;

   260 

   261     /**

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

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

   264      * default priority is used for that client.

   265      */

   266     RArray<TPriority> iPriorities;

   267     };

   268 

   269 #endif // C_HWRMHAPTICSRESERVATIONHANDLER_H 

   270             

   271 // End of File