The Wireless Application Protocol (WAP) and implementing WAP in gaming

URL: http://www.wapforum.org
The Wireless Application Protocol (WAP) is a set of standards based on the Internet Protocols (IP) and the Extensible Markup Language (XML). WAP is an open and global standard for wireless applications. WAP was designed to operate seamlessly over CMDA, CDPD, and all other major wireless network types.
WAP's primary technology—the Wireless Markup Language (WML)—is based on HDML and was developed by Unwired Planet (which became Phone.com and is now Openwave), Motorola, Nokia, and Ericsson. These companies and others have formed an open organization devoted to WAP called the WAP Forum.
WAP content is accessed using standard Uniform Resource Locators (URLs), just as Web pages are. Pages written in WML have the .WML extension, just as most HTML pages end with .HTML.
Most modern mobile phones support some version of WAP. Many phones come preloaded
with the Openwave (Phone.com) Mobile Browser. The following section is not intended to be a full WAP primer. Rather, it will provide a brief overview of most WML tags and attributes, allowing you to create simple WAP structures in which to support your Micro Java games.
The WAP Protocol Stack
The protocols that make up WAP are based strongly on the Internet Protocols. The Web protocol stack includes old favorites such as HTML, HTTP, SSL, UDP/IP, and TCP/IP. This is a very robust and efficient suite of protocols, to be sure. However, the Web stack itself is quite large, and provides more functionality than most mobile phones need.
Because of this, a special WAP protocol stack was created. The stack includes, in order
• An application layer—The actual application used to display things to the user. This uses the Wireless Application Environment (WAE) displaying pages written with WML.
• A session layer—How connections are made. This layer uses the Wireless Session Protocol (WSP).
• A transaction layer—How data is divided. This layer uses the Wireless Transaction Protocol (WTP).
• A security layer—Encrypts the data. This layer uses Wireless Transport Layer Security (WTLS).
• A datagram layer—How the data is packaged and sent across the network. This is done
using the Wireless Datagram Protocol (WDP). The WDP can use different bearers, such
as CDPD, SMS, and so on.
Wireless carriers and cell phone manufacturers need to worry about implementing all these
protocols properly. Lowly game developers need only focus on writing the actual applications
using WML and WMLScript.
WAP Architecture
A WAP browser works very similarly to a Web browser, and a WAP server works similarly to a Web server. As in the Web world, the client requests a page from a server. The server then responds with the page data. There is no continual connection. If the server has more data to send to the client, then another client request must first be made.
In the world of WAP, a phone is known as a user agent. In fact, most WAP pages come to the phone from a standard Web server, directed through a special server called a WAP gateway.

works as follows:
1. A mobile phone user asks for a specific URL.
2. The request is sent over a proprietary wireless network, using WAP protocols, to a gateway machine.
3. The gateway translates the request to HTTP and sends it to a standard Web server.
4. The Web server will grab or dynamically generate the content (usually a WML document) and send this response back to the gateway.
5. The gateway encodes the WML and WMLScript into byte code and sends it to the phone.
6. The phone processes the byte code and displays the first card to the user.

The Wireless Markup Language (WML)
The Wireless Markup Language is very similar, in concept, to the Hyper Text Markup Language
(HTML) used to create most Web pages. Obviously, a rich HTML Web site with snazzy animations, tons of colors, and fantastic music won't look quite so snazzy on a postage-stampsized black and white screen. WML was built to address the typical mobile phone's limitations:
• The screen is 20 or fewer characters across, and only three to six lines tall. As such, WML needs only very basic text formatting and layout abilities.
• Most phones have only a small amount of memory and rudimentary processor power. As such, the object model of how WMLScript can dynamically access a WML deck is vastly simplified.
• Typically, a phone only has only a numeric keypad. As such, all of WML's input methods are basic edit fields and option selections. Nothing that might rely on mouse or keyboard input is supported.
• Data transfer rates are extremely slow, which means latency is extremely high. As such, WML applications are not sent as separate pages requiring many separate requests and responses, but as one big deck separated into individual cards.
• Bandwidth, or the amount of data that can be uploaded or downloaded per second, is extremely limited. WML and WMLScript are usually compressed into tight runnable byte code, which means that a heavy WML file doesn't need to be parsed on the phone, but rather on the gateway server.
WML is currently released as version 1.3. However, most phones only support WML 1.1. The WML tags in this blog should work with WAP 1.1 browsers and up.

