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 common data class declaration.

    15 *

    16 */

    17 

    18 

    19 #ifndef C_HWRMHAPTICSCOMMONDATA_H

    20 #define C_HWRMHAPTICSCOMMONDATA_H

    21 

    22 #include <e32base.h>

    23 #include <hwrmhapticsobserver.h>

    24 #include <hwrmlogicalactuators.h>

    25 #include <hwrmhapticsactuatorobserver.h>

    26 #include "hwrmhapticsclientserver.h"

    27 

    28 /**

    29  * Container for haptics data that is common for all sessions.

    30  *

    31  * @lib hwrmhapticspluginmanager.lib

    32  * @since S60 5.1

    33  */

    34 class CHWRMHapticsCommonData : public CBase

    35     {

    36 public:

    37     

    38     /**

    39      * Two-phased constructor.

    40      */

    41     IMPORT_C static CHWRMHapticsCommonData* NewL();

    42         

    43     /**

    44      * Destructor.

    45      */

    46     virtual ~CHWRMHapticsCommonData();

    47         

    48 public:

    49     

    50     /**

    51      * Adds a new session to client array. This method is used, when

    52      * a session to haptics server is created.

    53      *

    54      * @param aSession Session pointer used to identify the client to 

    55      * be added.

    56      * Function may leave with Symbian OS error code

    57      */

    58     void AddSessionL( const CSession2* aSession );

    59     

    60     /**

    61      * Removes a session from the client array. This method is used,

    62      * when a session to haptics server is closed.

    63      *

    64      * @param aSession Session pointer used to identify the client to 

    65      * be removed.

    66      */

    67     void RemoveSession( const CSession2* aSession );

    68     

    69     /**

    70      * Adds the given message as a haptics status observer for a client

    71      * identified using the session of the message.

    72      *

    73      * @param aStatusObserverMsg New observer to be added.

    74      */

    75     void AddStatusObserver( const RMessage2& aStatusObserverMsg );

    76 

    77     /**

    78      * Notifies the given haptics status to the observer identified

    79      * with the given session.

    80      *

    81      * @param aStatus Status value to be notified with.

    82      * @param aSession Session pointer used to identify the client to 

    83      * be notified.

    84      */

    85     void NotifyStatus( MHWRMHapticsObserver::THWRMHapticsStatus aStatus,

    86                        const CSession2* aSession );

    87 

    88     /**

    89      * Notifies the last event of the given actuator to the observer

    90      * identified with the given session.

    91      *

    92      * @param aActuator The type of the actuator, whose last event should

    93      * be notified.

    94      * @param aSession Session pointer used to identify the client to 

    95      * be notified.

    96      */

    97     void NotifyActuatorEvent( THWRMLogicalActuators aActuator,

    98                               const CSession2* aSession );

    99 

   100     /**

   101      * Notifies all observers except the one identified with the given

   102      * session using the given haptics status.

   103      * 

   104      * @param aStatus Haptics status value to be notified with.

   105      * @param aSession Session pointer of the client, which should not 

   106      * be notified.This can be used e.g. when a client makes an active 

   107      * reservation; In that case it is unnecessary to notify that client, 

   108      * but all the others; The client making the reservation knows that 

   109      * the reservation succeeded from the return code of the command, 

   110      * and that it did not receive suspended -status.

   111      */

   112     void BroadcastStatus( MHWRMHapticsObserver::THWRMHapticsStatus aStatus,

   113                           const CSession2* aSession );

   114 

   115     /**

   116      * Notifies all observers listening to actuator events using the 

   117      * given event and actuator type values.

   118      *

   119      * @param aEvent Actuator event value to be notified with.

   120      * @param aActuator Logical actuator type to which this event is 

   121      * related to.

   122      */

   123     void BroadcastActuatorEvent( 

   124             MHWRMHapticsActuatorObserver::THWRMActuatorEvents aEvent,

   125             THWRMLogicalActuators aActuator );

   126 

   127     /**

   128      * Returns the current haptics status of the given session.

   129      * 

   130      * @param aSession Session pointer used to identify the client, whose

   131      * status is fetched.

   132      * @return Current status value of the client.

   133      */

   134     MHWRMHapticsObserver::THWRMHapticsStatus 

   135         CurrentStatus( const CSession2* aSession ) const;

   136 

   137 private:

   138 

   139     /**

   140      * Internal typedef for haptics status enumeration.

   141      */

   142     typedef MHWRMHapticsObserver::THWRMHapticsStatus THapticsStatus;

   143 

   144     /**

   145      * Internal typedef for actuator event enumeration.

   146      */

   147     typedef MHWRMHapticsActuatorObserver::THWRMActuatorEvents TActuatorStatus;

   148 

   149 private:

   150     

   151     /**

   152      * C++ default constructor.

   153      */

   154     CHWRMHapticsCommonData();

   155 

   156     /**

   157      * Symbian 2nd phase constructor.

   158      */

   159     void ConstructL();

   160     

   161     /**

   162      * Returns the index of the observer with given session.

   163      *

   164      * @param aSession Session pointer, which identifies the client.

   165      * @return Index of the observer in the internal array, if found.

   166      * KErrNotFound otherwise.

   167      */

   168     TInt FindClient( const CSession2* aSession ) const;

   169 

   170     /**

   171      * Returns the index of the actuator event in the event array.

   172      *

   173      * @param aActuator Logical actuator type to be found.

   174      * @return Index of the observer in the internal array, if found.

   175      * KErrNotFound otherwise.

   176      */

   177     TInt FindActuatorEvent( THWRMLogicalActuators aActuator ) const;

   178 

   179     /**

   180      * Updates given actuators status, or if not found, inserts new

   181      * data for the actuator.

   182      *

   183      * @param aStatus Event value for the actuator.

   184      * @param aActuator Logical actuator type.

   185      */

   186     void StoreActuatorEvent( TActuatorStatus aStatus, 

   187                              THWRMLogicalActuators aActuator );

   188     

   189     /**

   190      * Implements the actual haptics status notification to the client.

   191      *

   192      * @param aIndex Index of the client in the internal array.

   193      * @param aStatus Haptics status value to be sent to client.

   194      */

   195     void NotifyStatusToClient( TInt aIndex, THapticsStatus aStatus );

   196 

   197     /**

   198      * Implements the actual actuator event notification to the client.

   199      *

   200      * @param aIndex Index of the client in the internal array.

   201      * @param aStatus Actuator event value to be sent to client.

   202      * @param aActuator Logical actuator type to which this event is

   203      * related to (sent to client also).

   204      */

   205     void NotifyActuatorEventToClient( TInt aIndex, TActuatorStatus aStatus,

   206                                       THWRMLogicalActuators aActuator );

   207 

   208 private:

   209 

   210     /**

   211      * Data storage for a single client's status handling. Same application

   212      * may have several haptics client instances, in which case each session

   213      * generates a new client status data.

   214      */

   215     struct TClientStatus

   216         {

   217         /**

   218          * C++ constructor. By default client observes only haptics status,

   219          * so that earlier actuator events are not sent to client, when

   220          * it starts observation (creation of client).

   221          * 

   222          * @param aSession Session object identifying the client session.

   223          * @param aStatus Initial haptics status.

   224          */

   225         TClientStatus( const CSession2* aSession, THapticsStatus aStatus )

   226             : iSession( aSession ), iStatus( aStatus ), 

   227               iStatusTypes( EHWRMHapticsSessionStatus ), 

   228               iNotificationRequired( ETrue )

   229             {

   230             }

   231         

   232         /**

   233          * Destructor.

   234          */

   235         ~TClientStatus()

   236             {

   237             iRequiredActuators.Close();

   238             }

   239         

   240         /**

   241          * Status observation message received from the client.

   242          * The handle of the message is used to check whether or not

   243          * client has requested status notification.

   244          */

   245         RMessage2 iStatusObserver;

   246 

   247         /**

   248          * Pointer to the observing client's session, which is used to 

   249          * identify the client instance.

   250          */

   251         const CSession2* iSession;

   252 

   253         /**

   254          * Current status of this client. Needs to be stored here, since

   255          * it can be queried by the client without requested notification.

   256          */

   257         THapticsStatus iStatus;

   258 

   259         /**

   260          * What kind of status types has the client requested to be 

   261          * notified to it in general.

   262          */

   263         THWRMHapticsStatusTypes iStatusTypes;

   264 

   265         /**

   266          * Whether or not a notification should be sent to the client

   267          * immediately when it requests notification. The value is true,

   268          * when the client's status has changed, but it has not been sent

   269          * to the client, since there is no registered observation message

   270          * to use for notification. Basically, this flag has two different

   271          * cases, where it is needed:

   272          * 1. Client registeres an observation message for the first time,

   273          *    in which case the current status needs to be notified to client.

   274          * 2. Status changes in between last notification and the registration

   275          *    of the next observing message. In this case this flag is set

   276          *    true --> notification is sent, when the client requests

   277          *    notification for the next time.

   278          */

   279         TBool iNotificationRequired;

   280 

   281         /**

   282          * List of actuators, which have events to notify to client, 

   283          * but have not been notified yet. Used in similar matter as

   284          * iNotificationRequired, but for actuator events.

   285          */

   286         RArray<THWRMLogicalActuators> iRequiredActuators;

   287         };

   288 

   289     /**

   290      * Actuator event data for an actuator. Used to store last 

   291      * actuator specific events.

   292      */

   293     struct TActuatorEvent

   294         {

   295         /**

   296          * C++ constructor.

   297          */

   298         TActuatorEvent( TActuatorStatus aStatus,

   299                         THWRMLogicalActuators aActuator )

   300             : iActuatorEvent( aStatus ), iActuator( aActuator )

   301             {

   302             }

   303         

   304         /**

   305          * Actuator event.

   306          */

   307         TActuatorStatus iActuatorEvent;

   308 

   309         /**

   310          * Logical actuator type.

   311          */

   312         THWRMLogicalActuators iActuator;

   313         };

   314 

   315 private:

   316     

   317     /**

   318      * Last haptics status value, which has been broadcasted. This value

   319      * is set to client data, when client's status data is created (when its

   320      * session is created).

   321      */

   322     THapticsStatus iGeneralStatus;

   323 

   324     /**

   325      * Stores last received actuator events for each actuator type.

   326      */

   327     RArray<TActuatorEvent> iActuatorEvents;

   328     

   329     /**

   330      * Array containing all observers listening to haptics status.

   331      * Pointers are not owned by this component.

   332      */

   333     RPointerArray<TClientStatus> iClientArray;

   334     };

   335 

   336 #endif  // C_HWRMHAPTICSCOMMONDATA_H

   337             

   338 // End of File