Up one Level S60 Module Reference Contents Module Index Index
Previous: Up: 6.10 Sensors Next:


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"]

Up one Level S60 Module Reference Contents Module Index Index
Previous: Up: 6.10 Sensors Next:
Release 2.0.0 final , documentation updated on 10 Feb 2010.
See About this document... for information on suggesting changes.