Steve is the primary author of Programming Applications with the Wireless Application Protocol: The Complete Developer's Guide (John Wiley & Sons, 1999). He can be reached at [email protected].
There are more than 300 million cell-phone users in the world. There are also millions of Internet users. According to the prognosticators, the number of users of both of these technologies will continue to grow rapidly for several years.
There are a variety of forces at work causing a convergence of cell-phone and Internet technologies:
- The cost of buying and using both cell-phones and computers is decreasing.
- Both computer technology and cell-phone technology are becoming more powerful.
- Cellular networks, spurred on by the new digital technologies, are becoming more capable.
- Internet and cell-phone use is converging on flat-rate pricing.
- Technology users are increasingly more mobile.
As a result, cell-phone manufacturers are starting to build smart phonestelephones with full-blown programmable computers embedded in the hardware. Likewise, computer-device manufacturers are starting to build handheld computers with wireless communications capabilities. Both markets are converging on the same spotsmall, lightweight, inexpensive mobile-computing devices that are equally suitable for high-quality voice communications, modest bandwidth (5-10 Kbits/sec) data communications, seamless Internet connectivity, access to Internet services such as e-mail and content, and general-purpose, programmable computing devices that can run custom applications.
In the early 1990s, it was becoming apparent to major cell-phone manufacturers that wireless voice/data and the Internet would eventually converge. At the same time, Unwired Planet (since renamed phone.com) also started working on technologies to enable that convergence.
In June of 1997, the three largest cell-phone manufacturersEricsson, Motorola, and Nokiaand Unwired Planet announced the Wireless Application Protocol Forum (http://www.wapforum.com/), a nonprofit organization for creating standards for delivering Internet access to consumer-class wireless devices. The WAP Forum's goals are to:
- Create a global protocol specification that works on all wireless networks in all parts of the world.
- Enable the creation of content and applications that scale across a wide range of networks and devices.
- Embrace and extend existing standards and technologies whenever possible and appropriate.
Today the WAP Forum has dozens of members that represent all major handset manufacturers, wireless carriers, and computer manufacturers in the world.
The WAP Forum makes some assumptions about the consumer-class wireless devices that WAP will run on. First, these devices will have limited processing horsepower, RAM, ROM, and battery life. Additionally, they will have small screens and limited data-entry capabilities. The networks have some limitations as well. They are likely to be low-power networks with modest bandwidth. Because they're wireless, they are inherently unreliable, unstable, and unpredictable.
In the software industry, you can freeze a piece of code and start selling it to the public days later. In contrast, because of all the regulatory approvals, it typically takes cell-phone manufacturers 18 months to deliver a completed design to the marketplace. Consequently, you won't be able to buy any WAP 1.1-compliant devices until sometime in the year 2000 (even though the WAP 1.1 specification should be ratified by the time you read this). WAP devices are shipping in 1999, but are based on preWAP 1.0 specifications. All in all, the WAP Forum estimates that more than 10 million WAP devices will ship in 2000.
WAP
WAP is a multilayer communications architecture that borrows heavily from existing Internet standards while solving problems specific to wireless networks. The WAP specification has the following key components:
- An XML-based markup language, the Wireless Markup Language (WML), for creating applications.
- The WMLScript scripting language, loosely based on JavaScript, for adding computational power to WML.
- A microbrowser specification that defines how WML and WMLScript should be interpreted in the handset and presented to the user.
- A framework for Wireless Telephony Applications (WTA), providing functions that carriers can use to integrate the telephone and microbrowser functions of a WAP device.
- A lightweight protocol stack designed to minimize bandwidth requirements, work with a variety of wireless transports, and provide secure connections.
The WAP programming model is derived from the web programming model. On the Web, a user agent (usually a desktop browser) requests a document (static content) or a data processing task (dynamic content) from a server. The server responds to a static request by sending back an HTML document, a graphics file, or some other file format the user agent can hopefully understand and display. The server responds to a data processing request by launching a Common Gateway Interface (CGI) program that does some work, often using data sent by the user agent from a data-entry form, for instance. The CGI program responds with a document, often created on-the-fly, in some format that the user agent understands.
The WAP programming model also uses requests for both static and dynamic content. The difference is that all transactions are mediated by a WAP gateway server. Requests are sent, over a wireless network, from the WAP user agent to the gateway in compressed and optionally secure HTTP-compatible formats. The gateway translates those requests into uncompressed HTTP and sends them on to a web content server. The server responds, using HTTP, with a document that might be in WML, WMLScript, or WBMP (Wireless Bitmap) format. The gateway then compiles and compresses the WML and WMLScript into bytecodes and sends it back, using an HTTP-compatible compressed protocol, to the WAP user agent for display. Because WAP is designed to be an international standard, the gateway also negotiates character set requirements between the user agent and server, and transcodes character sets if necessary.
Although you can create WAP applications just by knowing WML and WMLScript, to really make the architecture sing, you need to have a thorough understanding of HTTP, the lingua franca of Internet transactions. The best place to start is by reading RFC2068, "Hypertext Transfer ProtocolHTTP/1.1," by R. Fielding, et al., January 1997 (ftp://ds.internic.net/rfc/ rfc2068.txt).
WML
WML is an XML-based language. In a nutshell, WML is a tagged language, much like HTML, where individual language elements are delineated by case-sensitive, lower-case tags that are enclosed in angle brackets. It's common to use the terms "element" and "tag" interchangeably when discussing WML programs.
The basic WAP application metaphor is a deck of cards, where each deck is essentially a program (more accurately, a document with a unique URL, delivered from a server). Each card is a single visible user interaction such as a choice list or a data-entry form. Syntactically, you usually put the nonvisible portion of the card, the part that contains executable elements, first, followed by the visible content. Listing One is a simple deck with one card.
The <wml> element encloses the deck, the <card> element encloses a card, and the <p> element encloses a paragraph containing the content. As you can see, like HTML, most elements end with a terminating tag that is identical to the starting tag with the additional of the character "/." There is also a short form syntax <tag/> for elements that don't contain any visible content.
When you run this program, it might appear as Figure 1 on a WAP phone. Just as HTML browsers decide specifically how to render content, WAP user agents have the same leeway. The same program may look and act differently, although the functionality should be identical, when run on two different WAP devices. An element may contain zero or more usually optional attributes, which are drawn from a list of attributes that are valid for that element. For instance, the <card> tag shown in Listing One has an id attribute. Attribute values are always enclosed in quotes.
Table 1 lists the full set of WML tags. They fall into eight groups. The first group covers basic deck structurecards, deck-level tags, and other odds and endsincluding a <meta> element for defining HTTP-like meta information for a deck. The content and formatting groups should look familiar to anyone who has worked with HTML.
The fourth group of elements provides data entry features, including formatted character entry and choice lists called <select> groups. To supplement the data entry elements, WML has variables. You can't set a variable's value directly, in an assignment statementthere is no such thing. You can only set WML variables as a side effect of some other action such as executing an HTTP POST request from a WML program or executing a task.
Tasks, Events, and Variables
The WML execution model recognizes tasks and events, the final two element groups. Tasks are programmatically defined actions. As Table 1 illustrates, there are four types<go> to a URL, <prev>, to go to the previously executed card, <refresh> the display, and <noop> for disabling deck-level task definitions at the card level. In all but the <noop> task, you can set a variable's value using a <setvar> element.
Events are things that happen as the result of user or system-level actions. WML has two types of eventsintrinsic and explicit. There are four intrinsic events:
- oneventforward, when a card is entered.
- onenterbackward, when a card is entered using the equivalent of a back button.
- ontimer, when a <timer> expires.
- onpick, when an <option> (choice list item) is selected.
You bind tasks to intrinsic events using the <onevent> element.
Listing Two is a simple Hello World card that, when entered, sets two variables and redraws the screen, showing the values of those two variables. Listing Two also demonstrates one way to initialize variables and reference them in a card's content. The <setvar> elements are executed before the <refresh> element.
There are three elements you can use to bind explicit events to tasks, as shown in Table 1. The first, and most common, is the <do> element, which gets executed when a user presses certain buttons on a WAP device. There are several predefined soft buttons that all WAP user agents must recognize, including Accept, Prev, Help, Options, and Reset. The two most-frequently used buttons are Accept and Prev. Accept is basically an OK button. Prev normally means that the user wants to navigate backwards in the user agent's history stack. It's similar to the Back button on a desktop browser.
Listing Three is a card that, in response to an Accept button, executes a <go> task to fetch a new deck that sits in the same directory as the deck containing the card.
The other way to bind explicit events to a task is to use anchors. Similar to HTML anchors, you can embed a <go>, <prev>, or <refresh> task in an <anchor> or abbreviated anchor, identified by the tag <a/>. Listing Four is the same deck using an anchor instead of a <do> element.
One particularly handy feature of WML is that you can use variables within most element attributes to dynamically alter your programs as they execute. Listing Five lets you enter a URL and a variable's value, and then send an HTTP POST request to the URL, passing the variable as a parameter. For this example to make any sense, nextdeck.wml needs to be a CGI program looking for a variable named var.
As you might have noticed, decks are identified by URLs. Cards within decks are identified by URL fragments. You also identify WMLScript compilation units with URLs, and functions within the compilation units with URL fragments.
WMLScript
WMLScript is a scripting language patterned loosely after JavaScript. It was designed to address WML's weak computational capabilities. Like WML, designed to work in devices with modest horsepower, WMLScript is lean and mean. It has just a handful of statements, but includes all those that you need to do serious procedural programming.
Table 2 shows the valid WMLScript statements. The use statement is a multipurpose statement. It includes pragma definitions for accessing functions in other compilation units, defining access controls for the current compilation unit, and defining HTTP-like meta information that might be useful in the WAP environment.
The WMLScript execution model is function oriented. There are no main programs. Instead, you create a set of functions and put the source code file on a server for access by WML and WMLScript programs. Listing Six is a WMLScript compilation unit. The extern keyword is necessary for any WMLScript function that must be called from outside its compilation unit.
To access the functions in a WMLScript compilation unit, you call them from a WML program using a URL, where the path points to the compilation unit and the fragment name points to the function. The bytecodes compiled on the WAP gateway are downloaded to the user agent, which has a WMLScript bytecode interpreter, and executed. When the function is finished, the interpreter returns control to the WML user agent.
If you put the preceding example in a file named "hellowmls.wmls," you can call it with the card in Listing Seven if the two are located in the same directory.
WMLScript is a weakly typed language with five internal data types: Boolean, Integer, Float, String, and Invalid, which might occur, for instance, when a floating-point operation results in a number outside the allowable range for floating-point numbers. It is used any time there's a need to distinguish a data item's value from the other four data types. You don't declare data types, but the compiler and run-time environment keep track of each variable's current type, which is determined when a value is assigned to it. Basic type conversions are automatic.
WMLScript has very simple scope rules. First, you cannot nest functions, so they have no implied complex scope. Second, all variables are local and only valid within the function in which they are declared. The run-time model is a simple stack: Parameters are pushed when a function is called and popped when exited. All parameters are passed by value.
WML can be extended with function libraries. WMLScript 1.1 has the following libraries:
- Lang. Basic arithmetic, conversion, flow control, and random number functions.
- Float. Floating-point functions like ceiling, floor, and square root.
- String. Substring, parsing, and string conversion functions.
- URL Functions. Verify and extract URL components.
- WMLBrowser. Functions for accessing WML variables and scheduling WML tasks.
- Dialogs. Functions to display simple dialogs.
Currently, the WAP forum does not provide tools or information for third-party developers to create their own libraries.
You've already seen an example of how you call a WMLScript function from a WML program.
You can also interact with the WML environment from within a WMLScript program using the WMLBrowser library. It includes functions for reading and writing WML variables from a WMLScript program.
You can also create a new WML context. (A context is the current variables, the WML card execution history stack, and the user agent cache.) You can also queue <go>, <prev>, and <refresh> tasks for execution after the WMLScript interpreter finishes its current thread.
Battleships
Instead of showing a few modest WMLScript example programs, I've included one larger program that incorporates both WML and WMLScript. It's a dumbed-down version of the game Battleships.
Classic Battleships is a two-person game where you set up your own playing board with multiple ships of different sizes. Players then take turns firing torpedoes at each other. The first player to sink all his opponent's ships wins.
For this implementation, designed for one player, you first select a playing field size of up to five rows by 10 columns (the default size), and the device places a single coordinate-size ship on each row. You then select a series of destinations for torpedo firing. The playing field is displayed using characters, not graphics.
Because WMLScript functions only have local variables, the ongoing state of the game is kept in a set of WML variables. Because WMLScript has more computational power than WML, the variables are initialized and changed entirely within WMLScript functions. This is an example of the interesting symbiosis between the two WAP language components.
The game starts with a two-card WML deck named bshipws.wml (available electronically; see "Resource Center," page 5). The first card displays a splash screen (see Figure 2) with two anchors: Play, which starts the game, and Rows/ Cols, which lets you set the playing board size. If you select Play, the WML deck calls the WMLScript function InitBoard, which creates the five display lines of the default playing board. At its conclusion, InitBoard returns to the second card using a WMLBrowser.go function call. The second card just displays the playing board and waits for you to enter a torpedo firing location.
If you select Rows/Cols, the WMLScript function GetBoardSize is called. Using the Dialogs.prompt library function, it asks you to enter your preferred board size, calls InitBoard to initialize the board, and then goes to card2 in the WML deck to wait for firing instructions.
The WMLScript FireTorpedo function is called when you request to fire a torpedo. It firsts asks you to enter a set of coordinates for the firing location (Figure 3), calculates the new board after the firing, and displays it. Torpedoes that hit nothing appear as underscores ("_") and ships that are hit appear as equals signs ("="). When you hit a ship, the rest of the line containing the ship is cleared out. Figure 4 shows a board in the middle of a game. The game is over when you hit all the ships.
This rendition of Battleships doesn't make for very challenging play, but it does demonstrate some of the basic principles of WML and WMLScript programming. To make it more interesting, you could extend it into a two-person game initiated with a telephone call and played using messaging services of one kind or another. Alternately, you could put the game logic on a server and play against a device with some serious horsepower.
Conclusion
Because of the length of this article, there are a number of topics I've glossed or skipped over entirely. Probably the most important is the process of creating and delivering dynamic content to WAP user agents. This requires a good understanding of HTTP headers and CGI server architectures. I've also completely ignored the topic of caching, both in user agents and gateways. Proper cache management is critical for achieving reasonable performance on a wireless network.
DDJ
Listing One
<wml>
<card id="card1" >
<p>
Hello WAP World.
</p>
</card><
/wml>
Listing Two
<card>
<onevent type="onenterforward">
<refresh>
<setvar name="var1" value="Hello " />
<setvar name="var2" value="World." />
</refresh>
</onevent>
<p>
$(var1) $(var2)
</p><
/card>
Listing Three
<card>
<do type="accept">
<go href="./nextdeck.wml" />
</do>
<p>
Press Go to get a new deck.
</p><
/card>
Listing Four
<card>
<p>
<anchor>
Press Go to get a new deck.
<go href="nextdeck.wml" />
</anchor>
</p><
/card>
Listing Five
<card>
<do type="accept" label="Go" >
<go href="$(url)" method="post" >
<postfield name="var" value="$(value)" />
</go>
</do>
<p>
Enter a URL:<br/>
<input name="url" value="nextdeck.wml" /><br/>
Enter some data:<br/>
<input name="value" />
</p><
/card>
Listing Six
extern function hello () {
Dialogs.alert ( "Hello WMLScript World." );
}
Listing Seven
<card id="hello">
<onevent type="onenterforward">
<go href="hellowmls.wmls#hello()" />
</onevent><
/card>
Copyright © 1999, Dr. Dobb's Journal
