6.8.3 RegisterNotification

RegisterNotification method registers the widget to receive notifications of new incoming messages. For each new message, the method returns the header information of that message. It is available only in asynchronous mode.

The following is an example for using RegisterNotification:


sms_id = messaging_handle.call('RegisterNotification', {'Type': u'NewMessage'}, 

where, new_sms_callback is a user defined callback function.

The following table summarizes the specification of RegisterNotification:

Interface IMessaging
Description Registers for getting notification for new messages.
Response Model Asynchronous
Pre-condition Valid instance of IMessaging interface is instantiated.
Post-condition Nil

Input Parameters

Input parameter specifies the request for notification of new messages. The object must contain the NotificationType property (unicode string), and this property must contain the value NewMessage.

Table 6.170: Input parameters for RegisterNotification
Name Type Range Description
Type unicode string NewMessage Performs operation based on the specified content types.

Output Parameters

Output parameters contain the requested information. They also contain ErrorCode, and ErrorMessage if the operation fails.

Table 6.171: Output parameters for RegisterNotification
Name Type Range (MessageType: string) Description
ReturnValue map:
MessageType: string
Sender: string
Subject: string
Time: Time
Priority: string
Attachment: bool
Unread: bool
MessageId: 32 bit int


It contains the list of message header fields.

SMS does not support subject, so it returns first few characters of body text.

ErrorCode int NA Service specific error code on failure of the operation.
ErrorMessage string NA Error description in Engineering English.


The following table lists the error codes and their values:

Table 6.172: Error codes
Error code value Description
0 Success
1000 Invalid service argument
1002 Bad argument type
1003 Missing argument
1010 Entry exists

Error Messages

The following table lists the error messages and their description:

Table 6.173: Error messages
Error messages Description
Messaging:RegisterNotification:Type Type Invalid Specifies if the type of Type parameter is invalid.
Messaging:RegisterNotification:Type Value Incorrect Specifies if the value of Type parameter is incorrect.
Messaging:RegisterNotification:Type Missing Specifies if the Type parameter is missing.
Messaging:RegisterNotification:Synchronous Operation not supported Specifies if RegisterNotification is called synchronously.


The following sample code illustrates how to register for a new message notification, send a SMS and then cancel the notification request, asynchronously:

import scriptext
import e32

lock = e32.Ao_lock()
messaging_handle = scriptext.load('Service.Messaging', 'IMessaging')

def new_sms_callback(trans_id, event_id, output_params):
    if trans_id == sms_id and event_id == scriptext.EventCompleted:
        print "SMS received from" + output_params['ReturnValue']['Sender'])
        print "Error in callback"
    # Cancel notification request
    messaging_handle.call('CancelNotification', {'Type': u'NewMessage'})

# The callback 'new_sms_callback' will be called when a sms is received
sms_id = messaging_handle.call('RegisterNotification', {'Type': u'NewMessage'}, 

# Send SMS to self so that the notification callback is hit
messaging_handle.call('Send', {'MessageType': u'SMS', 'To': u'12345678', 
                               'BodyText': u'Hi self'})

See About this document... for information on suggesting changes.