1.1 --- a/epoc32/include/sensrvchannel.h Tue Nov 24 13:55:44 2009 +0000
1.2 +++ b/epoc32/include/sensrvchannel.h Tue Mar 16 16:12:26 2010 +0000
1.3 @@ -1,1 +1,472 @@
1.4 -sensrvchannel.h
1.5 +/*
1.6 +* Copyright (c) 2008 Nokia Corporation and/or its subsidiary(-ies).
1.7 +* All rights reserved.
1.8 +* This component and the accompanying materials are made available
1.9 +* under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
1.10 +* which accompanies this distribution, and is available
1.11 +* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.12 +*
1.13 +* Initial Contributors:
1.14 +* Nokia Corporation - initial contribution.
1.15 +*
1.16 +* Contributors:
1.17 +*
1.18 +* Description: Sensor channel class definition
1.19 +*
1.20 +*/
1.21 +
1.22 +
1.23 +#ifndef SENSRVCHANNEL_H
1.24 +#define SENSRVCHANNEL_H
1.25 +
1.26 +#include <e32base.h>
1.27 +#include <sensrvtypes.h>
1.28 +#include <sensrvchannelconditionset.h>
1.29 +#include <sensrvchannelinfo.h>
1.30 +
1.31 +
1.32 +class MSensrvPropertyListener;
1.33 +class MSensrvDataListener;
1.34 +class MSensrvChannelConditionListener;
1.35 +class CSensrvChannelCondition;
1.36 +class CSensrvChannelListener;
1.37 +
1.38 +
1.39 +/**
1.40 +* The CSensrvChannel class provides an API that allows clients to open, control, configure,
1.41 +* receive data and receive notifications from a sensor channel.
1.42 +*
1.43 +* When instantiating CSensrvChannel an instance of TSensrvChannelInfo returned by
1.44 +* CSensrvChannelFinder::FindChannelsL() must be used. This ensures that internal data used
1.45 +* in identifying the chosen channel is passed back to Sensor Services in its entirety
1.46 +* therefore ensuring correct operation. Not using the instance returned by
1.47 +* CSensrvChannelFinder::FindChannelsL() will result in undefined behaviour.
1.48 +*
1.49 +* On instantiation of this class a session connection to the Sensor Server is made. The Sensor
1.50 +* server is a transient server and is started, if not already running, when a session connection
1.51 +* is made. The sensor server is shutdown when a device-configured timeout period expires after
1.52 +* the last session connection has been dropped. The Sensor Server will not shutdown if there is
1.53 +* a session connection to it.
1.54 +*
1.55 +* The instance of TSensrvChannelInfo returned by CSensrvChannelFinder::FindChannelsL()
1.56 +* contains a channel Id which is only valid for the lifetime of the sensor server. If a client
1.57 +* requires that this id remains unchanged then the client must ensure that an instance of either
1.58 +* CSensrvChannelFinder or CSensrvChannel remains instantiated. This keeps a session connection with
1.59 +* the server open which prevents the sensor server from shutting down.
1.60 +*
1.61 +* After creating an instance of this class a client would typically:
1.62 +* 1. Check the configuration of the channel using GetPropertyL() or GetAllPropertuies().
1.63 +* 2. Change the configuration where necessary using SetPropertiesL()
1.64 +* 3. If SetPropertiesL() failed, because of higher priority clients of this same channel or higher
1.65 +* priority clients of impacted channels on the same sensor, listen for notifications indicating
1.66 +* when it is able to set properties using SetPropertyListenerl().
1.67 +* 4. Listen for property changes using SetPropertyListenerl(). This notifies the client of property
1.68 +* changes made by other clients of this same channel.
1.69 +* 5. Listen for data and retrieve data on the channel using StartDataListeningL() and GetData().
1.70 +* 6. Set trigger conditions for a 1 off notification when the condition is met using AddConditionL()
1.71 +* and SetConditionListeningL().
1.72 +*
1.73 +* Its possible that there may be more than 1 client using the same sensor channel on the device. Each
1.74 +* of these clients will have created their own instance of CSensrvChannel and can attempt to configure
1.75 +* the sensor using the SetPropertyL() operation. To manage any contention between clients wishing to
1.76 +* change the configuration of the sensor a concept of Client Priorities is employed. This means that a
1.77 +* device creator assigns a pre-determined priority to a client. If a client has not been assigned a
1.78 +* priority then it is assumed it has the lowest priority.
1.79 +*
1.80 +* When the SetPropertyL() operation is called the sensor server checks to see if the client has the
1.81 +* highest Client Priority of all clients using that channel or using an impacted channel on the same
1.82 +* sensor. If it has the property is set and all other clients of the channel are notified of the property
1.83 +* change. If it has not the SetPropertyL() operation fails with KErrAccessDenied. If clients have
1.84 +* the same priority then property setting is done on a first come first served basis.
1.85 +*
1.86 +* If a client is unable to set a property because of higher priority clients then the client should
1.87 +* implement the MSensrvPropertyListener::SetPropertySuccessIndicationChanged() callback so that they can
1.88 +* be notified when they are able to set properties.
1.89 +*
1.90 +* All client applications should be designed in such a way so that they are able to handle the situation
1.91 +* where they are unable to configure a channel using the SetPropertyL() operation.
1.92 +*
1.93 +* For example:
1.94 +* Should application features be disabled or should the application shutdown in such conditions?
1.95 +* Should features be disabled under certain channel configurations?
1.96 +*
1.97 +* This object is closed when deleted either by a call to operator delete or by the cleanup stack. No special
1.98 +* cleanup code is necessary to close the object before deletion.
1.99 +*
1.100 +* @see CSensrvChannelFinder
1.101 +* @lib sensrvclient.lib
1.102 +* @since S60 5.0
1.103 +*/
1.104 +
1.105 +NONSHARABLE_CLASS( CSensrvChannel ): public CBase
1.106 + {
1.107 + public:
1.108 + /**
1.109 + * Two-phased constructor.
1.110 + *
1.111 + * The Sensor Server uses aChannelInfo to identify the channel in the server that the returned object
1.112 + * represents.
1.113 + *
1.114 + * @since S60 5.0
1.115 + * @param aChannelInfo The information that determines which channel object is created. This must
1.116 + * be an object returned by CSensrvChannelFinder::FindChannelsL().
1.117 + * @return Pointer to created CSensorChannel object
1.118 + * @leave KErrNoMemory
1.119 + * @leave One of the system-wide error codes
1.120 + */
1.121 + IMPORT_C static CSensrvChannel* NewL
1.122 + ( const TSensrvChannelInfo& aChannelInfo );
1.123 +
1.124 + /**
1.125 + * Two-phased constructor.
1.126 + *
1.127 + * The Sensor Server uses aChannelInfo to identify the channel in the server that the returned object
1.128 + * represents.
1.129 + *
1.130 + * @since S60 5.0
1.131 + * @param aChannelInfo The information that determines which channel object is created. This must
1.132 + * be an object returned by CSensrvChannelFinder::FindChannelsL().
1.133 + * @return Pointer to created CSensorChannel object that is placed on the cleanup stack.
1.134 + * @leave KErrNoMemory
1.135 + * @leave One of the system-wide error codes
1.136 + */
1.137 + IMPORT_C static CSensrvChannel* NewLC
1.138 + ( const TSensrvChannelInfo& aChannelInfo );
1.139 +
1.140 + public:
1.141 + /**
1.142 + * Initializes and opens the channel. After the channel is opened, the client can set and get channel
1.143 + * properties, add channel conditions and listen for sensor data.
1.144 + *
1.145 + * @since S60 5.0
1.146 + * @leave KErrAlreadyExists if channel is already open
1.147 + * @leave One of the system-wide error codes
1.148 + */
1.149 + virtual void OpenChannelL() = 0;
1.150 +
1.151 + /**
1.152 + * Closes the channel.
1.153 + *
1.154 + * This object is closed when deleted either by a call to operator delete or by the cleanup stack. No special
1.155 + * cleanup code is necessary to close the object before deletion.
1.156 + *
1.157 + * @since S60 5.0
1.158 + * @return KErrNone if channel closing is successful, or one of the system-wide error codes
1.159 + */
1.160 + virtual TInt CloseChannel() = 0;
1.161 +
1.162 + /**
1.163 + * Retrieves a channel information object related to this channel.
1.164 + *
1.165 + * @since S60 5.0
1.166 + * @return Reference to the channel information object
1.167 + */
1.168 + virtual const TSensrvChannelInfo& GetChannelInfo() const = 0;
1.169 +
1.170 + /**
1.171 + * Starts channel data listening on the channel.
1.172 + *
1.173 + * To use this operation clients must provide an object that inherits from MSensrvDataListener.
1.174 + *
1.175 + * When new data is available to be read, the client is notified by the
1.176 + * MSensrvDataListener::DataReceived() callback. On receiving this notificaton the client should
1.177 + * retrieve the data using the GetData() operation.
1.178 + *
1.179 + * Note that if a client is listening for both data and conditions on the channel then the lower
1.180 + * desired count and buffering period provided in either start listening operation arguments will be
1.181 + * used for both listeners. When either listener is stopped neither the desired count nor the
1.182 + * buffering period shall be changed.
1.183 + *
1.184 + * For the best performance, always use the highest desired count and maximum count as the use case
1.185 + * allows. This will reduce the overhead caused by a high volume of IPC context switches. However,
1.186 + * be aware that higher counts need to reserve more memory.
1.187 + *
1.188 + * @since S60 5.0
1.189 + * @param aDataListener Data listener for the channel. Must be valid until data listening is stopped.
1.190 + * @param aDesiredCount Desired receiving buffer size defined as a count of the channel data objects.
1.191 + * The maximum value is determined by sensor server internal channel buffer size, and minimum
1.192 + * value is one. Any value outside these limits is interpreted as maximum possible value.
1.193 + * The actual count of channel data objects received may be smaller than aDesiredCount, if a
1.194 + * non-zero buffering period has been specified.
1.195 + * The actual count of channel data objects received may larger, if aMaximumCount is bigger
1.196 + * than aDesiredCount.
1.197 + * If the sensor supplies data sporadically, and the clients requires every data object then
1.198 + * aDesiredCount should be set to one to ensure that no data objects are missed.
1.199 + * @param aMaximumCount Maximum receiving buffer size defined as a count of the channel data object.
1.200 + * The Maximum value is determined by sensor server internal channel buffer size, and minimum
1.201 + * value is aDesiredCount. Any value outside these limits is interpreted as maximum possible
1.202 + * value.
1.203 + * It is recommended that whenever aDesiredCount needs to be low and sensor has relatively high
1.204 + * data rate, aMaximumCount is set to significantly higher than aDesiredCount to reduce IPC
1.205 + * context switches and data loss.
1.206 + * @param aBufferingPeriod Specifies the maximum time in milliseconds that sensor server waits before
1.207 + * notifying the client that new data is available. It is possible that no new data is will be
1.208 + * available when the client is notified.
1.209 + * Zero timeout means that only desired and maximum counts are used in getting data.
1.210 + * Using a buffering period results in lot of unnecessary IPC context switches if a sensor
1.211 + * channel supplies data sporadically. It is therefore recommended that a buffering period is
1.212 + * used only when it is absolutely vital to have data at specific intervals and using a low
1.213 + * desired count is otherwise too expensive performance-wise.
1.214 + * @leave KErrArgument if aDataListener is NULL, or if a negative argument is supplied
1.215 + * @leave KErrNotFound if the channel is not open
1.216 + * @leave KErrAlreadyExists if data listening has already started on the channel
1.217 + * @leave One of the system-wide error codes
1.218 + */
1.219 + virtual void StartDataListeningL( MSensrvDataListener* aDataListener,
1.220 + const TInt aDesiredCount,
1.221 + const TInt aMaximumCount,
1.222 + const TInt aBufferingPeriod ) = 0;
1.223 +
1.224 + /**
1.225 + * Stop channel data listening.
1.226 + *
1.227 + * @since S60 5.0
1.228 + * @return KErrNone if stopping successful or one of the system-wide error codes
1.229 + */
1.230 + virtual TInt StopDataListening() = 0;
1.231 +
1.232 + /**
1.233 + * Get data items when the client is notified by the MSensrvDataListener::DataReceived() callback
1.234 + * that new data is ready to be retrieved. The callback also indicates the number of data items
1.235 + * contained in aData.
1.236 + *
1.237 + * Example:
1.238 + *
1.239 + * How to retrieve data using TPckg
1.240 + *
1.241 + * @code
1.242 + * void DataReceived(CSensrvChannel& aChannel, TInt aCount, TInt aDataLost )
1.243 + * {
1.244 + * if(aChannel.GetChannelInfo().iChannelType == KSensrvChannelTypeIdAccelerometerXYZAxisData)
1.245 + * {
1.246 + * TSensrvAccelerometerAxisData XYZData;
1.247 + * TPckg<TSensrvAccelerometerAxisData> XYZPackage( XYZData );
1.248 + * aChannel.GetData( XYZPackage );
1.249 + * }
1.250 + * }
1.251 + * @endcode
1.252 + *
1.253 + * @since S60 5.0
1.254 + * @param aData Reference to descriptor that contains the data. Typically this is a package buffer
1.255 + * defined for data type of this channel. See channel specific data headers for details of
1.256 + * the package types and data supported by a channel.
1.257 + * @return KErrNotFound if data buffer is empty, KErrOverflow if aData is wrong size for data
1.258 + * item, or one of the system-wide error codes
1.259 + */
1.260 + virtual TInt GetData( TDes8& aData ) = 0;
1.261 +
1.262 + /**
1.263 + * Sets a property value for this channel. To manage any contention between multiple clients wishing
1.264 + * to change the configuration of the sensor a concept of Client Priorities is employed. See class
1.265 + * description for further information.
1.266 + *
1.267 + * The sensor plugin may police setting of properties by verifying that the client making the request
1.268 + * has the necessary capabilities. If the client does not then it will return with KErrAccessDenied.
1.269 + * @since S60 5.0
1.270 + * @param aProperty Identifies the property that is to be set and its new value. Only the Property Id,
1.271 + * Item Index and Property Value should be filled in. All other fields in TSensrvProperty are
1.272 + * ignored.
1.273 + * @return KErrNotFound if channel is not open or if the property does not exist, KErrAccessDenied
1.274 + * if there are other clients for this channel or impacted channel on the same sensor with a
1.275 + * higher Client Priority, KErrAccessDenied if the client does not have the required
1.276 + * capabilities or one of the system-wide error codes
1.277 + */
1.278 + virtual TInt SetProperty( const TSensrvProperty& aProperty ) = 0;
1.279 +
1.280 + /**
1.281 + * Gets a channel property value for this channel.
1.282 + *
1.283 + * @since S60 5.0
1.284 + * @param aPropertyId Id of the property that is to be retrieved
1.285 + * @param aItemIndex The Item Index of the property to be retrieved. This is mapped to a specific item
1.286 + * in channel data structure. See channel specific data headers.
1.287 + * @param aProperty Reference for a property object where property data is to be copied
1.288 + * @leave KErrNotFound if channel is not open
1.289 + * @leave KErrNotFound if property does not exist
1.290 + * @leave KErrArgument if a negative argument is supplied
1.291 + * @leave One of the system-wide error codes
1.292 + * */
1.293 + virtual void GetPropertyL( const TSensrvPropertyId aPropertyId,
1.294 + const TInt aItemIndex,
1.295 + TSensrvProperty& aProperty ) = 0;
1.296 +
1.297 + /**
1.298 + * Get a channel property value for this channel
1.299 + *
1.300 + * @since S60 5.0
1.301 + * @param aPropertyId Id of the property that is to be retrieved
1.302 + * @param aItemIndex Item Index of the property to be retrieved. This is mapped to a specific item
1.303 + * in channel data structure. See channel specific data headers.
1.304 + * @param aArrayIndex Array index of the property to be retrieved when the property is part of a
1.305 + * property array.
1.306 + * @param aProperty Reference for a property object where property data is to be copied
1.307 + * @leave KErrNotFound if channel is not open
1.308 + * @leave KErrNotFound if property does not exist
1.309 + * @leave KErrArgument if a negative argument is supplied
1.310 + * @leave One of the system-wide error codes
1.311 + */
1.312 + virtual void GetPropertyL( const TSensrvPropertyId aPropertyId,
1.313 + const TInt aItemIndex,
1.314 + const TInt aArrayIndex,
1.315 + TSensrvProperty& aProperty ) = 0;
1.316 +
1.317 + /**
1.318 + * Get all properties for this channel
1.319 + *
1.320 + * @since S60 5.0
1.321 + * @param aChannelPropertyList Reference for a property list where all property data is to be
1.322 + * copied. Any existing data in the list will be lost.
1.323 + * @leave KErrNotFound if channel is not open
1.324 + * @leave One of the system-wide error codes
1.325 + */
1.326 + virtual void GetAllPropertiesL
1.327 + ( RSensrvPropertyList& aChannelPropertyList ) = 0;
1.328 +
1.329 + /**
1.330 + * Get all channel properties having the supplied Property Id. This is used when the property
1.331 + * is an array property.
1.332 + *
1.333 + * @since S60 5.0
1.334 + * @param aPropertyId Id of the property to be retrieved
1.335 + * @param aChannelPropertyList Reference for a property list where all property data is to be
1.336 + * copied. Any existing data in the list will be lost.
1.337 + * @leave KErrNotFound if channel is not open
1.338 + * @leave KErrNotFound if property does not exist
1.339 + * @leave One of the system-wide error codes
1.340 + */
1.341 + virtual void GetAllPropertiesL
1.342 + ( const TSensrvPropertyId aPropertyId,
1.343 + RSensrvPropertyList& aChannelPropertyList ) = 0;
1.344 +
1.345 + /**
1.346 + * Start property listening on this channel.
1.347 + *
1.348 + * To use this operation clients must provide an object that inherits from MSensrvPropertyListener.
1.349 + *
1.350 + * The client can use the property listener to get notifications when properties are changed and
1.351 + * to get a notification when the client is able/unable to set properties because of higher priority
1.352 + * clients have opened/closed the same sensor channel.
1.353 + *
1.354 + * If the client itself changes a property value, no notification is received for that property by
1.355 + * the client. If another client changes a property on this channel or another channel that impacts
1.356 + * this channel a notification will be received by the client.
1.357 + *
1.358 + * Some sensors support a number of channels with each channel having some common properties.
1.359 + * Therefore changing a common property may result in notifications on a number of other channels
1.360 + * supported by the sensor.
1.361 + *
1.362 + * @since S60 5.0
1.363 + * @param aChannelPropertyListener Pointer to channel property listener callback instance. The
1.364 + * channel property listener must be valid until the CSensrvChannel object is destroyed or
1.365 + * listening has been stopped. Listening can be stopped using a NULL parameter.
1.366 + * @leave KErrAlreadyExists if channel property listener has already been set
1.367 + * @leave KErrNotFound if channel is not open
1.368 + * @leave One of the system-wide error codes
1.369 + */
1.370 + virtual void SetPropertyListenerL
1.371 + ( MSensrvPropertyListener* aChannelPropertyListener ) = 0;
1.372 +
1.373 + /**
1.374 + * Add a channel ConditionSet to the channel.
1.375 + *
1.376 + * Channel ConditionSet's are used for channel condition listening and at least 1 ConditionSet must
1.377 + * be added before listening can begin.
1.378 + *
1.379 + * When the conditions defined by the ConditionSet is met the client will be notified by the
1.380 + * MSensrvChannelConditionListener::ConditionMet() callback and listening for this ConditionSet will
1.381 + * cease. If a client wishes to listen for this ConditionSet again it must be added again.
1.382 + *
1.383 + * The client continues to own the ConditionSet object after a call to this function and must ensure
1.384 + * that it is destroyed when no longer required.
1.385 + *
1.386 + * The client must ensure that the ConditionSet object is valid until it is no longer needed by the
1.387 + * Sensor Server. This is either after the condition set has been removed by the client using
1.388 + * RemoveConditionL() or the client has been notified that the condition has been met.
1.389 + *
1.390 + * @since S60 5.0
1.391 + * @param aChannelConditionSet The channel condition set to be added.
1.392 + * @leave KErrNotFound if channel is not open
1.393 + * @leave KErrNotSupported if a channel does not support conditions.
1.394 + * @leave One of the system-wide error codes
1.395 + * @see CSensrvChannel::StartConditionListeningL()
1.396 + */
1.397 + virtual void AddConditionL( CSensrvChannelConditionSet& aChannelConditionSet ) = 0;
1.398 +
1.399 + /**
1.400 + * Remove a channel ConditionSet from the channel.
1.401 + *
1.402 + * The same reference used to to add the Condition Set in AddConditionL(), must also be used to
1.403 + * remove it.
1.404 + *
1.405 + * The removed channel ConditionSet is no longer used for channel condition listening.
1.406 + *
1.407 + * The client continues to own the ConditionSet object after a call to this function and must ensure
1.408 + * that it is destroyed when no longer required.
1.409 + *
1.410 + * @since S60 5.0
1.411 + * @param aChannelConditionSet The channel condition set to be removed.
1.412 + * @leave KErrNotFound if channel is not open
1.413 + * @leave One of the system-wide error codes
1.414 + */
1.415 + virtual void RemoveConditionL
1.416 + ( CSensrvChannelConditionSet& aChannelConditionSet ) = 0;
1.417 +
1.418 + /**
1.419 + * Start channel condition listening.
1.420 + *
1.421 + * To use this operation clients must provide an object that inherits from MSensrvChannelConditionListener.
1.422 + *
1.423 + * If the conditions of an added ConditionSet is met the MSensrvChannelConditionListener::ConditionMet()
1.424 + * callback function will be called and listening for this ConditionSet will cease. If a client wishes
1.425 + * to listen for the same ConditionSet again it must be added again.
1.426 + *
1.427 + * Note that if a client is listening for both data and conditions on the channel then the lower
1.428 + * desired count and buffering period provided in either start listening operation arguments will be
1.429 + * used for both listeners. When either listener is stopped neither the desired count nor the
1.430 + * buffering period shall be changed.
1.431 + *
1.432 + * @since S60 5.0
1.433 + * @param aChannelConditionListener Condition listener for the channel. Must be valid until data
1.434 + * listening is stopped.
1.435 + * @param aObjectCount Listening buffer size defined as a count of the channel data objects. When the
1.436 + * desired object count is reached each ConditionSet is evaluated in turn. The maximum value is
1.437 + * determined by sensor server internal channel buffer size, and minimum value is one. Any value
1.438 + * outside these limits is interpreted as maximum possible value.
1.439 + * @param aBufferingPeriod Specifies the maximum time in milliseconds that sensor server waits before
1.440 + * evaluating new data.
1.441 + * Zero timeout means that the sensor server only evaluates new data when the object count has been
1.442 + * reached.
1.443 + * @leave KErrArgument if aChannelConditionListener is NULL, or if a negative argument is supplied
1.444 + * @leave KErrNotFound if the channel is not open
1.445 + * @leave KErrAlreadyExists if condition listening has already started on the channel
1.446 + * @leave One of the system-wide error codes
1.447 + */
1.448 + virtual void StartConditionListeningL
1.449 + ( MSensrvChannelConditionListener* aChannelConditionListener,
1.450 + const TInt aObjectCount,
1.451 + const TInt aBufferingPeriod ) = 0;
1.452 +
1.453 + /**
1.454 + * Stop channel condition listening.
1.455 + *
1.456 + * All remaining unmet ConditionSet's are removed and channel condition listening is stopped.
1.457 + *
1.458 + * If the same ConditionSet's need to be used when condition listening has been restarted then they must be
1.459 + * re-added.
1.460 + *
1.461 + * @since S60 5.0
1.462 + * @return KErrNone if condition listening is successfully stopped or one of the system-wide error codes
1.463 + */
1.464 + virtual TInt StopConditionListening() = 0;
1.465 +
1.466 + public:
1.467 + /**
1.468 + * Default constructor.
1.469 + */
1.470 + CSensrvChannel();
1.471 + };
1.472 +
1.473 +
1.474 +#endif //SENSRVCHANNEL_H
1.475 +
1.476 +// End of File