6.10.2 RegisterForNotification
RegisterForNotification
is used to register for notification with a sensor channel to receive channel data or channel property changes. This is associated with the transaction ID of an asynchronous request.
These notifications are continuous in nature and are stopped by invoking the Cancel
command on the retrieved transaction ID.
The following is an example for using RegisterForNotification
:
Asynchronous
sensor_handle.call('RegisterForNotification', {'ListeningType': u'ChannelData', 'ChannelInfoMap': {'ChannelId': result['ChannelId'], 'ContextType': result['ContextType'], 'Quantity': result['Quantity'], 'ChannelType': result['ChannelType'], 'Location': result['Location'], 'VendorId': result['VendorId'], 'DataItemSize': result['DataItemSize'], 'ChannelDataTypeId': result['ChannelDataTypeId']}}, callback=sensor_callback)
where, sensor_callback
is the user defined callback function.
The following table summarizes the specification of RegisterForNotification
:
Interface |
ISensor |
Description |
Registers for notification with a sensor channel to receive channel data. |
Response Model |
Asynchronous |
Pre-condition |
ISensor interface is loaded. |
Post-condition |
Client application receives an array of channel information to open channels. |
Input Parameters
Input parameter is a set of arguments that specifies the Listening
Type and the ChannelInfoMap
.
Table 6.197:
Input parameters for RegisterForNotification
Name |
Type |
Range |
Description |
ListeningType |
unicode string |
Range for ListeningType
ChannelData : Data listening |
Determines the type of notification that needs to be registered for. |
ChannelInfoMap |
map as mentioned in FindSensorChannel . Refer ChannelInfoMap 6.194 |
NA |
The map is obtained by invoking FindSensorChannel . |
|
Output Parameters
Output contains ReturnValue
. It also contains ErrorCode
and an ErrorMessage
if the operation fails. ReturnValue
is an object, which contains output parameter details depending on the listening type and channel selected.
Table 6.198:
Output parameters for RegisterForNotification
Name |
Type |
Range |
Description |
ErrorCode |
int |
NA |
Contains the SAPI specific error code when the operation fails. |
ErrorMessage |
string |
NA |
Error Description in Engineering English. |
ReturnValue |
The output consists of one of the following maps depending on the listening type and channel selected:
For listening type - ChannelData and channel information corresponding to AccelerometerAxis :
Type: Name
string: DataType
Time: TimeStamp
32 bit int: XAxisData
32 bit int: YAxisData
32 bit int: ZAxisData
For listening type - ChannelData and channel information corresponding to AccelerometerDoubleTapping :
Type: Name
string: DataType
Time: TimeStamp
32 bit int: DeviceDirection
For listening type - ChannelData and channel information corresponding to Orientation :
Type: Name
string: DataType
Time: TimeStamp
string: DeviceOrientation
For listening type - ChannelData and channel info corresponding to Rotation :
Type: Name
string: DataType
Time: TimeStamp
32 bit int: XRotation
32 bit int: YRotation
32 bit int: ZRotation |
DataType for AccelerometerAxis is AxisData
DataType for AccelerometerDoubleTapping is DoubleTappingData
DataType for Orientation is OrientationData
Range for DeviceOrientation :
Undefined
DisplayUp
DisplayDown
DisplayLeftUp
DisplayRightUp
DisplayUpwards
DisplayDownwards
DataType for Rotation is RotationData |
A map is returned in case notification is received. |
|
Errors
The following table lists the error codes and their values:
Table 6.199:
Error codes
Error code value |
Description |
0 |
Success |
1000 |
Invalid service argument |
1002 |
Bad argument type |
1003 |
Missing argument |
1005 |
Service in use |
|
Error Messages
The following table lists the error messages and their description:
Table 6.200:
Error messages
Error messages |
Description |
Sensors:RegisterForNotification:Listening type missing |
Indicates that the listening type for receiving notification is missing. |
Sensors:RegisterForNotification:Listening type is invalid |
Indicates that the datatype of Listening type is invalid. |
Sensors:RegisterForNotification:ChannelInfoMap missing |
Indicates that the channel information map is not provided as input parameter. |
Sensors:RegisterForNotification:Incomplete input param list |
Indicates that the input parameter list is incomplete. |
Sensors:RegisterForNotification:Listening type is out of allowed range |
Indicates that the Listening type falls outside the allowed range of listening types. |
Sensors:RegisterForNotification:Callback missing |
Indicates that the callback function is missing. |
Sensors:RegisterForNotification:Notification is already registered on this channel |
Indicates that the notification is already registered from the same user on the same channel. |
|
Example
The following sample code illustrates how to receive notification for channel data, on registering:
import scriptext
import e32
# Using e32.Ao_lock() to make main function wait till callback is hit
lock = e32.Ao_lock()
# Callback function will be called when the requested service is complete
def register_operation(trans_id, event_id, input_params):
if trans_id != scriptext.EventCompleted:
print "DataType: ", input_params["ReturnValue"]["DataType"]
print "TimeStamp: ", input_params["ReturnValue"]["TimeStamp"]
print "X-Axis Rotation: ", input_params["ReturnValue"]["XRotation"]
print "Y-Axis Rotation: ", input_params["ReturnValue"]["YRotation"]
print "Z-Axis Rotation: ", input_params["ReturnValue"]["ZRotation"]
Release 1.9.6 final , documentation updated on 30 Jun 2009.
See About this document... for information on suggesting changes.