PrintTest

Gidlet

Eleventh example

Purpose: Today most mobile phones are enabled to use the Multimedia Messaging Service (MMS), a important extension of SMS. With MMS mere kind of multimedia information may be exchanged, so text documents, audio, images and even video. An typical MMS message contains several message parts. Data in each part is transferred as byte stream with its own mime type. The WMA (Wireless Mobile API) contains all necessary classes to handle MMS, but the Gidlet framework puts another layer of simplicity on top of it.

In this example, an image stored in a resource file is sent to a given recipient. MMS uses a string type application identifier, that must correspond to the receiver MIDlet's identifier. If no identifier is used, the default MMS application of the mobile phone (and not a MIDlet) will capture the message.

// MmsSendGidlet.java

import javax.wireless.messaging.*;
import javax.microedition.lcdui.*;
import ch.aplu.gidlet.*;

public class MmsSendGidlet extends Gidlet
{
  private MForm f = new MForm("OK to send image");
  private final String appId = null; // Standard MMS
  private Item it;
  private String phonenumber;

  public void main()
  {
    it = f.addInputField("To phone number?",
                         "5550000",                           INT_VALIDATE);
    f.show();
    waitOk();
    phonenumber = f.getText(it);
    byte[] image = getResource("/res/raptor.png");
    if (image != null)
    {
      try
      {
        MessagePart imagePart =
          new MessagePart(image, "image/png", "id1",
                         "location", null);
        MessagePart[] parts = {imagePart};
        sendMMS(phonenumber, appId,                                "A raptor is coming", parts);         f.append("Trying to send MMS...");
      }
      catch (SizeExceededException ex)
      {
        f.append("image too big");
      }
    }
    else
      f.append("failed to load image");
  }

  public void notifyOutgoingMMS(int status)
  {
    if (status == 0)
      f.append("success");
    else
      f.append("failed");
  }
}

Sender
(WTK emulator)

Recipient
(WMA console of WTK)

