Websites Navigation: Airbit | Shop | m-shell.net
Languages: EN | DE

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

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

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

• function get(msgnum) → Array
  Permissions: FreeComm+ReadApp

  
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:

KeyContents
senderThe phone number (or other address) of the sender of the message.
subjectThe subject of the message.
timeThe time stamp of the message, as seconds since the start of year 0. See also module time.
unreadtrue if the message is still unread, false if it has been seen.
filesThe 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

• function inbox() → Array
  Permissions: FreeComm+ReadApp

Gets the ids of all MMS messages in the inbox.

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

mms.open

• function open(msgnum, index) → Native Object
  Permissions: FreeComm+ReadApp

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

• function receive(timeout=-1) → Number|null
  Permissions: FreeComm+ReadApp

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

• function send(recipient, subject, files, sender=null) → null
  Permissions: CostComm+Read(files)
• function send(recipients, subject, files, sender=null) → null
  Permissions: CostComm+Read(files)

  
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.
A few important character sets/encodings:

MIB enumDescription
3US-ASCII
4ISO-8859-1 (Latin 1)
5ISO-8859-2 (Latin 2)
106UTF-8
1000ISO-10646-UCS-2 ("Unicode")
1001ISO-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

• function set(msgnum, message) → null
  Permissions: FreeComm+WriteApp

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

© 2004-2011 airbit AG, CH-8008 Zürich
Document AB-M-LIB-888
mShell Home  > Documentation  > Manuals