WML Basics
Every WML file must begin with a standard prologue, including an XML header and a document
definition tag:


"http://www.wapforum.org/DTD/wml_1.1.xml">
WARNING
Since WML is based on XML, it is case sensitive—every tag and attribute should be in
lowercase. Also, tags cannot be nested incorrectly. For example, the following line is illegal
and will generate errors:
Hello!

The rest of the code must be surrounded by and .
A Game of Cards and Decks In the world of the desktop Internet browser, there are Web sites and Web pages. On a mobile phone, there are decks and cards.
A card is a screen that a user sees and can interact with. There can only be one card visible at a time. There is no notion of various windows that can be moved around, minimized, or maximized. Each card is surrounded by the tags:

and
The id attribute refers to the name of the card. This name must be a single word with no spaces or wacky characters. Every card in a deck must have a different id name.
The title attribute is a short description of the card, and is usually displayed at the top of the mobile phone's screen. Each card must have at least one paragraph in it, as designated by the tags and
.Some WAP phones do not show the card title at all, so don't rely on it being there. A deck is a set of cards. When your mobile phone downloads a WML file, it is getting an entire deck. The first card in the deck is activated. Later cards can then be activated using their id as the user selects various menu or other options.
A deck must begin with

and end with

So, taking all these rules together, the world's simplest WML file might look like this:


"http://www.wapforum.org/DTD/wml_1.1.xml">




Wow! This is one of the world's most simple WML files!




Wow! The second card!

Anchors Away
You can use anchors to go from one card to another, or to actually load a new deck from the
server. Anchor text or images will be hypertext, and will usually appear underlined. Players will
be allowed to select this hypertext using the up/down/left/right keys on their mobile phones.
The tag contains inner tags:
• Click Here— Loads a new WML deck and
brings up a specific card. If you omit the # symbol in the href attribute, then the first
card in the given deck will be brought up.

Likewise, if you omit the deck name completely and only use the # symbol, then you can
jump to a card within the currently active deck.
The tag is similar to the hyperlink tag in HTML. It allows you to send a
request to the server, asking for a specific URL.
Note that the tag can also contain a special tag called that allows
you to post parameters to the Web server:

• — Goes to the previously loaded WML card.
• Click Here— Reloads the current card.
• — No operation. This does nothing at all. This is usually done to show a
command that is currently disabled.
So, to switch to a new card in a deck

Select here to bring up a new card
from the current deck


To switch to a new deck entirely

Select here to bring up a new deck


Most requests will return a new WML document. The WML document can be static, or created
dynamically by a CGI script, Java servlet, JSP, ASP, or other server-side technology.
For example, a request to a Java servlet might look like this:

The tag allows you to change certain variables and then reload the same or a
different card:

Select here to refresh variable x
85




Note that you can also use the tag, similar to HTML, which is the same as using the
and combination:Select here to bring up a new card.
Or
Select here to bring up a new deck.

Text Formatting Tags
Since a mobile phone doesn't have a lot of room or a wide variety of colors and fonts, only a few
tags are actually supported in WML.
The most popular tags for formatting text include the following:
•
— Used to add a line break. Because this tag stands alone and has no closing tag,
it must contain a slash.
•
My Paragraph
— Separates chunks of text into paragraphs.
• I am mighty— Used to make text stronger (usually the same as
making text bold).
• Emphasize me, baby!— Used to emphasize text (usually the same as
italicizing).
• I am bold— Used to make text bold.
• I am italic— Used to make text italicized.
• I am underlined— Used to underline text.
• Wee little me— Makes text smaller.
• Big bad me— Makes text larger.
So the following code might appear as in Figure 4.4:


"http://www.wapforum.org/DTD/wml_1.1.xml">



Hello

I'm bold

I'm italic

I'm underlined

I'm big

I'm small


