Prev: Module mms: Multimedia Messages

Module msg: Generic Message Access

This module provides generic access to the messages (e.g. SMS, MMS, OBEX) stored on the phone.

The phone organizes messages into a hierachical tree of entries, much like an ordinary file system. The most important entry types are folders, messages and attachments. A typical message hierarchy could look as follows:

Each entry is identified by its unique id[17]. There are module constants for the ids of the four main folders: msg.inbox, msg.draft, msg.outbox, and msg.sent.

Note that the organization of folders is device dependent. For instance, Sony Ericsson phones devices have dedicated service entries for MMS. Scan from msg.root to obtain the complete hierarchy.

• msg.delete
• msg.move
• msg.open
• msg.scan
• Constants

msg.delete

• function delete(entryOrId) → null
  Permissions: FreeComm+ReadApp+WriteApp

Delete the message entry identified by entryOrId. entryOrId can be a complete entry, as returned by msg.scan, or simply an integer id.

Throws ErrNotFound if this entry does not exist.

for m in msg.scan(msg.sent, msg.msg) do   msg.delete(m) end

msg.move

• function move(entryOrId, newParentEntryOrId) → null
  Permissions: FreeComm+ReadApp+WriteApp

Move the message entry identified by entryOrId from its current parent to the entry identified by newParentEntryOrId. The latter is typically a folder. Both parameters can be a complete entry, as returned by msg.scan, or simply an integer id.

Throws ErrNotFound if this entry does not exist.

// move all .SIS file messages from the inbox to draft for m in msg.scan(msg.inbox, msg.msg, "*.sis") do   msg.move(m, msg.draft) end

msg.open

• function open(entryOrId, index=0) → Native Object|null
  Permissions: FreeComm+ReadApp

Opens a message or attachment entry, and returns a stream object to read the data at the given index from it. For attachment entries, the data is the file data from the attachment with the given index. For other entries, it is the message body, which has always index 0.

Returns null if the entry has no data to read.

The returned stream can be accessed with most functions from module io:

• io.read, io.readln, and io.readm read data,
• io.size gets the total number of bytes,
• io.avail gets the number of bytes remaining,
• io.seek changes the read position,
• io.close closes the stream,
• io.ces gets and sets the character encoding scheme. For messages, the default is io.utf16le and for attachments io.raw.

// Copy an attachment from the inbox to a file. function copyAttmt(name,file)   ms=msg.scan(msg.inbox, null, name);   // if there is no message, throw an exception   if len(ms)=0 then     throw "No message "+name   end;   // get the first attachment of the message   ms=msg.scan(ms[0], msg.attmt);   // if there is no attachment, throw an exception   if len(ms)=0 then     throw "No attachment for "+name   end;   i=msg.open(ms[0]);   print "Copying ",io.size(i),"bytes";   o=io.create(file);   b=io.read(i, 256);   while b#null do     io.write(o, b); b=io.read(i, 256)   end;   io.close(i); io.close(o) end

msg.scan

• function scan(parent=msg.inbox, type=null, pattern="*") → Array
  Permissions: FreeComm+ReadApp

Scan the message entry identified by parent for its direct children. parent can be a complete entry, as returned by this function, or simply an integer id. type restricts the entry type to the given type (e.g. msg.msg). If type=null, entries of all types are returned. pattern is a pattern which the two entry descriptions must match. It is not case sensitive and can contain the wildcards * and ?.

Returns an array with one element for each member found, each element being an array with the following keys:

Key	Meaning	Type
id	Entry id	Number
descr	Entry description (E.g. start of message text)	String
descr2	Other description (E.g. message sender)	String
time	The time stamp of the message, as seconds since the start of year 0. See also module time.	Number
unread	true if the message is still unread, false if it has been seen.	Boolean
type	Entry type	Number

// count the messages in the inbox print len(msg.scan()),"messages" → 13 messages // get the sent messages containing "morning" for m in msg.scan(msg.sent, msg.msg, "*morning*") do   print m end → [1048747,Good morning!,0779696969,63348191631,false, 268439402] [1048748,This morning I can't see you,0797654321, 63348191796,false,268439402]

msg Constants

• const attmt = The type indicating an attachment entry.
• const draft = The id of the folder with draft messages.
• const folder = The type indicating a folder entry.
• const inbox = The id of the folder with incoming messages.
• const local = The id of the service with local folders.
• const msg = The type indicating a message entry.
• const outbox = The id of the folder with outgoing messages.
• const root = The id of the root of the message entry hierarchy.
• const sent = The id of the folder with sent messages.

---

Next: Module obex: Object Exchange Client

Navigation