/*

* Copyright (c) 2006-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:  Provides methods to open and control a sensor channel.

*

*/

#ifndef SENSRVCHANNELIMPL_H

#define SENSRVCHANNELIMPL_H

#include <e32base.h>

#include "sensrvchannel.h"

#include "sensrvtypes.h"

#include "sensrvclient.h"

#include "sensrvdatahandlerobserver.h"

#include "sensrvpropertyhandlerobserver.h"

#include "sensrvconditionhandlerobserver.h"

class MSensrvPropertyListener;

class CSensrvPropertyHandler;

class MSensrvDataListener;

class CSensrvDataHandler;

class MSensrvConditionListener;

class CSensrvConditionHandler;

class CSensrvChannelConditionSetImpl;

/**

 *  Realizes a sensor channel. Provides methods to open and control a sensor channel.

 *  Class provides operations to initiates a data transmittion,

 *  set channel conditions and property providers.

 *

 *  @lib SensrvClient.lib

 *  @since S60 5.0

 */

NONSHARABLE_CLASS(CSensrvChannelImpl) : public CSensrvChannel,

                                        public MSensrvDataHandlerObserver,

                                        public MSensrvPropertyHandlerObserver,

                                        public MSensrvConditionHandlerObserver

    {

    friend class CSensrvChannel;

    enum THandlerId

        {

        EDataHandler,

        EPropertyHandler,

        EConditionHandler,

        EStartDataListening,

        EStartConditionListening

        };

    public:

        /**

        * Destructor.

        */

        virtual ~CSensrvChannelImpl();

    public:

        /**

        * Open and initiates the channel. After a channel is opened a client can 

        * set and get channel properties, add channel conditions and the listen 

        * sensor data from a sensor.

        *

        * @since S60 5.0

        */

        virtual void OpenChannelL();

        /**

        * Closes the channel.

        *

        * @since S60 5.0

        * @return TInt KErrNone if channel closing successful

        */

        virtual TInt CloseChannel();

        /**

        * Returns a channel info object related to this channel.

        *

        * @since S60 5.0

        * @return TSensrvChannelInfo& Reference to channel info object

        */

        virtual const TSensrvChannelInfo& GetChannelInfo() const;

        /**

        * Start the channel data listening. Channel data is received into the

        * receiving buffer and it can be read using the GetData-function. When new

        * data is available in the receiving buffer, a notification is delivered

        * via the data listener callback interface (MSensrvDataListener).

        *

        * Note that if channel is listening for both data and conditions, the

        * lower desired count and buffering period defined in start calls will be

        * used for both.

        *

        * For best performance, always use as high desired and maximum counts as 

        * the use case allows to reduce overhead caused by IPC calls.

        * However, keep in mind that higher counts reserve more memory.

        *

        * @since S60 5.0

        * @param[in] aDataListener Data listener for the channel. Must be valid

        *        until data listening is stopped.

        * @param[in] aDesiredCount Desired receiving buffer size defined in a 

        *        count of the channel data objects. Maximum value is determined 

        *        by sensor server internal channel buffer size, and minimum value 

        *        is one. Any value outside these limits is interpreted as maximum 

        *        possible value. Actual count of channel data objects received 

        *        each time may be smaller than aDesiredCount, if a non-zero 

        *        buffering period has been specified, or larger, if aMaximumCount 

        *        is bigger than aDesiredCount. If sensor supplies data sporadically, 

        *        and every data object is interesting, aDesiredCount should be set 

        *        to one to ensure that no data objects are missed.

        * @param [in] aMaximumCount Maximum receiving buffer size defined in a 

        *        count of the channel data object. Maximum value is determined by

        *        sensor server internal channel buffer size, and minimum value is 

        *        aDesiredCount. Any value outside these limits is interpreted as 

        *        maximum possible value. It is recommended that whenever 

        *        aDesiredCount needs to be low and sensor has relatively high 

        *        possible data rate, aMaximumCount is set to significantly higher 

        *        than aDesiredCount to reduce IPC traffic and data loss.

        * @param[in] aBufferingPeriod Specifies the maximum time in milliseconds

        *        that sensor server waits between updating new data into the

        *        receiving buffer. It is possible that no new data is available

        *        when notification comes. Zero timeout means that only desired 

        *        and maximum counts are used in getting data.

        *        Using buffering period results in lot of unnecessary IPC traffic,

        *        if sensor only supplies data sporadically, so it is recommended 

        *        to be used only when it is absolutely vital to have data at 

        *        specific intervals and using low desired count is too expensive 

        *        performance-wise.

        */

        virtual void StartDataListeningL( MSensrvDataListener* aDataListener,

                                          const TInt aDesiredCount,

                                          const TInt aMaximumCount,

                                          const TInt aBufferingPeriod );

        /**

        * Stop channel data listening.

        *

        * @since S60 5.0

        * @return TInt KErrNone if stopping successful

        */

        virtual TInt StopDataListening();

        /**

        * Get next data item. A client can use this function to get a received 

        * data from the data buffer when a data listening is on.

        *

        * @since S60 5.0

        * @param[out] aData Reference to descriptor where data should be copied 

        *              to. Typically this is a package buffer defined for data 

        *              type of this channel.

        * @return TInt KErrNotFound if data buffer is empty.

        *              KErrBadDescriptor if aData is wrong size for data item.

        */

        virtual TInt GetData( TDes8& aData );

        /**

        * Set a property. Set property to the sensor. If the property is not 

        * valid error code will be returned. Property ID and item index related 

        * to the operation are added to the property parameter itself.

        *

        * @since S60 5.0        

        * @param[in] aProperty New property to be set. Contains also information 

        *         about property ID and itemindex.

        * @return TInt KErrNotFound Property ID is not found

        *              KErrAccessDenied A client has no right or priority to 

        *                      change the property value.

        */

        virtual TInt SetProperty(  const TSensrvProperty& aProperty);

        /**

        * Get the channel property value.

        *

        * @since S60 5.0        

        * @param[in] aPropertyId Id of the property to be get

        * @param[in] aItemIndex Item index of the property. Mapped to 

        *         a specific item in channel data structure.

        * @param[out] aProperty Reference to property value to be get.

        */

        virtual void GetPropertyL( const TSensrvPropertyId aPropertyId,

                                   const TInt aItemIndex,

                                   TSensrvProperty& aProperty );

        /**

        * Get a channel property value. 

        *

        * @since S60 5.0

        * @param[in] aPropertyId Id of the property to be get

        * @param[in] aItemIndex Item index of the property. Mapped to a specific 

        *            item in channel data structure.

        * @param[in] aArrayIndex Array index of the property. If property is an array

        *            parameter references to array index.

        * @param[out] aProperty Reference to a property object where property data 

        *             is copied to.

        * @leave KErrNotFound - No open channel with that id for this client found,

        *                       or property does not exist.

        */  

        virtual void GetPropertyL( const TSensrvPropertyId aPropertyId,

                                   const TInt aItemIndex,

                                   const TInt aArrayIndex,

                                   TSensrvProperty& aProperty );

        /**

        * Get all channel properties.

        *

        * @since S60 5.0        

        * @param[out] aChannelPropertyList List of the properties the channel have.

        */

        virtual void GetAllPropertiesL( RSensrvPropertyList& aChannelPropertyList );

        /**

        * Get all channel properties. 

        *

        * @since S60 5.0

        * @param[in] aPropertyId Id of the property to be get

        * @param[out] aChannelPropertyList List of all properties the channel has. 

        *    Any old data in list will be lost.

        * @leave KErrNotFound - No open channel with that id for this client found

        *                       or property does not exist.

        */  

        virtual void GetAllPropertiesL(

                     const TSensrvPropertyId aPropertyId, 

                     RSensrvPropertyList& aChannelPropertyList );

        /**

        * Set property listener. A client can use a property listener to get 

        * notification about a changed property. If a client itself changes 

        * a property value notification is not received. Note that changing 

        * a property value may effect to other properties on the channel and 

        * notification about these is occured.

        *

        * @since S60 5.0        

        * @param[in] aChannelPropertyListener Pointer to channel property listener

        */

        virtual void SetPropertyListenerL( 

                     MSensrvPropertyListener* aChannelPropertyListener);

        /**

        * Add a channel condition set for a channel. Added channel condition 

        * will be used in the channel condition listening. A client has ownership 

        * to added object and CSensrvChannel will not destroy 

        * CSensrvChannelConditionSet-object in any case. Client has to ensure 

        * the CSensrvChannelConditionSet-object is valid until the condition

        * set is removed from the channel or the channel is destroyed.

        *

        *

        * @since S60 5.0

        * @param[in] aChannelConditionSet Channel condition to be added

        */

        virtual void AddConditionL( 

                     CSensrvChannelConditionSet& aChannelConditionSet );

        /**

        * Remove channel condition set. Removed channel condition set is not 

        * used anymore in the channel condition listening. A client have to 

        * take care of destroying channel condition set object.

        *

        * @since S60 5.0

        * @param[in] aChannelConditionSet Channel condition set to be removed

        */

        virtual void RemoveConditionL( 

                     CSensrvChannelConditionSet& aChannelConditionSet );

        /**

        * Set and start channel condition listener. If any one of the channel 

        * conditions is met callback function in listener object is called.

        *

        * Note that if channel is listening for both data and conditions, 

        * the lower object count and buffering period defined in start calls 

        * will be used for both.

        *

        * @since S60 5.0

        * @param[in] aChannelConditionListener Channel condition listener to be set.

        *    The listener must be valid until condition listening is stopped.

        * @param[in] aObjectCount Listening buffer size defined in a count of the 

        *        channel objects. Each channel condition is evaluated at once 

        *        for a block which size is an aObjectCount. Maximum count is 

        *        determined by sensor server internal channel buffer size, and 

        *        minimum count is one. Any count outside these limits is interpreted

        *        as maximum possible count.

        * @param[in] aBufferingPeriod Specifies the maximum time in milliseconds 

        *        that sensor server waits between getting new data to evaluate 

        *        conditions against. Zero timeout means that only aObjectCount 

        *        is used in getting data.

        */

        virtual void StartConditionListeningL( 

                     MSensrvChannelConditionListener* aChannelConditionListener,

                     const TInt aObjectCount,

                     const TInt aBufferingPeriod );

        /**

        * Stop condition listening.

        *

        * @since S60 5.0

        * @return TInt KErrNone if stopping successful

        */

        virtual TInt StopConditionListening();

    public: // From MSensrvDataHandlerObserver

        /**

        * Indicates data is available in the receiving buffer

        *

        * @since S60 5.0

        * @param aCount Data count in receiving buffer

        * @param aDataLost Data lost count

        */

        void DataReceived( TInt aCount, TInt aDataLost );

        /**

        * Data listening failed.

        * If error was fatal, channel has also been closed and sensor server 

        * session terminated.

        * If error was minor, some data has potentially been lost.

        *

        * @since S60 5.0        

        * @param aError Error code.

        */

        void DataError( TSensrvErrorSeverity aError );

        /**

        * Reopen channel.

        * Property listening and condition listening need restarting too

        *

        * @since S60 5.0        

        * @param aMaxBufferCount New maximum client buffer count

        */

        void ReopenChannelForDataListeningL( TInt& aMaxBufferCount );

    public: //From MSensrvPropertyHandlerObserver

        /**

        * Notification about the changed value of a property.

        *

        * @since S60 5.0

        * @param[in] aChangedProperty Changed property.

        */

        void PropertyChanged( const TSensrvProperty& aChangedProperty );

        /**

        * Property listening failed.

        * If error was fatal, channel has also been closed and sensor server 

        * session terminated.

        * If error was minor, some property changes have potentially been missed.

        *

        * @since S60 5.0

        * @param[in] aError Error code.

        */

        void PropertyError( TSensrvErrorSeverity aError );

        /**

        * Reopen channel.

        * Data listening and condition listening need restarting

        *

        * @since S60 5.0        

        * @param aMaxBufferCount New maximum client buffer count

        */

        void ReopenChannelForPropertyListeningL();

        /**

        * Notification about change in property setting avaibility.

        *

        * @since S60 5.0

        * @param[in] aIndication holds the new indicator value.

        */

        void SetPropertySuccessIndicationChanged( TSetPropertySuccessIndicator aIndication );

    public: //From MSensrvConditionHandlerObserver

        /**

        * Notification about the condition met.

        *

        * @since S60 5.0

        * @param[in] aSetId Condition set id that was met.

        * @param[in] aValue The data value that caused meeting of this condition.

        */

        void ConditionMet( TInt aSetId, 

                           TDesC8& aValue );

        /**

        * Condition listening failed.

        * If error was fatal, channel has also been closed and sensor server 

        * session terminated.

        * If error was minor, some condition meetings have potentially been missed.

        *

        * @since S60 5.0

        * @param[in] aError Error code.

        */

        void ConditionError( TSensrvErrorSeverity aError );

        /**

        * Reopen channel.

        * Data listening and property listening need restarting

        *

        * @since S60 5.0        

        */

        void ReopenChannelForConditionListeningL();

    private:

        /**

        * C++ constructor

        *

        * @since S60 5.0

        */

        CSensrvChannelImpl( const TSensrvChannelInfo& aChannelInfo );

        /**

        * 2nd phase of construction

        *

        * @since S60 5.0

        */

        void ConstructL();

        /**

        * Open Channel.

        * Must reset listeners here instead of close channel 

        * because listener pointer is needed after fatal error triggered

        * closing of channel to notify this fatal error to listener.

        *

        * @param aResetListeners ETrue set listeners to NULL,

        *        and remove all conditions.

        */

        void DoOpenChannelL( TBool aResetListeners );

        /**

        * Reopen channel for listening when prompted by a handler

        *

        * @param aInitiator The listener than prompted this

        */

        void ReopenChannelForListeningL( THandlerId aInitiator );

    private: // Data

        /**

        * Channel Id

        */

        TSensrvChannelInfo iChannelInfo;

        /**

        * Max buffer count

        */

        TInt iMaxBufferCount;

        /**

        * Data listening parameters

        */

        TSensrvStartListeningParameters iDataListeningParameters;

        /**

        * Sensor server client

        */

        RSensrvClient iSensrvClient;

        /**

        * Data handler

        * Own        

        */

        CSensrvDataHandler* iDataHandler;

        /**

         * Data listener

         * Not own        

         */

        MSensrvDataListener* iDataListener;

        /**

         * channel open flag

         */ 

        TBool iChannelOpen;

        /**

         * Property handler

         * Own         

         */

        CSensrvPropertyHandler* iChannelPropertyHandler;

        /**

         * Property listener

         * Not own         

         */

        MSensrvPropertyListener* iChannelPropertyListener;

        /**

        * Condition handler

        * Own         

        */

        CSensrvConditionHandler* iConditionHandler;

        /**

        * Condition listener

        * Not own         

        */

        MSensrvChannelConditionListener* iConditionListener;

        /**

        * List of added condition sets

        * Sets in list are not owned.

        */

        TSglQue<CSensrvChannelConditionSetImpl> iConditionSetList;

        /**

        * Iterator for condition list

        */        

        TSglQueIter<CSensrvChannelConditionSetImpl> iConditionSetIter;

        /**

        * Condition set id counter

        */

        TInt iConditionSetIdCounter;

    };

#endif //SENSRVCHANNELIMPL_H