Be aware that some phones do not support many of these tags. For example, an older WAP
browser may only allow paragraph breaks and line breaks, but no bolding, italicizing, or
underlining.
NOTE
You can add a comment to a WML file using the same comment tags that work in HTML:

Tables
Although using tables is discouraged because there's usually not enough room for them, standard
table tags are supported similarly to HTML.
You surround your table with

and
You can create rows and columns using the following tags:
• Row— Surrounds a given row of text.
87
• Column— Creates a given column.
The following code creates a small two-by-two column table:

Top Left	Top Right
Bottom Left	Bottom Right

For example:
Top Left Top Right
Bottom Left Bottom Right
User Input Tags
The user input controls will look different on every phone you use. You can use many of the same input elements that you'll find in an HTML form.
Input Fields
Typically, a user input field is an empty box in which a person can type in a number, word, or phrase. Because typing on a cell phone is usually an arduous task, many phones will bring up a special screen when an input field is selected.
You can create a standard input field named "test" as follows:

An input field possesses several attributes:
• name— The name of the field, which will become a variable name you can access later or
send to the server.
• emptyok— Set to true if the text field can be left blank. By default this is set to false.
• maxlength— The maximum length of characters that a user can enter.
• size— The width of the field, indicated in number of characters.
• title— Sets a title for the input field. This will be displayed on some phones when the
user is inside this field.
• type— Sets the type of input field. By default this is text, but you might also have a
password type of field. In password fields, anything the user enters usually appears as
an asterisk, for added security.
• value— Sets the default value for this input field.
• format— The type of data that can be entered in the field. The default is *M. The types
are as follows:
A—Uppercase alphabetic characters
a—Lowercase alphabetic characters
88
N—Numeric characters
X—Uppercase characters of any type
x—Lowercase characters of any type
M—All characters
Precede any of the these types with an asterisk to indicate that any number of characters can be entered.
Precede any of the these types with a specific number from 1 to 9 to specify that the user must enter a specific amount of the given character type.
So, to create a 10 character-wide input field that must be numeric and can contain only 10 characters, you would use the following:

Option Groups
You can create a pull-down option list by surrounding the list with the and tags, and surrounding each individual option using the and tags:

First Option
Second Option

Each option tag can take several attributes, such as:
• value— Sets the value for the option that will be dumped into the variable, should the
option be selected.
• onpick— This attribute takes a URL or anchor card name as a parameter. If the given
option is selected, then the given URL is requested.
Check Boxes and Radio Buttons
To create check boxes, you can use the First ChoiceSecond ChoiceThird ChoiceField Sets
Finally, you can visibly group the buttons together into a sort of set. To do so, simply surround elements inside your user input forms with

and

This can help group check boxes or radio buttons.

"http://www.wapforum.org/DTD/wml_1.1.xml">




Name:

AB

The Tag
The tag lets the user perform some sort of global command or other task on the current card.The command will usually appear in the soft-key menus at the bottom of the mobile phone's display. Most phones allow for two soft keys. If you create more than two options, then one of the soft-key commands will usually become Menu, which will lead to a special menu of
additional choices. The label attribute is the label for the command that will be shown to the
user.
The name attribute creates a variable name for the element.
The type attribute lets you choose what sort of command you wish to create. Various browsers
will display these commands in different ways. Usually, up to two commands can be shown on the
screen, mapped to the mobile phone's two command buttons. Other phones may display the
commands in a nested menu, or along with a special icon.
The following are some valid command types:
• accept— Acknowledgement of a message or event.
• prev— Navigate back to a previous deck.
• help— Help about this card.
• reset— Reset the WAP browser.
• options— A selection from a list of options.
• delete— Delete an item or choice.
• unknown— A special type, not one of the preceding types.
To perform an action, simply surround it with the and tags. To jump to a card in the
current deck named card2, you could use



The following command will add a back command to the current card, allowing you to go to the
previously loaded card:



Variables
WML files are capable of keeping track of and changing simple variables. This lets your WML
application keep information between cards.
To explicitly set the variable i to 10, use the tag:

Whenever you create an input element, the results are stored as variables. Simply use the name of
the element preceded by a dollar sign. You can surround the variable name by parentheses to
separate it from any other text.
So, to create a small application that asks the user for their name and then displays it, you could
use the following code:


