/*

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

*

*/

#ifndef C_HWRMHAPTICSCOMMONDATA_H

#define C_HWRMHAPTICSCOMMONDATA_H

#include <e32base.h>

#include <hwrmhapticsobserver.h>

#include <hwrmlogicalactuators.h>

#include <hwrmhapticsactuatorobserver.h>

#include "hwrmhapticsclientserver.h"

/**

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

 *

 * @lib hwrmhapticspluginmanager.lib

 * @since S60 5.1

 */

class CHWRMHapticsCommonData : public CBase

    {

public:

    /**

     * Two-phased constructor.

     */

    IMPORT_C static CHWRMHapticsCommonData* NewL();

    /**

     * Destructor.

     */

    virtual ~CHWRMHapticsCommonData();

public:

    /**

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

     * a session to haptics server is created.

     *

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

     * be added.

     * Function may leave with Symbian OS error code

     */

    void AddSessionL( const CSession2* aSession );

    /**

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

     * when a session to haptics server is closed.

     *

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

     * be removed.

     */

    void RemoveSession( const CSession2* aSession );

    /**

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

     * identified using the session of the message.

     *

     * @param aStatusObserverMsg New observer to be added.

     */

    void AddStatusObserver( const RMessage2& aStatusObserverMsg );

    /**

     * Notifies the given haptics status to the observer identified

     * with the given session.

     *

     * @param aStatus Status value to be notified with.

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

     * be notified.

     */

    void NotifyStatus( MHWRMHapticsObserver::THWRMHapticsStatus aStatus,

                       const CSession2* aSession );

    /**

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

     * identified with the given session.

     *

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

     * be notified.

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

     * be notified.

     */

    void NotifyActuatorEvent( THWRMLogicalActuators aActuator,

                              const CSession2* aSession );

    /**

     * Notifies all observers except the one identified with the given

     * session using the given haptics status.

     * 

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

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

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

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

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

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

     * and that it did not receive suspended -status.

     */

    void BroadcastStatus( MHWRMHapticsObserver::THWRMHapticsStatus aStatus,

                          const CSession2* aSession );

    /**

     * Notifies all observers listening to actuator events using the 

     * given event and actuator type values.

     *

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

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

     * related to.

     */

    void BroadcastActuatorEvent( 

            MHWRMHapticsActuatorObserver::THWRMActuatorEvents aEvent,

            THWRMLogicalActuators aActuator );

    /**

     * Returns the current haptics status of the given session.

     * 

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

     * status is fetched.

     * @return Current status value of the client.

     */

    MHWRMHapticsObserver::THWRMHapticsStatus 

        CurrentStatus( const CSession2* aSession ) const;

private:

    /**

     * Internal typedef for haptics status enumeration.

     */

    typedef MHWRMHapticsObserver::THWRMHapticsStatus THapticsStatus;

    /**

     * Internal typedef for actuator event enumeration.

     */

    typedef MHWRMHapticsActuatorObserver::THWRMActuatorEvents TActuatorStatus;

private:

    /**

     * C++ default constructor.

     */

    CHWRMHapticsCommonData();

    /**

     * Symbian 2nd phase constructor.

     */

    void ConstructL();

    /**

     * Returns the index of the observer with given session.

     *

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

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

     * KErrNotFound otherwise.

     */

    TInt FindClient( const CSession2* aSession ) const;

    /**

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

     *

     * @param aActuator Logical actuator type to be found.

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

     * KErrNotFound otherwise.

     */

    TInt FindActuatorEvent( THWRMLogicalActuators aActuator ) const;

    /**

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

     * data for the actuator.

     *

     * @param aStatus Event value for the actuator.

     * @param aActuator Logical actuator type.

     */

    void StoreActuatorEvent( TActuatorStatus aStatus, 

                             THWRMLogicalActuators aActuator );

    /**

     * Implements the actual haptics status notification to the client.

     *

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

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

     */

    void NotifyStatusToClient( TInt aIndex, THapticsStatus aStatus );

    /**

     * Implements the actual actuator event notification to the client.

     *

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

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

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

     * related to (sent to client also).

     */

    void NotifyActuatorEventToClient( TInt aIndex, TActuatorStatus aStatus,

                                      THWRMLogicalActuators aActuator );

private:

    /**

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

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

     * generates a new client status data.

     */

    struct TClientStatus

        {

        /**

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

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

         * it starts observation (creation of client).

         * 

         * @param aSession Session object identifying the client session.

         * @param aStatus Initial haptics status.

         */

        TClientStatus( const CSession2* aSession, THapticsStatus aStatus )

            : iSession( aSession ), iStatus( aStatus ), 

              iStatusTypes( EHWRMHapticsSessionStatus ), 

              iNotificationRequired( ETrue )

            {

            }

        /**

         * Destructor.

         */

        ~TClientStatus()

            {

            iRequiredActuators.Close();

            }

        /**

         * Status observation message received from the client.

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

         * client has requested status notification.

         */

        RMessage2 iStatusObserver;

        /**

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

         * identify the client instance.

         */

        const CSession2* iSession;

        /**

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

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

         */

        THapticsStatus iStatus;

        /**

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

         * notified to it in general.

         */

        THWRMHapticsStatusTypes iStatusTypes;

        /**

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

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

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

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

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

         * cases, where it is needed:

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

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

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

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

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

         *    notification for the next time.

         */

        TBool iNotificationRequired;

        /**

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

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

         * iNotificationRequired, but for actuator events.

         */

        RArray<THWRMLogicalActuators> iRequiredActuators;

        };

    /**

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

     * actuator specific events.

     */

    struct TActuatorEvent

        {

        /**

         * C++ constructor.

         */

        TActuatorEvent( TActuatorStatus aStatus,

                        THWRMLogicalActuators aActuator )

            : iActuatorEvent( aStatus ), iActuator( aActuator )

            {

            }

        /**

         * Actuator event.

         */

        TActuatorStatus iActuatorEvent;

        /**

         * Logical actuator type.

         */

        THWRMLogicalActuators iActuator;

        };

private:

    /**

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

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

     * session is created).

     */

    THapticsStatus iGeneralStatus;

    /**

     * Stores last received actuator events for each actuator type.

     */

    RArray<TActuatorEvent> iActuatorEvents;

    /**

     * Array containing all observers listening to haptics status.

     * Pointers are not owned by this component.

     */

    RPointerArray<TClientStatus> iClientArray;

    };

#endif  // C_HWRMHAPTICSCOMMONDATA_H

// End of File