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.

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 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.

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

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	MessageType: SMS MMS Unknown Priority: Low Medium High	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.

Error code value	Description
`0`	Success
`1000`	Invalid service argument
`1002`	Bad argument type
`1003`	Missing argument
`1010`	Entry exists

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'])
    else:
        print "Error in callback"
    # Cancel notification request
    messaging_handle.call('CancelNotification', {'Type': u'NewMessage'})
    lock.signal()

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

# 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'})
lock.wait()