"http://www.wapforum.org/DTD/wml_1.1.xml">
92









Your name is: $(myname)



The name is input in the first card (with the id of input). Then the card with the id result is called, as soon as the OK! button is pressed. The result is then displayed. Images
As with HTML, WML does support an tag:
The src attribute points to an image in the WBMP format. This format is a special, tiny blackand-white bitmap created to fit snugly on wireless devices.

Timers
When using WAP, the connection between a mobile phone and the server does not remain
persistent between requests. If the server needs to send an update to the client, it has no way to do
so until the client explicitly requests a new deck.
Many games and other time-sensitive applications will need to constantly poll the server, asking
for any new updates. This can be done using a simple WML timer.
Set the ontimer attribute of the tag to point to the WML page you wish to update. You
can then use the tag to create the countdown, setting the value in tenths
of a second.
To refresh the WML document every three seconds, simply use the following:



Some Message


WMLScript
If you've followed along so far, you've noticed that WML has very limited interactivity on the
client side. Really, all you can do is display simple text and images, collect a little information via
user input forms, and send it all to the server to process.
Just as HTML has JavaScript (based on the ECMAScript standard), some WML browsers support
a special client-side scripting language called WMLScript. WMLScript is a much simpler subset
of ECMAScript. In addition, WMLScript is compiled into bytecode by the WAP gateway before
being sent down to the phone.
WARNING
Many WAP Browsers do not support WMLScript. Be sure to research your target platform
before relying on any client-side scripting. Check out the excellent table at
http://www.allnetdevices.com/faq/useragents.php3 to determine what version of WAP your
target device supports.
WMLScript is used, for the most part, to verify user input before wasting precious time sending it
to the server. For example, if you ask your game player for his age, a simple WMLScript can be
sure the input is indeed a number, isn't negative, and isn't over 200. If the results aren't valid, a
dialog box can pop up telling the player to enter a new number.
In addition, some versions of WMLScript allow you to access special features of the user agent,
such as the following:
• Dialog boxes to alert the user of something or to request input
• Make phone calls
• Access the SIM card
• Access or change the address book
• Configure the phone preferences
94
Accessing WML Script
WMLScript files are stored separately from WML files. They usually have the .wmls extension.
You can access a WMLScript file's WML the same way you would request any other document:

You can access specific external functions within WMLScript using the hash symbol. This allows
you to pass in variables. For example, the following file requests a variable called myvar and then
passes it to the process() function within a WMLScript file:


"http://www.wapforum.org/DTD/wml_1.1.xml">






Type something here:


WMLScript Example
You can make a simple guessing game entirely on the client side using WMLScript. For example,
you can create a dialog box that asks the user for a random number.
A function will pick a random number and compare it the user's guess, and show a card indicating
whether the user was correct.
The following is the code for GuessNumber.wml:


"http://www.WAPforum.org/DTD/wml_1.1.xml">



Guessing a Random Number...






You were right!
Number was $(randresult)


95


Sorry. Wrong!
Number was $(randresult)