Execute MmsSendGidlet (if you have the Sun's Wireless Toolkit (WTK) installed and the JAD extension registered. Learn how to register the JAD extension). Execute MmsReceiveGidlet at the same time to communicate.

Discussion: The most important parameter of sendMMS() is an array of MessageParts. Each part contains a byte array for the data, a mime type, a string identifier, a location and an encoding scheme. We use the following constructor, as specified in the WMA documentation:

MessagePart(byte[] contents, String mimeType,String contentId, String contentLocation, String encoding)

When we send image to the standard application, only the data and the mime type are used. If the receiver is a MIDlet, the contentId is important in order to identify the part. sendMMS() spawns a thread for sending the MMS and returns immediately. This is a good idea, because on a real device the process may take some time and the program should not freeze. When the job is done, a callback notification is invoked and the parameter status informs us also about success or failure.

Instead of using the WTK emulator, that is somewhat boring, you may send the picture from a real device to a (eventually the same) real device. If you are afraid of the costs, you may write a receiver MIDlet as follows. Do not forget to change the appId to "MmsGidlet" in the MmsSendGidlet. Run the emulator twice at the same time for the sending and receiving device and select the phone number as shown on top of the emulated phone. (Sometimes the WTK does not like the two program instances and may even crash. Rerun it and hopefully it works.)

// MmsReceiveGidlet.java

import javax.microedition.lcdui.*;
import javax.wireless.messaging.*;
import ch.aplu.gidlet.*;

public class MmsReceiveGidlet extends Gidlet
{
  private final String appId = "MmsGidlet";
  private MForm f;
  private MMSReader reader;

  public void main()
  {
    f = new MForm("Waiting for image by MMS...");
    f.show();
    reader = new MMSReader(appId);
  }

  public void notifyIncomingMMS(MultipartMessage mpm)
  {
    beep(3); // Alarm

    byte[] data = mpm.getMessagePart("id1").getContent();
    Image image = Image.createImage(data, 0, data.length);
    ImageItem imageItem =
      new ImageItem("Received from " + mpm.getAddress(),                      image, Item.LAYOUT_CENTER,
                     "Image not displayable");
    f.append(imageItem);
    f.append("Subject: " + mpm.getSubject());
  }

  public void doExit()
  {
    if (reader != null)
      reader.stop();
    notifyDestroyed();
  }
}

Execute MmsReceiveGidlet (if you have the Sun's Wireless Toolkit (WTK) installed and the JAD extension registered. Learn how to register the JAD extension). Execute MmsSendGidlet at the same time to communicate.

Twelfth example

Purpose: With MMS you can even send an e-mail without having direct access to the internet. The Gidlet framework wraps the sendMMS() in a very simple and common sendMMSMail() method that takes the recipients mail address, the mail subject and the mail message as parameters (the coding scheme is ISO-8859-1).

// MmsMailGidlet.java

import javax.microedition.lcdui.*;
import ch.aplu.gidlet.*;

public class MmsMailGidlet extends Gidlet
{
  private MForm f;
  private Item it;
  private String mailaddress;

  public void main()
  {
    f = new MForm("OK continue");
    it = f.addInputField("E-mail address?",
                         "support@aplu.ch");
    f.show();
    waitOk();

    MTextBox tb = new MTextBox("Enter text, press OK");
    tb.show();
    waitOk();

    mailaddress = f.getText(it);
    String message = tb.getText();
    f.setTitle("Exit to quit");
    f.show();
    f.append("Trying to send e-mail...");
    sendMMSMail(mailaddress, "Success", message);
  }

  public void notifyOutgoingMMS(int status)
  {
    if (status == 0)
      f.append("success");
    else
      f.append("failed");
  }
}

Execute MmsMailGidlet (if you have the Sun's Wireless Toolkit (WTK) installed and the JAD extension registered. Learn how to register the JAD extension)

Discussion: sendMMSMail() returns immediately and an internal thread will do the job. When the thread terminates, it notifies us by calling notifyOutgoingMMS().

Thirteenth example

Purpose: Why not send a sound message with MMS? It's easy. put text and audio (from a resource file) in a MessagePart, add a subject and call sendMMS(). Keep in mind that the size of a MMS must be rather small (depending on your phone company, but normally smaller than 100 kBytes).

// MmsAudioGidlet.java

import javax.wireless.messaging.*;
import javax.microedition.lcdui.*;
import ch.aplu.gidlet.*;

public class MmsAudioGidlet extends Gidlet
{
  private MForm f = new MForm("OK to send MMS");
  private final String appId = null; // Default MMS receiver
  private Item it;
  private String phonenumber;

  public void main()
  {
    it = f.addInputField("To phone number?", "5550000", INT_VALIDATE);
    f.show();
    waitOk();
    phonenumber = f.getText(it);

    String subject = "Bird whistle";
    String message = "Do you know this bird?";
    byte[] soundClip = getResource("/res/bird.wav")
    if (soundClip != null)
    {
      try
      {
        MessagePart textPart =
          new MessagePart(message.getBytes(), "text/plain", "id1",
                          "location", "ISO-8859-1");
        MessagePart audioPart =
          new MessagePart(soundClip, "audio/wav", "id2", "location", null);
        MessagePart[] parts = {textPart, audioPart};
        sendMMS(phonenumber, appId, subject, parts, "id1");
        f.append("Trying to send MMS...");
      }
      catch (SizeExceededException ex)
      {
        f.append("MMS too big");
      }
    }
    else
      f.append("failed to load sound clip");
  }

  public void notifyOutgoingMMS(int status)
  {
    if (status == 0)
      f.append("success");
    else
      f.append("failed");
  }
}

Execute MmsAudioGidlet (if you have the Sun's Wireless Toolkit (WTK) installed and the JAD extension registered. Learn how to register the JAD extension)