Waqas Sadiq

Intended audience

This article describes, very briefly, the steps involved in providing WML pages to mobile devices, in particular WAP-enabled mobile phones. It assumes that reader is already familiar with HTTP, HTML, and Web server operation, but knows nothing about WML or WAP protocols. The article does not attempt to describe WML, but does provide a simple example.

Basic principles

Viewers for WAP content are often called microbrowsers. Microbrowsers are found in WAP-enabled mobile phones, and some PDAs, among other things. If you are familiar with Web servers, then you may be reassured to know that at least one thing is the same for WAP services: the HTTP protocol. WAP microbrowsers use exactly the same HTTP protocol for exchanging pages as ordinary Web servers and Web browsers do. So, although you could pay a good deal of money for a `WAP server' for your enterprise, in fact any Web server will do perfectly well; Apache, for example. Of course, some WAP server products offer a good deal more than basic HTTP support, such as portal services and content management. However, if you just want to create pages of data and make then available to WAP phones, all you need is a Web server. In the same way that Web browsers expect their pages to be delivered in HTML format, WAP microbrowsers expect content in WML format. WML (WAP Markup Language) is simply XML, formatted according to a particular schema. Unlike traditional HTML, which only has a passing resemblance to XML, WML is true XML. It can be processed by a validating parser, and ill-formed content rejected. In principle, WML's stricter syntax rules suggest that there should be less inter-browser variability in formatting than is the case for HTML, but my experience has not borne this out. You should consider testing your WML pages with more than one browser if you want good coverage.

A significant difference between WML and HTML is that a WML document can contain multiple pages (cards, in WAP jargon). When the browser loads the WML document, it will usually display the first page. This will generally contain links to the other pages. HTML, of course, has a single-page format. If you want to display multiple pages, you need multiple HTML files. The difference is for a very good reason. A WAP phone has to establish a dial-up session for each request, and this takes time. It is more convenient, therefore, if the browser can retrieve a set of pages at the same time. WML provides the concept of cards to enable pages to be grouped. Because a WML file contains cards, you will see the phrase `WML deck' used to mean a WML file. This is a trendy piece of jargon, and `deck' means nothing more than `file' in this context.

When a WAP-enabled phone is asked to display a WML page, it needs a URL. The URL has the same format, and meaning, as the URL in any ordinary Web browser. When it has the URL, the WAP phone will dial up a WAP gateway, and then issue an HTTP request for that URL, usually over the public Internet. The gateway collects the response, and returns it to the browser. The browser then hangs up (either immediately, or after a short delay).

The following sections describe step-by-step what you need to do to get a very simple WML page available to WAP phones.

Step 1: get a web server running

Unless you are going to run your own WAP gateway, that is, software that accepts incoming phone calls and relays them to a Web server, you need a web server on the public Internet. You don't need exclusive access to the server; if your existing web site is hosted by an ISP, even a free ISP, it should be possible to host WAP content as well. However, the Web server must deliver the correct content-type header when the browser requests WML content. With the Apache Web server, this mapping from file extensions to content types usually lives in /etc/mime.types, although you can also use an AddType directive in httpd.conf. Other servers have other conventions. As a miniumum, you need to ensure that the file extension .wml, or whatever else you intend to use for your WML pages, maps onto the content type text/vnd.wap.wml. There are other content type mappings you might need, but this one is a minimum. The problem with using any kind of shared Web server, either paid for or not, is that you may not be able to influence the mappings of file extensions onto content types. However, all modern Apache versions have WAP mappings in the default mime.types file, so if your ISP uses Apache you should have no problems.
If you intend to deliver Java applications to suitably-equipped devices via your WML pages, then you need to make sure that the appropriate content types are mapped. This is not a default in Apache, so you'll need to do it yourself. Add the following lines to httpd.conf:

AddType text/vnd.sun.j2me.app-descriptor jad
AddType application/java-archive jar

Of course, other Web servers will require this configuration as well, using whatever technique they support. It is not difficult, in principle, to run your own WAP gateway, and this may be useful for a company that wants to provide a private resource to its employees. A WAP gateway is nothing more than a modem and a PPP server. However, to make use of a private gateway requires some reconfiguration of the browser's communications settings, and not every WAP phone user will be happy doing this reconfiguration.

Step 2: create a WML page

This is not the place for a tutorial on WML; in any case, there are plenty of those on the Web. Suffice it to say that you need a WML page to test your WAP service, and if this is your first time using WML you should probably make it as simply as possible. The listing below shows a very simply example: it is a deck of two cards, with links between the cards and a bit of text.

<?xml version="1.0"?>
<!DOCTYPE wml PUBLIC "-//WAPFORUM//DTD WML 1.1//EN"
"http://www.wapforum.org/DTD/wml_1.1.xml">
<wml>
<card id="test1" title="KB WAP test p1">
<p>
Test page 1
</p>
<p>
<a href="#test2">Next page</a>
</p>
</card>
<card id="test2" title="KB WAP test p2">
<p>
Test page 2
</p>
<p>
<a href="#test1">Prev page</a>
</p>
</card>
</wml>

Step 3: upload and test with an emulator

Put you WML page(s) into any convenient place on your Web site. If you are planning to build a large WAP site, you would probably want to set up a separate site or area of your site, but this isn't essential. When you request the WML page with a browser, you will specify its URL just as for an HTML page. I strongly recommend testing the WML pages, and the Web server, using a WAP browser emulator. Then if things don't go according to plan when you request the page using a microbrowser, you can at least be reasonably confident that the problem does not lie with your Web server or its configuration. I use Deck-it from PyWeb; this is available free of charge for Linux and Windows systems. All you have to do is run Deck-it, and enter the URL of your WML page.

One word of warning, however: do not assume that because you can fetch and display your content using an emulator, you will be able to do so using a real microbrowser. Deck-it, and most other emulators, are far more tolerant of badly-formed WML, and incorrect response headers, than real microbrowsers and WAP gateways are. Remember that a microbrowser is very limited in its memory footprint, so it will parse the WML in a fairly prescriptive way. If your WML isn't up to par, not only will you not get a display, but you won't even get a helpful message. Error messages like `bad response from origin server' may simply mean that your WML is syntactically incorrect. It's worth getting hold of a WML validator, the stricter the better. Alternatively, there is a public WML validation service at HTMLHelp.

