172 MIDP 2.0 AND THE JTWI public void itemStateChanged(Item item){ if (item instanceof Gauge){ Gauge volumeIndicator = (Gauge)item; int level = volumeIndicator.getValue(); audioPlayer.setVolume(level); } } The itemStateChanged() method obtains the value requested by the user and invokes the setVolume() method to adjust the audio playback volume via the Player’s VolumeControl. The showAlert()method (see below) is called by the AudioPlayer instance in the event of an Exception being thrown at any stage of the Player lifecycle. public void showAlert(String title, String message){ Alert alert = new Alert(title, message, null, AlertType.ERROR); display.setCurrent(alert, initialView); initialView.removeProgressGauge(); initialView.addCommand(playCommand); } After displaying an error Alert, the current Displayable is set to the InitialView allowing the user to try either the same URL again or a different URL. The MIDletController class also provides a couple of callback methods: updateProgressGauge and removeVolumeControl. The first updates the InitialView progress gauge as the Player progresses through its lifecycle. The second removes the interactive volume indicator Gauge from the PlayerView in the event that the implementation of Player does not support a VolumeControl. The full source code and JAR and JAD files for the Audio Player MIDlet can be downloaded from the Symbian website at www.symbian. com/books . 3.4.1.5 Working with Video We shall now illustrate how to play a video with code highlights taken from a simple Video Player MIDlet (see Figure 3.26). The architecture of the Video Player MIDlet (see Figure 3.27) is very similar to that of the Audio Player. The MIDlet contains four classes: MIDletController, InitialView, VideoPlayer and VideoCanvas. The VideoCan- vas is used for rendering the video playback as well as providing controls similar to those found in the PlayerView of the Audio Player MIDlet. The other classes fulfill very similar roles to their equivalents in the Audio Player MIDlet. OPTIONAL J2ME APIS IN THE JTWI 173 Figure 3.26 The Video Player MIDlet running on a Nokia Series 60 phone. javax.microedition.lcdui.Form InitialView MIDletController VideoPlayer javax.microedition.media.control.VideoControl javax.microedition.lcdui.Canvas javax.microedition.media.Player VideoCanvas Figure 3.27 UML class diagram of the Video Player MIDlet. The VideoPlayer Class Let’s first take a look at the key methods of the VideoPlayer class: import javax.microedition.media.*; import javax.microedition.media.control.*; import java.io.*; // Acquires the video content and renders it public class VideoPlayer implements Runnable { private final static String THREE_GPP = "3gp"; private final static String MPEG = "mpg"; 174 MIDP 2.0 AND THE JTWI private final static String MIME_3GPP = "video/3gpp"; private final static String MIME_MPEG = "video/mpeg"; private MIDletController controller; private VideoCanvas canvas; private Player player; private VideoControl videoControl; private String resource; private String mimeType = THREE_GPP; private Thread initializer; public VideoPlayer(MIDletController controller, VideoCanvas canvas){ } public void initializeVideo(String resource){ } public void run(){ } public void startPlayer(){ } public void stopPlayer(){ } public void closePlayer(){ } } The constructor is shown below. public VideoPlayer(MIDletController controller, VideoCanvas canvas){ this.controller = controller; this.canvas = canvas; } It simply initializes the controller and canvas attributes with refer- ences to the MIDletController and the VideoCanvas respectively. One difference between the Video Player and Audio Player MIDlets is that the Video Player obtains its content from resource files packaged in the MIDlet suite JAR file, rather than from a remote resource. The initializeVideo() method takes the name of the video file as a parameter. public void initializeVideo(String resource){ this.resource = resource; String fileExt = resource.substring(resource.lastIndexOf('.') + 1); if(fileExt.equals(THREE_GPP)) { mimeType = MIME_3GPP; } else if(fileExt.equals(MPEG)) { mimeType = MIME_MPEG; } initializer = new Thread(this); initializer.start(); } OPTIONAL J2ME APIS IN THE JTWI 175 The resource file name is tested to ascertain its format (MPEG for the Sun’s J2ME Wireless Toolkit 2.0 emulator and 3GPP for real phones) and the appropriate MIME type set. A new thread is then launched to perform the essential initialization required to play the video content. The run() method, mandated by the Runnable interface, contains the initialization of the Player. public void run(){ try { InputStream in = getClass().getResourceAsStream("/" + resource); player = Manager.createPlayer(in, mimeType); player.addPlayerListener(controller); player.realize(); player.prefetch(); videoControl = (VideoControl)player.getControl("VideoControl"); if (videoControl != null) { videoControl.initDisplayMode( videoControl.USE_DIRECT_VIDEO, canvas); int cHeight = canvas.getHeight(); int cWidth = canvas.getWidth(); videoControl.setDisplaySize(cWidth, cHeight); videoControl.setVisible(true); startPlayer(); } else{ controller.showAlert("Error!", "Unable to get Video Control"); closePlayer(); } } catch (IOException ioe) { controller.showAlert("Unable to access resource", ioe.getMessage()); closePlayer(); } catch (MediaException me) { controller.showAlert("Unable to create player", me.getMessage()); closePlayer(); } } An InputStream is obtained from the resource file and used to create the Player instance. A PlayerListener (the controller)is registered with the Player in order to receive callbacks. The prefetch and realize() methods are then called on the Player instance. Once the player is in the PREFETCHED state we are ready to render the video content. First we must obtain a VideoControl by calling getControl on the Player, and casting it down appropriately. Note that the MMAPI specification requires that a player for video media must support a VideoControl, unlike the case of a player for audio content, where support for VolumeControl is only a recommended practice. 176 MIDP 2.0 AND THE JTWI The initDisplayMode() method is used to initialize the video mode that determines how the video is displayed. This method takes an integer mode value as its first argument with one of two predefined values: USE_GUI_PRIMITIVE or USE_DIRECT_VIDEO. In the case of MIDP implementations (supporting the LCDUI), USE_GUI_PRIMITIVE will result in an instance of a javax.microedition.lcdui.Item being returned: Item display = control.initDisplayMode(control.USE_GUI_PRIMITIVE, null); For CDC implementations supporting AWT, USE_GUI_PRIMITIVE will return an instance of java.awt.Component. For implementations that support both LCDUI and AWT, the required type must be specified by a String as the second argument: Item display = control.initDisplayMode(control.USE_GUI_PRIMITIVE, "javax.microedition.lcdui.Item"); The USE_DIRECT_VIDEO mode can only be used with implementa- tions that support the LCDUI (such as Symbian OS) and a second argument of type javax.microedition.lcdui.Canvas (or a subclass) must be supplied. This is the approach adopted in the example code above. Methods of VideoControl can be used to manipulate the size and the location of the video with respect to the Canvas where it will be dis- played. Since we are using direct video as the display mode it is necessary to call setVisible(true) in order for the video to be displayed. (In the case of USE_GUI_PRIMITIVE the video is shown by default when the GUI primitive is displayed.) Finally, we start the rendering of the video with the startPlayer() method. If at any stage an Exception is thrown the MIDletController.showAlert() method is called and the resources acquired by the Player are released by calling the closePlayer() method. The other methods of the VideoPlayer class are the same as their namesakes in the AudioPlayer class of the Audio Player MIDlet. The MIDletController Class The MIDletController class for the Video Player MIDlet is very similar to that of the Audio Player. The method signatures of the class are shown below. import javax.microedition.midlet.*; import javax.microedition.lcdui.*; import javax.microedition.media.*; // A simple video player MIDlet using JSR 135 - Mobile Media API public class MIDletController extends MIDlet implements OPTIONAL J2ME APIS IN THE JTWI 177 CommandListener, PlayerListener { private Command exitCommand, playCommand, backCommand, replayCommand; private Display display; private InitialView initialView; private VideoCanvas videoCanvas; private VideoPlayer videoPlayer; public MIDletController() { } public void startApp(){ } public void pauseApp(){ } public void destroyApp(boolean unconditional){ } public void commandAction(Command c, Displayable s){ } public void playerUpdate(Player p, String event, Object eventData) { } public void showAlert(String title, String message){ } public void releaseResources(){ } } The constructor is listed below: public MIDletController() { int noOfVideos = Integer.parseInt(getAppProperty( "number-of-videos")); String[] videoNames = new String[noOfVideos]; for (int i = 1; i <= noOfVideos; i++){ videoNames[i-1] = getAppProperty("video-" + i); } initialView = new InitialView(this, videoNames); exitCommand = new Command("Exit", Command.EXIT, 2); playCommand = new Command("Play", Command.SCREEN, 1); initialView.addCommand(exitCommand); videoCanvas = new VideoCanvas(this); backCommand = new Command("Back", Command.BACK, 1); videoCanvas.addCommand(backCommand); videoPlayer = new VideoPlayer(this, videoCanvas); display = Display.getDisplay(this); } It first uses the MIDlet getAppProperty() method to retrieve user- defined attributes from the JAD file, namely the number of video files packaged in the JAR and their names. The names are then used to initialize the InitialView. The VideoCanvas and VideoPlayer instances are then created. 178 MIDP 2.0 AND THE JTWI All the other methods in MIDletController are essentially the same as their Audio Player namesakes. The VideoCanvas Class We will briefly take a look at the (very simple) VideoCanvas class: import javax.microedition.lcdui.*; public class VideoCanvas extends Canvas{ public VideoCanvas(MIDletController controller){ setCommandListener(controller); } // Paints background color public void paint(Graphics g){ g.setColor(128, 128, 128); g.fillRect(0, 0, getWidth(), getHeight()); } } The important point to note is that the paint() method plays no part in rendering the video. This is performed directly by the VideoControl. The full source code and JAR and JAD files for the Video Player MIDlet can be downloaded from the Symbian website at www.symbian. com/books . 3.4.1.6 Capturing Images Another use of VideoControl is to capture images from a camera. In this case, rather than specifying a file (and MIME type) as the data source, we specify capture://video. Other than that, the setting up of the video player and control proceeds pretty much as in the Video Player MIDlet above. The Picture Puzzle MIDlet, included as a case study in Chapter 5, illustrates image capture. The following code which performs the neces- sary initialization of a video player and a control is reproduced from the Capturer class in that example. // Creates a VideoPlayer and gets an associated VideoControl public void createPlayer() throws ApplicationException { try { player = Manager.createPlayer("capture://video"); player.realize(); // Sets VideoControl to the current display. videoControl = (VideoControl)(player.getControl("VideoControl")); if (videoControl == null) { discardPlayer(); } else { OPTIONAL J2ME APIS IN THE JTWI 179 videoControl.initDisplayMode(VideoControl.USE_DIRECT_VIDEO, canvas); int cWidth = canvas.getWidth(); int cHeight = canvas.getHeight(); int dWidth = 160; int dHeight = 120; videoControl.setDisplaySize(dWidth, dHeight); videoControl.setDisplayLocation((cWidth - dWidth)/2, (cHeight - dHeight)/2); } By setting the Canvas to be the current one in the Display, we can use it as a ‘‘viewfinder’’ for the camera. When we are ready to take a picture, we simply call getSnapshot(null) on the VideoControl, as shown in the following code from the Picture Puzzle MIDlet: public byte[] takeSnapshot() throws ApplicationException { byte[] pngImage = null; if (videoControl == null) { throw new ApplicationException("Unable to capture photo: VideoControl null"); } try { pngImage = videoControl.getSnapshot(null); }catch(MediaException me) { throw new ApplicationException("Unable to capture photo", me); } return pngImage; } It should be noted that, if a security policy is in operation, user permission may be requested through an intermediate dialog, which may interfere with the photography! 3.4.1.7 Generating Tones MMAPI also supports tone generation. Generating a single tone is simply achieved using the following method of the Manager class: public static void playTone(int note, int duration, int volume) throws MediaException The note is passed as an integer value in the range 0–127. ToneCon- trol.C4 = 60 represents middle C. Adding or subtracting 1 increases or lowers the pitch by a semitone. The duration is specified in milliseconds and the volume is an integer value on the scale 0–100. To play a sequence of tones it is more appropriate to create a Player and use it to obtain a ToneControl. 180 MIDP 2.0 AND THE JTWI byte[] toneSequence = { ToneControl.C4, ToneControl.C4 + 2, ToneControl.c4 +4, }; try{ Player player = Manager.createPlayer(Manager.TONE_DEVICE_LOCATOR); player.realize(); ToneControl control = (ToneControl)player.getControl("ToneControl"); control.setSequence(toneSequence); player.start(); } catch (IOException ioe) { } catch (MediaException me) { //handle } A tone sequence is specified as a list of tone–duration pairs and user- defined sequence blocks, using Augmented Backus–Naur form (ABNF) syntax (refer to the MMAPI specification for more detail). The list is packaged as a byte array and passed to the ToneControl using the setSequence() method. To play the sequence we simply invoke the start() method of the Player. A more sophisticated example can be found in the documentation of ToneControl in the MMAPI specification. 3.4.2 MMAPI on Symbian OS Phones We next look at the important question of which media capabilities are supported in practice on the various Symbian OS phones on the market. It is important to understand that when we talk about MMAPI on Symbian OS we are not talking about a single version but three, based on two distinct implementations. These are: • Symbian MIDP 2.0 Audio subset (on Symbian OS Version 7.0) • Series 60 Developer Platform 1.0 (on Symbian OS Version 6.1) • Series 60 Developer Platform 2.0 (on Symbian OS Version 7.0s). These MMAPI implementations will be discussed in turn. MMAPI was first implemented on Symbian OS not by Symbian but by Nokia, for their Series 60 Developer Platform 1.0 (as embodied in the Series 60 MIDP SDK 1.2.1 for Symbian OS, Nokia edition, based on Symbian OS Version 6.1). This is available on all phones based on this platform, with the exception of the Nokia 7650 which was technically based on a precursor to the Series 60 Developer Platform 1.0, and provided multimedia capabilities only through custom Nokia APIs. This implementation was extended by Nokia for the Series 60 Devel- oper Platform 2.0 and Series 90 Developer Platform 1.0, both based on Symbian OS Version 7.0s. At the time of writing, the only announced phones based on these platforms are the Nokia 6600 and the Nokia 7700, based on Series 60 and Series 90 respectively. OPTIONAL J2ME APIS IN THE JTWI 181 As the number of phones based on these platforms continues to grow, the reader is referred to www.symbian.com/phones to ascertain the cur- rent list. Note that Nokia licenses its platforms to other mobile phone manufacturers, so the list is not restricted to Nokia phones. At the same time, Symbian has separately implemented the audio subset (‘‘building block’’) of MMAPI defined by MIDP 2.0, which became available with the release of Symbian OS Version 7.0s. Consequently, it is not available as standard on phones based on Symbian OS Version 7.0. However, the whole of MIDP 2.0 has been ‘‘backported’’ from Symbian OS Version 7.0s to Symbian OS Version 7.0 as part of the upgrade of the UIQ platform from UIQ 2.0 to UIQ 2.1. As a result, phones based on UIQ 2.1 (the first of which to be announced are the Sony Ericsson P900/P908 and the BenQ P30) support the audio subset. Symbian is releasing a fully featured MMAPI implementation in the forthcoming Symbian OS Version 8.0, which will be available for all Symbian OS phones (see www.symbian.com/technology/standard- java.html ). This will certainly mean a closer match of the MMAPI capabilities of Symbian OS phones based on different UIs than at present. 3.4.2.1 Symbian MIDP 2.0 Audio Subset The audio subset of MIDP 2.0 is described in the MIDP 2.0 specification document under javax.microedition.media and javax.micro- edition.media.control. Notably there is no javax.micro- edition.media.protocol package, since custom DataSources are not supported. The associated overridden version of Manager. createPlayer() is not, as a result, supported either. Only two con- trols are available, VolumeControl and ToneControl, both of which are fully supported by Symbian OS. There is no support for media recording or capture. The following are the audio formats supported: Format File extension MIME types AU audio .au audio/basic Wave audio .wav audio/wav, audio/x-wav MP3 .mp3 audio/mp3 Tone sequence n/a audio/x-tone-seq These can all, with the exception of tone sequences, be played via the various mechanisms described in Section 3.4.1.2. Tone sequences differ in that there is no file extension associated with them; they can only be created in a programmatic manner, in the context of a ToneControl. [...]... technology for battery-powered devices Symbian OS has provided native support for Bluetooth since Symbian OS Version 6.1 Programming Java 2 Micro Edition on Symbian OS: A developer’s guide to MIDP 2. 0 Martin de Jode  20 04 Symbian Ltd ISBN: 0-470-0 922 3-8 20 6 JAVA APIs FOR BLUETOOTH WIRELESS TECHNOLOGY 4 .2 Introduction to the Bluetooth APIs The aim of JSR 82 was to provide a standard set of Java APIs... class package com .symbian. devnet.chatmidlet; import javax.microedition.midlet.*; import javax.microedition.lcdui.*; import javax.wireless.messaging.*; import javax.microedition.io.*; import java. io.*; public class ChatMIDlet extends MIDlet implements CommandListener, MessageListener{ private Sender sender; private Receiver receiver; private MessageConnection smsconn; //Widgets for the UI for entering and... method For a client mode connection (as used in the code listed above), messages can only be sent The URL address syntax for a client mode connection has the following possible formats: • sms://+44711 122 2333 • sms://+44711 122 2333: 123 4 The first format (as in the example above) is used to open a connection for sending a normal SMS message, which will be received in the end-user’s inbox The second format... Messaging API on Symbian OS shipped as part of Nokia’s Series 60 v1.x platform This WMA implementation supplemented the MIDP 1.0 environment available on this platform The first phone to support this implementation of the WMA was the Nokia 3 650 More recently, a MIDP 2. 0-compatible version of the WMA shipped as part of Symbian OS Version 7.0s which forms the basis for Nokia’s Series 60 v2.0 platform The first... default encoding= png for Series 60 v2.0; returns a list of all supported encodings for Series 60 v1 .2 and Symbian OS Version 8.0 (for which the default is the first value in the list) • streamable.contents – returns null on all Symbian OS phones 3.4.3 MMAPI and the MIDP 2. 0 Security Model For reasons of privacy the following Mobile Media API calls are restricted under the MIDP 2. 0 security model (see... tested on real Symbian OS- based MIDP 2. 0 phones In the next chapter we will look at another optional API, the Java API for Bluetooth Wireless Technology, that is supported by the latest generation of Symbian OS phones, but which does not currently fall under the JTWI 4 Java APIs for Bluetooth Wireless Technology In the last chapter we considered MIDP 2. 0 and the optional APIs that form part of the... javax.microedition.io.Connector.sms – needed to open an SMS connection • javax.wireless.messaging.sms.send – needed to send an SMS • javax.wireless.messaging.sms.receive – needed to receive an SMS MIDlet-Permissions: javax.microedition.io.Connector.sms, javax.wireless.messaging.sms.send or: MIDlet-Permissions: javax.microedition.io.Connector.sms, javax.wireless.messaging.sms.send, javax.wireless.messaging.sms.receive If the protection... currently does not support receiving CBS 3 .5 MIDP 2. 0 and Symbian OS Phones At the time of writing, two MIDP 2. 0 phones based on Symbian OS have been released: the Nokia 6600 and Sony Ericsson P900/P908 Both phones implement the mandatory APIs and the minimum configuration required by the JTWI The Nokia 6600 (Figure 3.30) is a Series 60 Version 2. 0 phone based on Symbian OS Version 7.0s It runs the CLDC 1.0... many more possibilities are presented 3.4 .2. 5 Working Out What Is Supported If you know which of the Symbian OS platforms you are targeting with a MIDlet, you will be able to craft your code to conform to the cited capabilities However, in practice it is more likely that you will want to write portable code which can run on several or all of the above platforms, or indeed on non -Symbian OS phones with... Ltd MIDlet-Version: 2. 0 MicroEdition-Configuration: CLDC-1.0 MicroEdition-Profile: MIDP -2. 0 Note that the MIDlet-push-1 entry (shown below) is required to register a push registry connection: MIDlet-Push-1: sms://: 123 4, com .symbian. devnet.chatmidlet.ChatMIDlet, * Screenshots of the ChatMIDlet running on a Nokia 6600 are shown in Figure 3 .29 The full source code and JAR and JAD files for the ChatMIDlet . on Symbian OS not by Symbian but by Nokia, for their Series 60 Developer Platform 1.0 (as embodied in the Series 60 MIDP SDK 1 .2. 1 for Symbian OS, Nokia edition, based on Symbian OS Version 6.1) audio subset of MIDP 2. 0 is described in the MIDP 2. 0 specification document under javax.microedition.media and javax .micro- edition. media.control. Notably there is no javax .micro- edition. media.protocol. MIDlet. OPTIONAL J2ME APIS IN THE JTWI 173 Figure 3 .26 The Video Player MIDlet running on a Nokia Series 60 phone. javax.microedition.lcdui.Form InitialView MIDletController VideoPlayer javax.microedition.media.control.VideoControl javax.microedition.lcdui.Canvas javax.microedition.media.Player VideoCanvas Figure