Prev: Module obex: Object Exchange Client
Module sms: Short Messages
This module supports sending and receiving of short messages.
Messages are identified by numbers. These numbers are used to retrieve and update message contents, and to delete messages.
When a function of the module is called for the first time, it starts listening for incoming messages and enqueues their numbers. Calling sms.receive will return these numbers. Messages received earlier can be retrieved from the inbox.
Messages longer than the maximum length (160 characters in the default alphabet) can also be sent and received. They are transmitted as "concatenated SMS", but the module handles this automatically.
The typical sequence to consume messages starting with a certain token (//tok in our example) is:
nr=sms.receive(); // wait for a new message
msg=sms.get(nr); // get the message
words=split(msg["text"]); // split the text into words
if len(words)>0 and words[0] = "//tok" then
// first word is //tok, delete it from inbox
sms.delete(nr);
// process message
end
|
sms.delete
• function delete(msgnum) → null
Permissions: WriteApp+FreeComm
Delete the message with number msgnum from the inbox.
Throws ErrNotFound if the message with this number does not exist.
// delete all SMS inbox messages older than a week
lastweek=time.get()-7*24*3600;
for id in sms.inbox() do
if sms.get(id)["time"]<lastweek then
sms.delete(id)
end
end
|
sms.get
• function get(msgnum) → Array
Permissions: ReadApp+FreeComm
Get the contents of the message with number msgnum. The message contents are returned as an array with the following keys:
| Key | Contents |
| sender | The phone number of the sender of the message. |
| text | The text of the message. |
| time | The time stamp of the message, as seconds since the start of year 0. See also module time. |
| unread | true if the message is still unread, false if it has been seen. |
| |
Throws ErrNotFound if the message with number msgnum does not exist.
// print all messages in the SMS inbox
for id in sms.inbox() do
print sms.get(id)
end
→ [248,Delivery confirmation,63277873561,false]
...
|
sms.inbox
• function inbox() → Array
Permissions: ReadApp+FreeComm
Gets the ids of all SMS messages in the inbox.
print sms.inbox()
→ [1049241,1049289,1049292]
|
sms.receive
• function receive(timeout=-1) → Number|null
Permissions: ReadApp+FreeComm
Receives a new message and returns its id. If there is no message, waits until one arrives. If timeout>=0 and timeout milliseconds have passed without receiving anything, returns null.
Throws ExcValueOutOfRange if timeout exceeds 2147483 (35 minutes and 47.483 seconds).
// quickly check whether there is a new message
id=sms.receive(0);
if id#null then
msg=sms.get(id);
// process msg
end
|
sms.send
• function send(recipient, message, bits=7) → null
• function send(recipients, message, bits=7) → null
Permissions: CostComm
Sends a short message to one or several recipients. A single recipient is specified as a single phone number string, multiple recipients are specified as an array of phone number strings.
bits indicates the number of bits used to encode a character, thus limiting the length of a simple message. Longer messages will be concatenated from several simple messages, thus increasing transmission cost. The allowed values are:
| bits | Meaning | Max. length |
| 7 | Default text alphabet | 160 |
| 8 | Data alphabet | 140 |
| 16 | Unicode alphabet | 70 |
| |
This function does not return before the message has been sent (or an error occurs).
// send a silly message to two people
sms.send(["+41797654321", "+393401234567"],
"Good morning!")
|
sms.set
• function set(msgnum, message) → null
Permissions: WriteApp+FreeComm
Updates the short message with number msgnum with the fields from message. The keys listed in sms.get must be used. The sender and text of the message will only be changed in the SMS inbox summary; they cannot be changed in the actual message.
// mark all messages in the inbox as unread
for id in sms.inbox() do
sms.set(id, ["unread":true])
end
|
Next: Multimedia© 2004-2011 airbit AG, CH-8008 Zürich
Document AB-M-LIB-888
