6.11.3 GetNotification
GetNotification
method registers a callback function to receive notifications of system data. It takes a set of input parameters that specifies entity and key of System Attribute.
It is available in only asynchronous mode.
The following is an example for using GetNotification
:
Asynchronous
event_id = sysinfo_handle.call("GetNotification", {"Entity": u"Battery", "Key": u"ChargingStatus"}, callback=sysinfo_callback)
where, sysinfo_callback
is user defined function.
The following table summarizes the specification of GetNotification
:
Interface |
ISysinfo |
Description |
Registers a callback function for listening to notifications. |
Response Model |
Asynchronous |
Pre-condition |
ISysInfo Interface is loaded. |
Post-condition |
Returns the generic parameter system data on success. |
Input Parameters
Input parameter specifies the Entity and Key of system attribute, and system data.
Table 6.213:
Input parameters for GetNotification
Name |
Type |
Range |
Description |
Entity |
unicode string |
For complete list of supported Entities, refer Key Values 6.11.4 section. |
Entity of system attribute. For example, Battery
Network and so on. |
Key |
unicode string |
For complete list of supported Keys, refer Key Values 6.11.4 section. |
Key of system attribute. For example, BatteryStrenth
CurrentNetwork and so on. |
[SystemData] |
map |
Status information
Status: int
DriveInfo
Drive: unicode string
CriticalSpace: int |
This is an optional parameter from API definition point of view. For some system attributes, you need to specify input.
This map must contain one of the input data specifiers defined in System Data.
For more information on input specifier refer the section Key Values 6.11.4.
Here are some system attributes for which status information is used as input specifier.
DriveNumber and critical space to be specified for drive critical memory notifications.
For example,
Battery- BatteryStrength (Threshold Strength value).
Network- Signal (Threshold Signal value). |
|
Output Parameters
Output parameter returns an object that contains the requested information. It also contains ErrorCode
and an ErrorMessage
, if the operation fails.
Table 6.214:
Output parameters for GetNotification
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 |
map(System Data)
Entity: string
Key: string |
For complete range of keys for the particular map, refer to System Data in Key Value section. |
Output map always contains Entity and Key. Rest of the elements in the map depends on requested system attribute (Entity-Key). It will be one of the data specifiers defined in System Data.
On requesting drive information using system attribute (for example: Memory , DriveInfo ), ReturnValue map will contain Keys defined in DriveInfo Map. |
|
Errors
The following table lists the error codes and their values:
Table 6.215:
Error codes
Error code value |
Description |
1002 |
Bad argument type |
1003 |
Missing argument |
1006 |
Service not ready |
1010 |
Entry exists |
1012 |
Item not found |
|
Error Messages
The following table lists the error messages and their description:
Table 6.216:
Error messages
Error messages |
Description |
SysInfo:GetNotification:Insufficient Arguments to process |
At least two input arguments are expected to process GetNotification service request. |
SysInfo:GetNotification:Entity:Input Parameter Missing |
Indicates mandatory parameter Entity is missing in the service request. |
SysInfo:GetNotification:Key:Input Parameter Missing |
Indicates mandatory parameter Key is missing in the service request. |
SysInfo:GetNotification:Incorrect SystemData Type, SystemData Must be a Map |
Indicates that either the optional parameter SystemData specified is not a map or content of the map is inappropriate to process request. |
SysInfo:GetNotification:Sync Version Not Supported |
This message is given when GetNotification is requested without specifying callback or CmdOptions set to Synchronous request type. |
|
Example
import scriptext
import e32
lock = e32.Ao_lock()
messaging_handle = scriptext.load('Service.SysInfo', 'ISysInfo')
def sysinfo_callback(trans_id, event_id, input_params):
if event_id != scriptext.EventCompleted:
# Check the event status
print "Error in retrieving required info"
print "Error code is: " + str(input_params["ReturnValue"]["ErrorCode"])
if "ErrorMessage" in input_params["ReturnValue"]:
print "Error message is: " + input_params["ReturnValue"]["ErrorMessage"]
else:
print "Current Battery charging value: " + str(input_params["ReturnValue"]["Status"])
lock.signal()
# Make a request to get notification
event_id = sysinfo_handle.call("GetNotification", {"Entity": u"Battery", "Key": u"ChargingStatus"}, callback=sysinfo_callback)
lock.wait()
Release 1.9.6 final , documentation updated on 30 Jun 2009.
See About this document... for information on suggesting changes.