Step 4: test with a microbrowser

If you are using a WAP-enabled phone or PDA, all you need do is start the browser, and enter the URL. On Nokia phones, for example: select `Services' from the main menu, scroll down to `Go to address', then enter the URL. With a bit of luck, you should get the same display on the screen that you did on the emulator, or at least something similar. As mentioned before, don't assume that because an error message looks horribly technical, that it isn't a simple error like missing a closing tag in the WML.
Be aware that some low-cost mobile phone services restrict phones to getting WAP content from the service provider's hosts. If you have such a phone service, it will be difficult to enter the URL of your WML site. Nearly all mobile phones allow the communications settings to be changed, and the limition can be overcome by pointing the phone at a different WAP gateway. Of course, you may have to pay for the use of such a service.

Providing Java applications to WAP devices

This is not the place to describe how to create Java applications for mobile devices; I assume that you have available the JAR and/or JAD files that implement the desired application. In brief, the JAR file contains Java executable code in compressed format, while the JAD file is a text file that provides information about the application. Not all WAP devices require JAD files, but most do, so it's as well to provide them. Mobile devices that support Java applications (known as midlets) generally provide a number of ways for the user to get applications onto the device. For WAP devices, an interesting approach is to make the applications available for download using WAP protocols. In WAP jargon this is called over the air (OTA) installation. Devices that don't support OTA will use a cable, or bluetooth, or infra-red communication. These installation methods are not relevant to the present discussion, as they are proprietary and not covered by WAP standards. I will concentrate here on making Java applications available OTA.

WAP phones that support OTA installation normally provide the user with at least one of the following methods of download.

• The user follows a link in the browser to a JAD or JAR file (JAD is more widely supported). The device downloads the JAD, locates the corresponding JAR, downloads the JAR, and installs it. Normally the user gets asked at some point if it is OK to install.


• The user tells the phone to install an application, and provides a URL. The URL links to a WML page that contains a list of hyperlinks to JAD or JAR files. The device extracts the hyperlink text from the page, and presents a menu of application choices. When the user selects an application, the device downloads the corresponding JAD and JAR file, and installs the application.

You can support both these methods using the same WML page: just provide a page titled `Application downloads', or whatever, and provide in the WML a list of hyperlinks like this:

<a href="myhost://myurl/app1.jad">Application 1</a>
<a href="myhost://myurl/app2.jad">Application 2</a>
...etc

The use of absolute URLs in the href tags is necessary, for maximum portability. Mobile devices don't necessarily assume that a Java application can be obtained from the same directory as the WML file that references it, even if that is the case. In other words, even if your JAD and JAR files are in the same directory as the WML files, you'll still need absolute URLs to the JAD files.