Here's the code for RandomGuess.wmls:
extern function guessrandom()
{
// Request a number, 0 by default
var thenum = 0;
// Loop until a valid number is picked.
do
{
var r = Dialogs.prompt("Pick a number between 1 and 10", "0");
thenum = Lang.parseInt(r);
}
while (thenum < 1 || thenum > 10)
var randnum = Lang.random(10)+1;
// set the randresult variable
WMLBrowser.setVar("randresult", randnum);
if (randnum == thenum)
WMLBrowser.go("GuessNumber.wml#right");
else
WMLBrowser.go("GuessNumber.wml#wrong");
} ;
The guessrandom() function is preceded by the extern modifier, meaning that it can be
accessed by external WML or WMLScript documents.
Note that the variable randnum is a script variable, and can only be set and accessed within this
WMLScript function.
The randresult variable, however, is set using WMLScript's setVar() method, meaning it
will be an active browser variable—active and accessible as long as the player is visiting the
current WAP site.
Server-Side WAP
Most any Web server can serve out WML pages. You will, however, need to modify your server
using the instructions given in this section.
Server Configuration
Every response your Web server sends to a browser is tagged with a special header. One of the
most important lines of the header tells the browser what the content-type of the document is. This
content-type is expressed using a standard known as the Multipurpose Internet Mail Extension
(MIME).
96
The MIME type of HTML files, for example, is text/html. For WAP documents, you need to
add several new MIME types to allow for WML files, WML script files, compiled WML files,
and WBMP wireless bitmaps:
• text/vnd.wap.wml
• application/vnd.wap.wmlc
• text/vnd.wap.wmlscript
• application/vnd.wap.wmlscriptc
• image/vnd.wap.wbmp
Most Web servers make it easy to add new MIME types. Many servers have a
httpd.conf file in which these types can be added.
WAP and Java
Although some WAP pages will never change and can be written using a standard text editor or
HTML authoring tool, most WAP games and game tools will involve lots of dynamic information
such as game state, scores, number of users in a lobby, chat messages, and so on.
That means that the Web server will need to generate WML decks and cards on-the-fly. Serverside Java technologies, such as JavaServer Pages (JSPs) and Java Servlets, are a great way to pump out the necessary WML.
A Servlet Game Lobby For example, here's a simple servlet that can allow an unlimited number of players to chat with each other. This can lead up to a full-featured lobby where players can match up and then be joined together to play Java games.
The WAP need only call the servlet with one parameter:
mymessage
The servlet will take that message and return the last five lines of chat.
This is obviously a very simplified version of a game lobby. A real lobby would force users to log in with a password, keep track of the user's name, keep track of which chat lines each user has already seen, match players together, and kick off game sessions.
Sample
import java.io.*;
import javax.servlet.*;
import javax.servlet.http.*;
public class SimpleChatServlet extends HttpServlet {
// Store last five messages
private static String message[] = new String[5];
public void init() throws ServletException
{
// Set messages to blank for now
for (int i=0; i < 5; i++)
97
message[i] = "";
}
public void doGet(HttpServletRequest request,HttpServletResponse
response)
throws ServletException,IOException
{
// set content type as wap.wml
response.setContentType("text/vnd.wap.wml");
// create a print writer output
PrintWriter out = response.getWriter();
// get the latest message, if any
String mymsg = request.getParameter("mymessage");
// If the message isn't null, add it to the top of the queue
if (mymsg != null)
{
for (int i=4; i > 0; i—)
{
// Replace message with previous message
message[i] = message[i-1];
}
message[0] = mymsg;
}
// write the data
out.println("");
out.println("
1.1//EN\"");
out.println(" \"http://www.wapforum.org/DTD/wml_1.1.xml\">");
out.println("");
out.println("");
// Send any new messages back to this servlet
out.println("");
out.println(" method=\"get\">");
out.println(" value=\"$mymsg\"/>");
out.println(" ");
out.println("");
out.println("
");
// print out the last five messages
for (int i=0; i < 5; i++)
{
out.println(message[i]+"
");
}
out.println("
");
// Request a new chat message
out.println("");
out.println("Chat:
name=\"mymsg\"/>");
out.println("
");
out.println("
");
out.println("");
out.println("");
}
}Any WML card that requests this servlet will send its own chat message and retrieve the last five
messages that have been sent. Effectively, this servlet will pump out a WML file that looks like
the following:


"http://www.wapforum.org/DTD/wml_1.1.xml">







Message 1

Message 2

Message 3

Message 4

Message 5



Chat:



99

Using JavaServer Pages (JSPs)
Similarly, JavaServer Pages (JSPs) can be used to dynamically create cards, using variables that
can be created programmatically.
Here's a simple example:


"http://www.wapforum.org/DTD/wml_1.1.xml">
<%
response.setContentType("text/vnd.wap.wml");
out.println("");
out.println("");
out.println("

");
out.println("Date: "+ new java.util.Date());
out.println("

");
out.println("");
out.println("");
%>
Development Environment
To develop WAP applications, you can use a number of different environments. Every major cell phone manufacturer offers a software development kit that allows you to create and emulate their precise WAP environment.