4.3 `messaging` -- A messaging services package

Availability: S60.

The messaging module offers APIs to messaging services. Currently, the messaging module has functions:

sms_send( number, msg, [encoding='7bit', callback=None, name=""])

Sends an SMS message with body text msg^4.4 (Unicode)to telephone number number (string).

The optional parameter encoding is used to define encoding in the message. The parameter values can be '7bit', '8bit' or 'UCS2'.

The optional parameter callback is invoked with the current status of the send operation as parameter. The possible states are data items in the module messaging. Invoking another send while a previous send request is ongoing will result in RuntimeError being raised.

If the callback is not given, the sms_send function will block until the message in the queue is either deleted or the sending has failed^4.5.

The optional parameter name will be shown in the sent item message entry as recipient's name after successfully sending message to number. If this parameter is not specified, then the recipient's phone number will be shown in the sent item message entry^4.6.

mms_send( number, msg, [attachment=None])

Sends an MMS message with body text msg (Unicode) to telephone number number (string). The optional parameter attachment is full path to e.g. image file attached to the message.

The following data items for SMS sending state information are available in the module messaging:

ECreated

EMovedToOutBox

EScheduledForSend

ESent: The SMS message has been sent.

EDeleted: The SMS message has been deleted from device's outbox queue. The sms_send operation has finalized and subsequent SMS sending is possible.

EScheduleFailed

ESendFailed: This state information is returned when the SMS subsystem has tried to send the message several times in vain. The sms_send operation has finalized and subsequent SMS sending is possible.

ENoServiceCentre: This state information is returned by the SMS subsystem in S60 3.x emulator. In emulator this indicates that the sms_send operation has finalized and subsequent SMS sending is possible.

EFatalServerError

The underlying messaging subsystem in S60 devices might give error messages to the user if the device is not connected to a network while trying to send a message - An "SMS send failed!" note is a common error message.

When sending messages in offline-mode or with no network connection these messages are actually added to an outgoing message queue and they might be sent if the device is later on connected to a suitable network^4.7. This occurs despite the possibly misleading error messages. The current network conditions can be checked e.g. with sysinfo.active_profile() and sysinfo.signal_bars() invocations.

The following is example code for state information processing with sms_send operation:

>>> import messaging
>>>
>>> def cb(state):
...   if state==messaging.ESent:
...     print "**Message was sent**"
...   if state==messaging.ESendFailed:
...     print "**Something went wrong - Truly sorry for this**"
...
>>> messaging.sms_send("1234567", "Hello from PyS60!", '7bit', cb, "Mary")
>>> **Message was sent** # This is printed from the callback

Footnotes

...msg ^4.4: The maximum length of a message that can be sent using sms_send function is either 39015 characters or Max network capacity whichever is lower.
... failed ^4.5: Please note that this blocking might last for several minutes and hence supplying the callback might be more suitable in many cases.
... entry ^4.6: The name can be of maximum 60 characters and will be shown in the sent item message entry as specified by sender without making any check in the contact database.
... network ^4.7: Note also that prior this the user of the device can explicitly delete the messages from the native messaging application. The amount of resending is approx. 4 times - After this the sending operation is cancelled and the user of the device will see a visual cue of the failure in the status pane.

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

4.3 messaging -- A messaging services package

Footnotes

4.3 `messaging` -- A messaging services package