Module mms: Multimedia Messages

Compatibility of module mms Sony Ericsson phones: all functions except mms.send[16] ErrNotSupported

This module supports sending and receiving of multi media messages (MMS). In the context of this module, an MMS is simply a set of files being sent from and to mobile devices, very similar to an e-mail with attachments.

MMS 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 mms.receive will return these numbers. Messages received earlier can be retrieved from the inbox.

The typical sequence to consume messages starting with a certain token in the subject (//tok in our example) is:

nr=mms.receive(); // wait for a new message msg=mms.get(nr); // get the message words=split(msg["subject"]); // split into words if len(words)>0 and words[0] = "//tok" then   // first word is //tok, process message files   for f in msg["files"] do     ...   end;   // delete it from the inbox   mms.delete(nr) end

The functions in this module correspond to those in module sms for short messages.

• mms.delete
• mms.get
• mms.inbox
• mms.open
• mms.receive
• mms.send
• mms.set

mms.delete

Delete the message with number msgnum from the inbox.

Throws ErrNotFound if the message with this number does not exist.

// delete all MMS inbox messages older than a week lastweek=time.get()-7*24*3600; for id in mms.inbox() do   if mms.get(id)["time"]<lastweek then     mms.delete(id)   end end

mms.get

Compatibility of function mms.get Symbian 3rd/5th Edition phones: the file names returned by this call are not directly accessible, use mms.open to read their data.

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 (or other address) of the sender of the message.
subject	The subject 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.
files	The list of files comprising the message.

Throws ErrNotFound if the message with number msgnum does not exist.

// play all MIDI files found in the MMS inbox for id in mms.inbox() do   for f in mms.get(id)["files"] do     if len(f)>3 and substr(f,len(f)-4)=".mid" then       audio.play(f); audio.wait()     end   end end

mms.inbox

Gets the ids of all MMS messages in the inbox.

print mms.inbox() → [1045642,1045678,1047382]

mms.open

Opens the attachment with index index, and returns a stream object to read its data from. index is the index into msg.get(msgnum)['files'].

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.

// Copy all attachments of an MMS to a directory function copyAttmts(msgnum, dir)   m=mms.get(msgnum);   for j=0 to len(m['files'])-1 do     name=m['files'][j];     name=substr(name, rindex(name, '\\')+1);     i=mms.open(msgnum, j);     print "Copying ",io.size(i),"bytes to",name;     o=io.create(dir+'\\'+name);     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 end

mms.receive

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 MMS id=mms.receive(0); if id#null then   msg=mms.get(id);   // process msg end

mms.send

Compatibility of function mms.send Sony Ericsson phones: character sets of attached files and the sender cannot be set. ErrNotSupported

Sends a multimedia 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.

The message will get the subject subject. The files to be attached are defined by files, an array with one element for each file to be sent. Each element is:

• Either a string, directly denoting the file name, with automatically derived MIME type and default character set,
• or an array of one to three elements, in the form [name,mimeType,charset]. name is a string denoting the file name, mimeType (if not missing or null) is the MIME type of the file, and charset (if not missing or null) is the character set/encoding specified as an integer IANA MIB enum value.

MIB enum	Description
3	US-ASCII
4	ISO-8859-1 (Latin 1)
5	ISO-8859-2 (Latin 2)
106	UTF-8
1000	ISO-10646-UCS-2 ("Unicode")
1001	ISO-10646-UCS-4

If sender is not null, the From: field of the outgoing message is set to sender. Note that most MMSCs will set this field to the MSISDN of the sending device when receiving the MMS, so specifying a sender has no effect unless you operate your own MMSC.

This function throws ErrNotFound if any of the files to be attached does not exist.

This function returns as soon as the message has been placed in the outbox. Actual sending may occur at a later time ("store and forward" principle).

// find all m scripts f=files.scan(system.docdir + "*.m"); // prepend the directory for i=0 to len(f)-1 do   f[i]=system.docdir+f[i] end; // send all those files to two people mms.send(["+41797654321", "+393401234567"],          "My mShell scripts", f); // send all those files again, specifying a MIME type // and Latin 1 character set for i=0 to len(f)-1 do   f[i]=[f[i],'text/plain',4] end; mms.send(["+41797654321", "+393401234567"],          "My mShell scripts", f);

mms.set

Updates the short message with number msgnum with the fields from message. The keys listed in mms.get must be used. The sender and subject of the message will only be changed in the MMS inbox summary; they cannot be changed in the actual message. files cannot be changed at all.

// mark all MMS in the inbox as unread for id in mms.inbox() do   mms.set(id, ["unread":true]) end