diff -r 000000000000 -r 4e1aa6a622a0 sensorservices/sensorserver/inc/client/sensrvchannelimpl.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/sensorservices/sensorserver/inc/client/sensrvchannelimpl.h Tue Feb 02 00:53:00 2010 +0200 @@ -0,0 +1,529 @@ +/* +* 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 +#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 iConditionSetList; + + /** + * Iterator for condition list + */ + TSglQueIter iConditionSetIter; + + /** + * Condition set id counter + */ + TInt iConditionSetIdCounter; + + }; + + +#endif //SENSRVCHANNELIMPL_H \ No newline at end of file