Académique Documents
Professionnel Documents
Culture Documents
Copyright
Copyright © (c) 2001 3G LAB Limited. ALL RIGHTS RESERVED.
The 3G LAB logo and Alligata logo are copyright of 3G LAB Limited in the US and other countries. In addition no part of any documentation
contained in or on this packaging may be reproduced in any form (whether by electronic means, by photocopying or in any permanent or
temporary form) without the express written permission of 3G LAB Limited or except as in accordance with the provisions of the Copyright
Designs and Patents Act 1988 as amended or superseded from time to time.
Linux is a registered trademark of Linus Torvalds.
Solaris is a registered trademark of Sun Microsystems, Inc.
UltraSPARC is a registered trademark of SPARC International, Inc.
Wavecom and WM02 are registered trademarks of Wavecom S.A.
Nokia and Premicell are registered trademarks of Nokia Corporation.
Siemens and M20T are registered trademarks of Siemens AG.
Openwave is a trademark of Openwave Systems, Inc.
3G LAB recognises that other trademarks displayed are the property of their respective holders.
Revision History
Revision cvs-20100318 2010.03.20
Table of Contents
I. Part One: Getting Started ....................................................................................................................vi
1. 1 Welcome......................................................................................................................................1
1.1 The Alligata Server Package ..............................................................................................1
2. 2 System Requirements..................................................................................................................3
2.1 Linux Version .....................................................................................................................3
Minimum System Requirements ....................................................................................3
Optional Hardware Accessories......................................................................................3
2.2 Solaris Version....................................................................................................................3
Minimum System Requirements ....................................................................................3
Optional Hardware Accessories......................................................................................4
2.3 Optional Software Included with the Alligata Server ........................................................4
3. 3 About the Alligata Server............................................................................................................5
3.1 What is the Alligata Server?...............................................................................................5
3.2 The Alligata Server, WAP and SMS...................................................................................5
3.3 Inside the Alligata Server ...................................................................................................6
3.3.1 Program States .......................................................................................................6
3.3.2 Bearer Box .............................................................................................................7
3.3.3 Communication Between the Boxes......................................................................8
3.3.4 WAP Box ...............................................................................................................8
3.3.5 SMS Box................................................................................................................8
4. 4 Installation from a Graphical User Interface.............................................................................10
5. 5 Installation from the Command Line ........................................................................................15
6. 6 Installing Multiple WAP and SMS Boxes.................................................................................19
II. Part Two: Using the Alligata Server .................................................................................................21
7. 7 Introduction to Part Two ...........................................................................................................22
8. 8 Running the Alligata Server......................................................................................................23
8.1 Starting the Alligata Server ..............................................................................................23
8.1.1 Method 1 ..............................................................................................................23
8.1.2 Method 2 ..............................................................................................................23
Linux users ..........................................................................................................23
Solaris users.........................................................................................................24
8.1.3 Method 3 ..............................................................................................................24
Command Line Options ......................................................................................25
8.2 Administering the Alligata Server....................................................................................26
8.2.1 Administering the Alligata Server from the Command Line...............................26
8.2.2 Administering the Alligata Server Using HTTP ........................................26
8.2.3 Monitoring the Alligata Server Using less ..............................................27
Shutting down an Alligata Server box....................................................................................27
8.3.1 Method 1 ..............................................................................................................27
8.3.2 Method 2 ..............................................................................................................28
9. 9 Configuring the Alligata Server ................................................................................................29
9.1 Core Configuration Variables (Core group) .....................................................................32
9.2 WAP Configuration Variables (WAP Box group).............................................................36
9.3 SMS Configuration Variables (SMS Box, SMSC, SMS Service and Send SMS User
groups) ..........................................................................................................................38
iii
9.3.1 SMS Box group ...................................................................................................38
9.3.2 SMSC group ........................................................................................................40
9.3.3 SMS Service Group .............................................................................................44
9.3.4 Send SMS User Group.........................................................................................49
9.4 Over-the-air Configuration Variables (OTA Configuration Group)..................................51
10. 10 Creating WAP Documents ....................................................................................................53
11. 11 Introduction to WML ............................................................................................................54
11.1 Content and Tags ............................................................................................................54
11.2 Elements and Attributes..................................................................................................55
11.3 Cards and Decks .............................................................................................................55
11.4 XML Validation Tags .....................................................................................................56
11.5 The wml Element ...........................................................................................................56
11.6 Paragraphs ......................................................................................................................56
11.7 Hyperlinks ......................................................................................................................57
11.8 Tasks (do Element) .........................................................................................................58
11.9 Events .............................................................................................................................59
11.10 Templates......................................................................................................................60
11.11 Variables .......................................................................................................................62
11.12 Timers ...........................................................................................................................64
11.13 Images...........................................................................................................................64
12. 12 Example WAP Sites ..............................................................................................................66
12.1 Example Site 1: Static WML (Simple)...........................................................................67
12.2 Example Site 2: Static WML (Complex) .......................................................................67
12.3 Example Site 3: Perl System Resource Monitor ............................................................72
12.4 Example Site 4: PHP System Resource Monitor ...........................................................73
12.5 Example Site 5: 'PAT' PHP Mail ....................................................................................76
13. 13 SMS Messaging ....................................................................................................................79
13.1 Implementing SMS Keyword Services ..........................................................................79
13.1.1 SMS Service Parameters....................................................................................81
13.2 Sending SMS Messages Using HTTP............................................................................82
13.2.1 User Data Headers (udh parameter) ..................................................................82
13.2.2 smsc Parameter..................................................................................................82
13.2.3 SMS Messaging Using HTML Forms ...............................................................83
13.3 Over-the-air (OTA) Configuration of WAP Client Devices Using SMS ........................84
A. Appendix: Troubleshooting Guide ....................................................................................................86
iv
List of Tables
8-1. Figure 8.1: Alligata Server command line options.............................................................................25
8-2. Figure 8.2: Alligata Server command line administration commands ...............................................26
8-3. Figure 8.3: Alligata Server HTTP administration commands............................................................27
9-1. Escape characters ...............................................................................................................................31
9-2. Figure 9.2: Summary of Alligata Server configuration groups ..........................................................32
9-3. Figure 9.3: SMSC group protocol-specific variables .........................................................................40
9-4. Currently supported modems .............................................................................................................44
9-5. Possible parameters in the URL template ..........................................................................................45
11-1. Figure 11.2: WML event types.........................................................................................................60
11-2. Figure 11.6: Image attributes............................................................................................................64
12-1. Figure 12.1: Example WAP phone configuration.............................................................................66
12-2. Figure 12.14: Summary of PAT files ................................................................................................78
v
I. Part One: Getting Started
Chapter 1. 1 Welcome
Welcome to the Alligata Server User Manual. This manual is in two parts:
• This part, Getting Started, provides an overview of the Alligata Server, and explains how to install the
program. It covers the following topics:
• How the Alligata Server fits into the architecture of the Wireless Application Protocol (WAP), the
Short Message Service (SMS) and the World Wide Web
• The internal functioning of the Alligata Server
• The hardware and software you need to run the Alligata Server
• How to install the Alligata Server from a Linux/Solaris windowing system, or from the
Linux/Solaris command prompt
• How to spread an installation of the Alligata Server across several computers in order to maximise
processing capacity
• The second part, Using the Alligata Server, is a detailed guide to running, configuring and using the
Alligata Server. It covers the following topics:
• How to start, stop and administer the Alligata Server
• How to change the Alligata Server's configuration settings
• How to view the example WAP sites provided with the Alligata Server
• How to create WAP sites using Wireless Markup Language (WML)
• How to create dynamic WAP sites using the Perl scripting language
• How to create dynamic WAP sites using the PHP scripting language
• How to use the Alligata Server's SMS features to deliver World Wide Web and other content to
mobile phones
• How to use the Alligata Server to send SMS messages from a computer workstation
• How to configure a mobile phone for a WAP service 'over the air' using the Alligata Server's SMS
features
• An installation CD-ROM from which you can install the Alligata Server, some example WAP sites,
the Apache Web server, the PHP scripting language and some modules for the Perl scripting language
that are useful for developing Mobile Internet sites.
• A booklet, Your Pocket Guide to the Mobile Internet.
1
Chapter 1. 1 Welcome
2
Chapter 2. 2 System Requirements
There are two versions of the Alligata Server, one for the Linux operating system and one for the Sun
Solaris operating system.
Software:
• Red Hat Linux version 6.0, 6.1 or 6.2 or Mandrake Linux version 7.0 or 7.1
(The Alligata Server may run on some other distributions of Linux)
• Perl version 5.0 or higher. Perl is standard in most Linux distributions. If you do not have Perl
installed, download it from www.perl.org (http://www.perl.org)
3
Chapter 2. 2 System Requirements
Software:
4
Chapter 3. 3 About the Alligata Server
5
Chapter 3. 3 About the Alligata Server
A signal sent by a mobile device is picked up by one of a network operator's base stations. It is then
routed through the mobile network to the Alligata Server using User Datagram Protocol (UDP). If it is an
SMS message, it is first sent to the network's SMS Centre (SMSC). The SMSC's main job is to hold
pending SMS messages for recipients whose phones are turned off or otherwise inaccessible.
Once the Alligata Server has received a WAP data packet from a client and decompressed it, it uses
Hypertext Transfer Protocol (HTTP) to retrieve data from the relevant content server on the Mobile
Internet.
On receiving an SMS message, the Alligata Server scans it for keywords and parameters listed in its
6
Chapter 3. 3 About the Alligata Server
configuration file (see Section 13.1), then sends an automatic reply to the client device depending on
which keyword and parameters it encountered. This reply can consist of static text, or it can be retrieved
from a local file, a WAP site or a World Wide Web page.
The Alligata Server's reply to an SMS message is another SMS message. This means that, in principle, it
has to be sent to the relevant network operator's SMSC in order to be routed to the recipient device (or
stored if the recipient device is not accessible). Most network operators charge a fee for terrestrial access
to their SMSCs, but the Alligata Server allows you to circumvent this if you own a GSM modem, or a
mobile phone that includes a GSM modem such as the Nokia 7110 or 6210. The Alligata Server can use
the modem to send SMS messages directly over the airwaves. This way, you will get charged the same
rates as mobile phone users for sending SMS messages from your computer workstation. See Section
9.3.2 for details of how to send messages using a GSM modem.
• Running. The Alligata Server accepts, processes and sends files and messages normally.
• Suspended. The Alligata Server does not accept any new WAP requests or messages from SMSCs. The
Bearer Box does not allow new WAP or SMS Boxes to connect to it. No messages or files are sent out.
• Isolated. The Alligata Server does not accept any new WAP requests or messages from SMSCs.
However, it continues processing messages already in its system, and accepts SMS messages sent via
HTTP (see Section 13.2).
7
Chapter 3. 3 About the Alligata Server
• Shutdown. The Alligata Server performs the shutdown procedure. New WAP requests and SMS
messages are refused. Requests already being processed are carried through. When all queues in the
boxes have been processed, the Alligata Server closes down.
You can change the state of the Alligata Server using HTTP administration commands. See Section 8.2.2.
There follows a more detailed look at the components of the Alligata Server. You do not need to know
this information to use the Alligata Server, but you may find it of interest.
8
Chapter 3. 3 About the Alligata Server
its incorporation into the Alligata Server means that the Bearer Box, WAP Boxes and SMS Boxes can be
run on separate computers, if required. The advantages of this set-up are clear: it means that, outside the
Bearer Box, groups of packets can be processed simultaneously, and therefore the Alligata Server can
process high volumes of messages very quickly.
If the TCP stream between the Bearer Box and a WAP or SMS Box fails for any reason, the Bearer Box
notices this and removes the disconnected box from its list of available boxes. Any packets from phones
that were routed to this box are then treated as packets from new clients, and redirected by the Bearer
Box to an alternative WAP Box. When a WAP Box receives a message from a new client that it identifies
as being from the middle of a session, it sends an error message to the client device.
A WAP or SMS Box can also go 'catatonic': its TCP stream to the Bearer Box is still running, but it is not
responding to any messages. So that the Bearer Box knows when this has happened, WAP and SMS
Boxes send 'heartbeat' packets at regular intervals, effectively telling the Bearer Box that they are running
and functioning normally. If the Bearer Box stops receiving heartbeat messages from another box, it
assumes there is a problem even though the TCP stream may still be running, and removes the box from
its list. When the ailing box recovers and announces its presence, the Bearer Box reopens the connection.
9
Chapter 3. 3 About the Alligata Server
SMS message or messages, and sends the SMS message(s) to the Bearer Box via the TCP stream. The
Bearer Box sends the message back to the client device via an SMSC.
Other services the SMS Box can provide include sending a fixed text message or the content of a local
file in response to a keyword. For more information, see Sections 9.3 and 13.1.
The SMS Box also listens for SMS messages arriving via HTTP from computer workstations. It converts
these messages from HTTP into true SMS format, and sends them on to the Bearer Box to be conveyed to
mobile devices. See Section 13.2 for details of how to send SMS messages from a computer workstation.
10
Chapter 4. 4 Installation from a Graphical User
Interface
If your Linux or Solaris system includes a graphical user interface, the installation program
automatically installs the Alligata Server using the graphical procedure described in this section.
To install the Alligata Server from a Linux/Solaris graphical user interface:
(In Linux the path of the CD-ROM mount point is usually /mnt/cdrom, in Solaris it is usually
/cdrom/cdrom0 or something similar.) For example:
mount /mnt/cdrom
Press ENTER.
If your version of Linux or Solaris automounts CD-ROMs, you can ignore this step.
6. Change directory to your system's CD-ROM mount point. For example, Linux users should type
cd /mnt/cdrom
11
Chapter 4. 4 Installation from a Graphical User Interface
12
Chapter 4. 4 Installation from a Graphical User Interface
13
Chapter 4. 4 Installation from a Graphical User Interface
Binary directory
Shows the directory into which the Alligata Server's binary files are installed. Defaults to
/usr/bin, and cannot be changed.
14
Chapter 4. 4 Installation from a Graphical User Interface
PHP language
Installs the PHP scripting language. PHP is used by two of the Alligata Server example WAP
sites. It can be very useful for developing Web and WAP applications.
In the Solaris installation, this option includes the PHP IMAP module (see below).
15
Chapter 4. 4 Installation from a Graphical User Interface
16
Chapter 4. 4 Installation from a Graphical User Interface
17
Chapter 5. 5 Installation from the Command
Line
If your Linux or Solaris system does not include a graphical user interface, the installation program will
install the Alligata Server using the command line procedure described in this section.
To install the Alligata Server from the command line:
(In Linux the path of the CD-ROM mount point is usually /mnt/cdrom, in Solaris it is usually
/cdrom/cdrom0 or something similar.) For example:
mount /mnt/cdrom
Press ENTER.
If your version of Linux or Solaris automounts CD-ROMs, you can ignore this step.
5. Change directory to your system's CD-ROM mount point. For example, Linux users should type
cd /mnt/cdrom
18
Chapter 5. 5 Installation from the Command Line
Y installs the Alligata Server on the current computer, including the Bearer Box, one WAP Box
and one SMS Box. If you want to install extra WAP and SMS Boxes on other computers, see
Section 6.
Y causes the WAP Box to be started automatically every time the computer is booted.
Y installs the Alligata Server example WAP sites. In Linux, these are installed into
/home/httpd/alligata/wml. In Solaris 7, they are installed into
/usr/local/apache/alligata/wml. In Solaris 8, they are installed into
/etc/apache/alligata/wml.
Section 12 provides a guide to viewing, using and understanding the example sites.
Y installs the Apache Web server. You will need Apache to view the example sites.
19
Chapter 5. 5 Installation from the Command Line
Install Development files for the Apache Web server? [N/y/?] (Linux only)
Y installs the Apache development package. You will need this package if you plan to extend
Apache, for example to write a new module.
If the computer already contains an installation of Apache, the Alligata Server installation
program updates the Apache configuration for WML and WBMP file formats.
Y installs the PHP scripting language. PHP is used by two of the Alligata Server example WAP
sites. It can be very useful for developing Web and WAP applications.
In the Solaris installation, this option includes the PHP IMAP module (see below).
Install IMAP module for the PHP language? [N/y/?] (Linux only)
Y installs the IMAP PHP module. This module is used in the example WAP site PAT for
liaising with your e-mail server.
Y installs the Common Gateway Interface (CGI) Perl module, version 2.69. This module
facilitates the output of Web files from Perl scripts. It is needed to view the Alligata Server's
Perl example site. (The CGI modules supplied with most Linux distributions are too old and
will not work with the example Perl site.)
Y installs the HTML Perl module. This module is needed to view the Alligata Server's Perl
example site.
Y installs the HTML tables Perl module. This module is needed to view the Alligata Server's
Perl example site.
11. The following messages (or equivalents) will be displayed on the screen:
Installing to /usr/share/alligata
20
Chapter 5. 5 Installation from the Command Line
13. To start the Alligata Server, follow the instructions in Section 8.1.
21
Chapter 6. 6 Installing Multiple WAP and SMS
Boxes
The Alligata Server installation program installs a Bearer Box, a WAP Box and an SMS Box onto a
personal computer running Linux or Solaris.
The following instructions assume you have already installed the Alligata Server on a personal computer
running Linux or Solaris ('Computer A'). If you have not yet installed the Alligata Server, please follow
the instructions in Section 4 for installation from a graphical user interface, or Section 5 for installation
from the command line.
You can add any number of extra WAP and SMS Boxes to an installation of the Alligata Server.
To add a WAP Box to an installation of the Alligata Server:
1. Connect a computer running Linux or Solaris ('Computer B') to Computer A using TCP/IP.
2. Install a complete copy of the Alligata Server onto Computer B as described in Sections 4 and 5.
3. On Computer B, open the configuration file /etc/alligata.conf in a text editor such as vi or
Emacs.
About the configuration file: the Alligata Server configuration is a list of variables divided into
groups. Each group begins with the line
group = x
where x is a group identifier. A blank line signifies the end of a group. (Full instructions for
configuring the Alligata Server are provided in Section 9.)
4. In the configuration group beginning with the line
group = wapbox
, change the value of the variable
bearerbox-host
to the IP address or URL of the computer hosting the Bearer Box (that is, computer A). For example:
bearerbox-host = 10.0.0.1
5. Repeat steps 1-4 on a new computer for each WAP Box you want to add.
1. Connect a computer running Linux or Solaris ('Computer C') to Computer A using TCP/IP.
2. Install a complete copy of the Alligata Server onto Computer C as described in Sections 4 and 5.
3. On Computer C, open the configuration file /etc/alligata.conf in a text editor such as vi or
Emacs.
About the configuration file: the Alligata Server configuration is a list of variables divided into
groups. Each group begins with the line where x is a group identifier. A blank line signifies the end
of a group. (Full instructions for configuring the Alligata Server are provided in Section 9.)
group = x
22
Chapter 6. 6 Installing Multiple WAP and SMS Boxes
, change the value of the variable bearerbox-host to the IP address or URL of the computer hosting
the Bearer Box (that is, computer A). For example:
bearerbox-host = 10.0.0.1
5. Repeat steps 1-4 on a new computer for each SMS Box you want to add.
23
II. Part Two: Using the Alligata
Server
Chapter 7. 7 Introduction to Part Two
Welcome to Part Two of the Alligata Server User Manual, Using the Alligata Server. This part of the
user manual explains how to:
25
Chapter 8. 8 Running the Alligata Server
Note: to run an Alligata Server command line command, you must be logged in as root. Therefore,
before using any of the command line commands in this section, change to root as follows:
8.1.1 Method 1
If, when you installed the Alligata Server, you selected 'Start the Bearer Box at boot', 'Start the WAP Box
at boot' or 'Start the SMS Box at boot', then the relevant box will start automatically each time you boot
up the computer.
8.1.2 Method 2
Linux users
At the command prompt, type
/etc/rc.d/init.d/box start
where box is one of the strings bearerbox, wapbox or smsbox. Press ENTER.
The procedure to start the Bearer Box, WAP Box and SMS Box on a single Linux workstation is
therefore as follows:
26
Chapter 8. 8 Running the Alligata Server
/etc/rc.d/init.d/wapbox start
Solaris users
At the command prompt, type
/etc/init.d/ box start
where box is one of the strings bearerbox, wapbox or smsbox. Press ENTER.
The procedure to start the Bearer Box, WAP Box and SMS Box on a single Linux workstation is
therefore as follows:
8.1.3 Method 3
This method of starting the Alligata Server allows you to enter command line options that customise the
way each box runs. Using this method, the procedure to start up the Bearer Box, WAP Box and SMS
Box on a single workstation is as follows:
27
Chapter 8. 8 Running the Alligata Server
at the command prompt and press ENTER. You can use command line options to override some of
the settings in the configuration file. See Command Line Options below.
The Bearer Box will start up.
2. To start the WAP Box, type
wapbox
at the command prompt and press ENTER. You can use command line options to override some of
the settings in the configuration file. See Command Line Options below.
The WAP Box will start up.
3. To start the SMS Box, type
smsbox
at the command prompt and press ENTER. You can use command line options to override some of
the settings in the configuration file. See Command Line Options below.
The SMS Box will start up.
For each box, you can use a different configuration file from the default file by including the path and
name of the relevant file after the command. For example:
bearerbox /etc/alligata2.conf
For example:
bearerbox -v 2
The available command line options are shown in Figure 8.1.
-F file_name Log file name. Does not override the log file name
setting in the configuration file, but outputs to both
files.
-V number_0-4 Verbosity level for output to the log file specified
with -F. 0 provides most detail, 4 least. The default
value is 1.
-S Suspended. Starts the Alligata Server in suspended
state. See Section 3.3.1 for details.
-I Isolated. Starts the Alligata Server in isolated state.
See Section 3.3.1 for details.
28
Chapter 8. 8 Running the Alligata Server
Table 8-2. Figure 8.2: Alligata Server command line administration commands
• In the 'Location' box of a Web browser, type the command using the following syntax:
http://hostname:port/cgi-bin/command ?password=password
http://localhost:13004/cgi-bin/suspend?password=PAPaya
The port number (13004 in the example) must be the same as that defined by the admin-port variable
in the Core configuration group (see Section 9.1). The command must be one of the five HTTP
administration commands listed in Figure 8.3. The password must be that defined by the
admin-password variable in the Core configuration group. (Note that the status command requires no
password.)
To save having to type a whole URL for each command, you can create an HTML form. Here is one
for the shutdown command:
<form name="httpadmin" method="get"
action="http://localhost:13004/cgi-bin/shutdown">
29
Chapter 8. 8 Running the Alligata Server
30
Chapter 8. 8 Running the Alligata Server
8.3.1 Method 1
Linux users.
Solaris users.
replacing box with the relevant box name, bearerbox, wapbox or smsbox. For example:
/etc/rc.d/init.d/wapbox stop
8.3.2 Method 2
• Send the Alligata Server an HTTP shutdown administration command (see Section 8.2.2).
Note that this method can only be used to shut down the Bearer Box, not individual WAP and SMS
Boxes.
31
Chapter 9. 9 Configuring the Alligata Server
The Alligata Server is installed with a default configuration that allows you to use it as a WAP gateway.
If you want to customise its WAP features, or implement SMS messaging services, you need to make
changes to the configuration file.
All the configuration data for the Alligata Server is held in a single file. By default this file is called
alligata.conf and is held in the directory /etc. If you want to use a different configuration file,
specify the path and file after the relevant command when you start up a box. (To do this, you must start
the box using Method 3 - see Section 8.1.3.) For example:
bearerbox /etc/alligata2.conf
group = core
user = alligata
max-threads = 99
admin-port = 13004
wapbox-port = 13002
smsbox-port = 13005
admin-password = bar
wdp-interface-name = *
log-file = /alligata/admin/bearer.log
log-level = 0
box-deny-ip = *.*.*.*
box-allow-ip = 127.0.0.1
admin-deny-ip = 10.0.0.2
admin-allow-ip = *.*.*.*
unified-prefix = 0044,0
group = wapbox
bearerbox-host = localhost
log-file = /alligata/admin/wapbox.log
log-level = 0
group = smsbox
bearerbox-host = localhost
sendsms-port = 13013
global-sender = 123
log-file = /alligata/admin/smsbox.log
log-level = 0
group = smsc
smsc = at
modemtype = wavecom
device = /dev/ttyS2
group = sms-service
32
Chapter 9. 9 Configuring the Alligata Server
keyword = proverb
aliases = Proverb;PROVERB;potd;Potd;POTD
url = http://www.awebsite.net/potd.html
prefix = <!--beginprov-->
suffix = <!--endprov-->
split-chars = ;:.
split-suffix = -cont-
header = "Today's proverb -- "
max-messages = 10
group = sms-service
keyword = ota
# In one line!
url =
http://localhost:13013/cgi-bin/sendota?
username=otauser&password=foo&phonenumber=%p
group = otaconfig
location = http://www.asite.net
service = Company Home
ipaddress = 10.0.0.5
phonenumber = 44998123456
bearer = data
calltype = analogue
connection = cont
pppsecurity = off
authentication = normal
login = phoneuser
secret = barfoo
group = sendsms-user
username = otauser
password = foo
user-deny-ip = 10.0.0.2
user-allow-ip = *.*.*.*
max-messages = 2
concatenation = 1
group = sms-service
keyword = ota
# In one line!
url =
http://localhost:13013/cgi-bin/sendota?
username=otauser&password=foo&phonenumber=%p
group = sms-service
keyword = default
text = Sorry, the Alligata Server didn't understand your message.
group = sendsms-user
username = tester
password = foobar
max-messages = 10
33
Chapter 9. 9 Configuring the Alligata Server
split-chars = .;,
split-suffix = -cont.-
header = "Msg from tester -- "
password = foo
user-deny-ip = 10.0.0.2
user-allow-ip = *.*.*.*
max-messages = 2
concatenation = 1
The configuration file is a list of variables used by the Alligata Server, divided into groups. Each group
controls a different area of the Alligata Server's functionality. The configuration file is a plain text file, so
you can edit it in any text editor.
When editing the configuration file, note the following points:
However, quotation marks are required if the value begins or ends with a space, or if it contains special
characters.
Within quotation marks, standard C escape character syntax operates:
\a Alert
\b Backspace
\f Form feed
\n Newline
\r Carriage return
\t Horizontal tab
\t Vertical tab
\\ Backslash
\' Single quotation mark
\" Double quotation mark
\0oo Octal value (where o represents an octal digit)
34
Chapter 9. 9 Configuring the Alligata Server
• Within a group, each variable definition must be followed by a single carriage return.
• A hash # at the start of a line indicates a comment. The Alligata Server will ignore this line.
• The Alligata Server reads the configuration file when it is started up. If you make changes to the
configuration file while it is running, then you must restart the Alligata Server before they will be
implemented.
A summary of the characteristics of each configuration group is shown in Figure 9.2.
The rest of this section consists of a full list of all the variables that can be used in the Alligata Server
configuration file. Variables are arranged by group.
35
Chapter 9. 9 Configuring the Alligata Server
group = core
user = user_name
The user name under which the Alligata Server is run. The Alligata Server automatically switches
to this user name after it has started. (You must be logged in as root to start the Alligata Server
manually. See Section 8 for instructions on starting the Alligata Server.)
Setting user to root is strongly discouraged, as it could compromise the security of the system.
Example:
user = alligata
admin-port = port_number
Administration Port. Gives the port number on which the Bearer Box listens to HTTP
administration commands. It can be any value between 1024 and 65535. (It may be under 1024 if
you are running the Alligata Server as a root process, but it is not recommended that you do this.) It
is not the same as the HTTP port of the local World Wide Web server. (Required.)
Example:
admin-port = 13004
admin-password = password
Administration Password. Defines the password for HTTP administration commands (except the
status command, which does not require a password). See Section 8.2.2 for HTTP administration
instructions. (Required.)
Example:
admin-password = PAPaya
smsbox-port = port_number
SMS Box Port. Defines the port number to which SMS Boxes connect. It can be any value between
1024 and 65535. (It may be under 1024 if the user variable is set to root, but this is not advised.)
This variable is required if the Alligata Server is to handle SMS traffic. Example:
smsbox-port = 13005
wapbox-port = port_number
WAP Box Port. Defines the port number to which WAP Boxes connect. It can be any value between
1024 and 65535. (It may be under 1024 if the user variable is set to root, but this is not advised.)
This variable is required if the Alligata Server is to handle WAP traffic. Example:
wapbox-port = 13002
36
Chapter 9. 9 Configuring the Alligata Server
wdp-interface-name = IP_address
If the Alligata Server's host machine has multiple network cards, specifies the IP address of the card
from which User Datagram Protocol (UDP) WAP packets are accepted. If set to 0.0.0.0, accepts
packets from any IP address.
Example:
wdp-interface-name = 10.0.0.3
log-file = file_name
Log File. Specifies a file to which to output a log report of the Bearer Box's activity. If the specified
file already exists, new output will be added to the end of the file.
If a log file is also defined in the command line when the Bearer Box is started up, then the log
report will be output to both files (as well as to the standard output). See Section 8.1.3 for command
line options.
If log-file is not set in the configuration file, it defaults to
/var/log/alligata/bearerbox.log.
Example:
log-file = /alliglog/bearer.log
log-level = number_0-4
Log Level. Sets the level of information to be recorded in the log file. Settings are as follows (with 0
providing the most detail and 4 the least):
0 Debug
1 Information
2 Warning
3 Error
4 Panic
If log-level is not defined in the configuration file, it defaults to a value of 1.
Example:
log-level = 0
box-deny-ip = List_of_IP_addresses
box-allow-ip = List_of_IP_addresses
Denied and allowed Box IP List. These variables list the IP addresses of WAP or SMS Boxes to
which the Bearer Box may, or may not, forward packets. These variables allow you to prevent third
parties from intercepting TCP packets as they leave the Bearer Box.
Addresses in the Denied and Allowed Box IP Lists are separated by semicolons. An asterisk * can
be used as a wildcard in place of any single group of digits, so *.*.*.* matches any IP address.
Examples:
box-deny-ip = *.*.*.*
box-allow-ip = 10.0.0.6;10.0.0.7
37
Chapter 9. 9 Configuring the Alligata Server
admin-deny-ip = List_of_IP_addresses
admin-allow-ip = List_of_IP_addresses
Administration Denied and Allowed IP Lists. These variables list IP addresses to be denied and
allowed HTTP administration access to the Alligata Server. Addresses are formatted in the same
way as in box-deny-ip and box-allow-ip.
Examples:
admin-deny-ip = *.*.*.*
admin-allow-ip = 10.0.0.6;10.0.0.7
unified-prefix = List_of_telephone_code_prefixes
Unified Prefix. Lists substitutions for telephone code prefixes in SMS messages. Substitutions are
applied to the 'sender' and 'recipient' fields in incoming and outgoing SMS messages respectively,
and ensure that all equivalent numbers are formatted consistently for SMSCs.
The format for each substitution is r,p1,p2... where r is the replacement prefix, and p1, p2,
etc. are the prefixes to be replaced.
You can define any number of substitutions in the configuration file by separating each definition
with a semicolon ;.
Example:
unified-prefix = 0044, 0; 00555, 05, 050
white-list = URL
White List. Links to a file listing telephone numbers of approved senders of SMS messages to the
Alligata Server. SMS messages from numbers not in this list will be automatically discarded.
The white list file should contain telephone numbers separated by carriage returns.
Note: only the last nine digits are read, so it is theoretically possible for unauthorised senders with
numbers nearly identical to those in the white list to gain access to the Alligata Server. The
likelihood of this occurring is, however, minimal.
If the configuration file contains a white-list, it should not contain a black-list.
Example:
white-list = http://www.awebsite.net/alligata/white.htm
black-list = URL
Black List. Links to a file listing telephone numbers of prohibited senders of SMS messages to the
Alligata Server. SMS messages from numbers on this list are automatically discarded.
The black list file should contain telephone numbers separated by carriage returns.
As with the white list, only the last nine digits of the number are read by the Alligata Server.
If the configuration file contains a black-list, it should not contain a white-list.
Example:
black-list = http://www.awebsite.net/alligata/black.htm
38
Chapter 9. 9 Configuring the Alligata Server
http-proxy-host = IP_address/URL
HTTP Proxy Host. Identifies a proxy server to be used for HTTP requests.
Example:
http-proxy-host = 10.0.0.8
http-proxy-port = port_number
HTTP Proxy Port. Identifies the port on the proxy server to which the Alligata Server connects.
Example:
http-proxy-port = 13005
http-proxy-exceptions = list_of_IP_addresses/URLs
HTTP Proxy Exceptions. Lists Internet addresses to be reached directly rather than via the proxy
server (for example, computers on a local network).
Multiple values should be separated by spaces. Example:
http-proxy-exceptions = 10.0.0.3 10.0.0.4
access-log = file_name
Access Log File. Specifies a file to which to output a log report of SMS messages processed by the
Bearer Box.
Example:
access-log = bearerbox.access
group = wapbox
bearerbox-host = IP_address/URL
Bearer Box Host. Identifies the computer hosting the Bearer Box. (Required.)
Examples:
bearerbox-host = localhost
bearerbox-host = 100.100.100.100
39
Chapter 9. 9 Configuring the Alligata Server
bearerbox-host = acomputer.asite.net
log-file = file_name
Log File. Specifies a file to which to output a log report of the WAP Box's activity. If the specified
file already exists, new output is added to the end of it.
If a log file is also defined in the command line when the WAP Box is started up (see Section 8.1.3),
then the log report will be output to both files.
If log-file is not set in the configuration file, it defaults to /var/log/alligata/wapbox.log.
Example:
log-file = /alliglog/wap.log
log-level = number_0-4
Log Level. Sets the level of information to be recorded in the log file. Settings are as follows (with 0
providing the most detail and 4 the least):
0 Debug
1 Information
2 Warning
3 Error
4 Panic
If log-level is not defined in the configuration file, it defaults to a value of 1.
Example:
log-level = 0
timer-freq = value_in_seconds
Timer Frequency. If not set in the configuration file, defaults to a value of 1.
Example:
timer-freq = 3
URL Mapping. On incoming URL requests, replaces url#1 with url#2. Asterisks can be used as
wildcards to right-truncate either or both of the URLs.
Example:
map-url = xlwa/* http://www.extremely_longwinded _wapsite_address.com/*
This example enables a mobile device user to gain access to the URL
http://www.extremely_longwinded_wapsite_address.com/contacts.wml simply by
keying xlwa/contacts.wml.
Note: only one map-url is allowed in the configuration. If you need to map more than one URL, use
map-url-0, etc. together with map-url-max.
map-url-max = number
URL Mapping Maximum. Sets the maximum number of URL mappings to be defined in the
configuration file.
40
Chapter 9. 9 Configuring the Alligata Server
If no maximum is specified, the Alligata Server allows a default maximum of ten mappings,
numbered from 0 to 9 (see map-url-0, map-url-1, etc.).
Example:
map-url-max = 8
device-home = url
Device Home. For Openwave's UP.Browser, defines the client's WML home deck. The actual URL
supplied by the Openwave microbrowser is DEVICE:home. Both parts of the variable definition are
implicitly right-truncated.
Thus,
device-home = http://www.devicehome.com/
is equivalent to
is equivalent to
Example:
device-home = http://www.devicehome.com/
41
Chapter 9. 9 Configuring the Alligata Server
group = smsbox
bearerbox-host = IP_address/URL
Bearer Box Host. Identifies the computer hosting the Bearer Box. (Required.)
Examples:
bearerbox-host = localhost
bearerbox-host = 10.0.0.1
bearerbox-host = acomputer.asite.net
sendsms-port = port_number
Send SMS Port. Specifies the port via which SMS messages sent from a workstation by HTTP are
received (see Section 9.3.4).
The port number can be any value between 1024 and 65535. (It may be under 1024 if the user
variable in the Core configuration group is set to root, but this is not advised.)
Example:
sendsms-port = 13001
telephone_number
Global Sender Number. Specifies the number shown as the sender's telephone number in outgoing
SMS messages.
Note that most SMSCs will automatically replace this number with their own.
Example:
global-sender = 44998123456
log-file = file_name
Log File. Specifies a file to which to output a log report of the SMS Box's activity. If the specified
file already exists, new output will be added to the end of it.
If a log file is also defined in the command line when the SMS Box is started up, then the log report
will be output to both files.
If log-file is not set in the configuration file, it defaults to /var/log/alligata/smsbox.log.
Example:
log-file = /alliglog/sms.log
log-level = number_0-4
Log Level. Sets the level of information to be recorded in the log file. Settings are as follows (with 0
providing the most detail and 4 the least):
0 Debug
1 Information
2 Warning
3 Error
4 Panic
42
Chapter 9. 9 Configuring the Alligata Server
access-log = file_name
Access Log File. Specifies a file to which to output a log report of SMS messages processed by the
SMS Box.
Example:
access-log = smsbox.access
43
Chapter 9. 9 Configuring the Alligata Server
group = smsc
smsc = smsc_type
SMSC Type. Identifies the SMSC type. Currently available types are cimd, cimd2, emi,
emi_ip, smpp, sema, at and ois. See Figure 9.3. (Required.)
Example:
smsc = emi
smsc-id = string
SMSC Identifier. Provides a name by which the SMSC can be referred to elsewhere. This name can
be used to associate the SMSC with particular SMS services and users, via the accepted-smsc,
forced-smsc and default-smsc variables in the SMS Service and Send SMS User groups (see
Sections 9.3.3 and 9.3.4).
The value of smsc-id may contain any alphanumeric characters, and is case-insensitive. Example:
smsc-id = smsc1
denied-prefix = list_of_telephone_code_prefixes
Denied Telephone Prefix List. Lists prefixes of telephone numbers to which messages are not to be
sent via this SMSC.
Numbers in the list are separated by semicolons ;.
44
Chapter 9. 9 Configuring the Alligata Server
The denied-prefix variable may be needed because some SMSCs do not allow messages to be
sent to users on different telephone networks to their own. denied-prefix and
preferred-prefix can also be useful to direct calls to the cheapest SMSC according to their
destination code.
Example:
denied-prefix = 0898;0999
preferred-prefix = list_of_telephone_code_prefixes
Preferred Telephone Prefix List. Lists prefixes of telephone numbers that should, if possible, be sent
messages via this SMSC.
Numbers in the list are separated by semicolons ;.
It is possible for a telephone code prefix to be listed as preferred in more than one SMSC group.
Where this is the case, the Alligata Server chooses one of these SMSC groups at random.
Where a telephone number's prefix is not listed as preferred in any SMSC group, the Alligata Server
chooses a group at random from all available SMSC groups. Example:
preferred-prefix = 01487;01223
host = IP_address/host_name
Examples:
host = 10.0.0.20
host = acomputer.acompany.net
port = port_number
SMSC Host Port. Identifies the port number on the SMSC host machine used for communication.
(Required.)
Example:
port = 13004
our-port = port_number
Local Port. Identifies the port on the Alligata Server's host machine used for communication with
the SMSC. Currently only the EMI IP protocol supports this.
Example:
our-port = 13005
receive-port = port_number
Receive Port. Used with protocols that accept different send and receive ports, namely EMI IP,
SMPP IP and OIS.
Example:
receive-port = 13006
45
Chapter 9. 9 Configuring the Alligata Server
smsc-username = user_name
SMSC User Name. The Alligata Server's account user name on the SMSC's host machine.
Example:
smsc-username = ally
smsc-password = password
SMSC Password. The Alligata Server's account password on the SMSC's host machine.
Example:
smsc-password = PINEapple
device = device_name
System Device. When the Alligata Server is used with a GSM modem or the EMI or X.28
protocols, this identifies the device associated with the modem.
Example:
device = /dev/ttyS0
connect-allow-ip = list_of_IP_addresses
Allowed IP Connections. Specifies IP addresses of SMSCs to be allowed to connect to the Alligata
Server. Used by EMI IP.
Example:
connect-allow-ip = 10.0.0.20 10.0.0.21
smsc_nua = X.121_address
home_nua = X.121_address
Radio PAD (Product Assembler/Disassembler) address using X.121 protocol. Used by SEMA X.28.
Example:
home_nua = 000001220900
wait_report = digit_(0_or_1)
phone = telephone_number
46
Chapter 9. 9 Configuring the Alligata Server
phone = 44999123456
keepalive = number
system_id = string
system_type = string
address_range = range
modemtype = string
The type of modem being used to send SMS messages by the AT protocol. Modems currently
supported are as follows:
(The Nokia Premicell does not support user data headers (UDHs), so cannot be used for over-the-air
configuration messages.)
Used only by AT.
Example:
modemtype = wavecom
pin = number
Personal Identification Number. An optional variable used only by AT. Use this variable if the SIM
card inserted in your GSM modem requires a PIN for activation.
47
Chapter 9. 9 Configuring the Alligata Server
You can include as many SMS Service groups in the configuration as you like. Each group defines a
single SMS service.
For instructions on how to implement SMS services, see Section 13.
group = sms-service
keyword = word
Service Keyword. Defines the keyword that triggers the service. (Required.)
The keyword can only be a single word, without spaces, and must always be the first word in
incoming messages.
keyword is case-sensitive. For example, frog, Frog and FROG are treated as different keywords.
If keyword has the value default, then the SMS Service will be applied to all incoming messages
that do not contain recognised keywords.
Example:
keyword = football
Service Keyword Aliases. Defines alternative keywords that will trigger the service. Multiple aliases
must be separated by semicolons ;. Each alias must be a single keyword, containing no spaces.
Example:
aliases = Football;FOOTBALL
url = url
48
Chapter 9. 9 Configuring the Alligata Server
These parameters can also be used with the file and text variables. See Section 13.1 for
examples of how parameters can be used.
If an SMS Service group contains a url variable, it cannot also contain a file or a text (see
below). There can only be one url in an SMS Service group.
url can be used in conjunction with prefix and suffix to retrieve a section of a Web page.
Example:
url = http://www.awebsite.net/cgi/salary?user=%s&password=%s&employee=%r
file = file_name
Retrieval File. Specifies a file on a local disk from which to fetch data.
The whole of the file is retrieved, except for the last character (usually a line feed).
If an SMS Service group contains a file, it cannot also contain a url or a text. There can only be
one file in an SMS Service group.
file supports all the parameters listed under url.
Examples:
file = /replies/areply.txt
file = /info/%s
text = character_string
49
Chapter 9. 9 Configuring the Alligata Server
Examples:
text = All is well over here.
prefix = character_string
suffix = character_string
Retrieval Prefix and Suffix. Used in conjunction with url. The Alligata Server retrieves all text
between (but not including) the prefix and the suffix in the target Web page. Tags are stripped out.
If the target page contains more than one occurrence of the prefix or suffix, then the Alligata Server
retrieves everything between the first occurrence of the prefix and the first succeeding occurrence of
the suffix.
Examples:
prefix = <!--begin today's weather-->
faked-sender = telephone_number
Faked Sender Number. Specifies the number shown as the sender's telephone number in outgoing
SMS messages for this service.
faked-sender will override any sender numbers specified elsewhere (for example, the
global-sender variable in an SMS Box group).
Note that most SMSCs will replace the faked-sender number with their own.
Example:
faked-sender = 44998123456
max-messages = number
Maximum Reply Messages. Specifies the maximum number of individual SMS messages allowed
in a single reply.
If max-messages is not set in the configuration file, it defaults to a value of 1.
If max-messages is set to 0, then no replies will be sent, other than error messages.
Example:
max-messages = 8
split-chars = list_of_characters
Message Split Characters. Specifies characters that can be used to split a long outgoing message
into several shorter ones.
The maximum length of a single SMS message will vary depending on whether it uses a 7-bit or an
8-bit format, and whether it has a user data header (UDH). A 7-bit message usually has a maximum
length of 160 characters, an 8-bit message a maximum length of 140 characters.
50
Chapter 9. 9 Configuring the Alligata Server
Messages over the maximum length for a single message are split as specified in the configuration
file. Where split-chars is not specified, the Alligata Server uses any character to split the
message.
The Alligata Server only splits messages where necessary. For example, if the semicolon ; is
specified as a split character, then a message of 200 characters containing six semicolons will be
split into just two shorter messages, not seven.
Example:
split-chars = ;:.
split-suffix = character_string
Message Split Suffix. Where a long message is split into two or more shorter ones, specifies a string
to appear at the end of each message (except the last).
Example:
split-suffix = -cont.-
Omit Empty Messages. If set to a number other than 0, stops messages containing no data being
sent to the user.
Example:
omit-empty = 1
header = character_string
Reply Header. Specifies a string to appear at the beginning of outgoing messages. In the case of split
messages, the string appears on every message.
Example:
header = Today's weather...
footer = character_string
Reply Footer. Specifies a string to appear at the end of outgoing messages. In the case of split
messages, the string appears on every message.
Example:
footer = -- sent by the Alligata Server --
accepted-smsc = list_of_smsc_identifiers
Accepted SMSC identifiers. Only messages from SMSCs with these identifiers (see smsc-id in
Section 9.3.2) are allowed to use this service.
Multiple values should be separated by semicolons ;.
Example:
accepted-smsc = smsc1;smsc2
51
Chapter 9. 9 Configuring the Alligata Server
concatenation = 0_or_1
group = sendsms-user
username = string
Send SMS User Name. Specifies the account user name. (Required.)
Example:
username = colin
password = string
user-deny-ip = List_of_IP_addresses
Denied IP Addresses. Lists IP addresses from which SMS messages may not be sent using HTTP.
Addresses in the list are separated by semicolons. An asterisk * can be used as a wildcard in place
of any single group of digits. For example, *.*.*.* matches any IP address.
Example:
user-deny-ip = 0.0.0.0;10.0.0.6
user-allow-ip = List_of_IP_addresses
Allowed IP Addresses. Lists IP addresses from which SMS messages may be sent using HTTP.
Addresses are formatted in the same way as in user-deny-ip.
user-allow-ip = 0.0.0.0;10.0.0.7
faked-sender = telephone_number
Faked Sender Number. Specifies the telephone number shown as the sender's on client devices.
Note that most SMSCs will replace this number with their own.
52
Chapter 9. 9 Configuring the Alligata Server
faked-sender will override any sender numbers specified elsewhere (for example, the
global-sender variable in the SMS Box group).
Example:
faked-sender = 44998123456
max-messages = number
Maximum Messages. Specifies the maximum number of individual SMS messages into which a
long message can be split.
If max-messages is not set in the configuration file, it defaults to a value of 1.
If max-messages is set to 0, then no messages will be sent.
Example:
max-messages = 8
split-chars = list_of_characters
Message Split Characters. Specifies characters that can be used to split a long message into several
shorter ones.
The maximum length of a message is usually 140 or 160 characters, depending on the SMSC's
protocol. Messages over this length are split as specified in max-messages and split-chars. If
split-chars is not set, any character is used to split the message.
The Alligata Server will only split messages where necessary. For example, if the semicolon ; is
specified as a split character, then a message of 200 characters containing six semicolons will be
split into just two shorter messages, not seven.
Example:
split-chars = .,':
split-suffix = character_string
Message Split Suffix. Where a long message is split into two or more shorter ones, specifies a string
to appear at the end of each message (except the last).
Example:
split-suffix = -cont.-
omit-empty = number
Omit Empty Messages. If set to a number other than 0, stops messages containing no data being
sent to the user.
Example:
omit-empty = 1
header = character_string
message Header. Specifies a string to appear at the beginning of outgoing messages. In the case of
split messages, the string appears on every message.
Example:
53
Chapter 9. 9 Configuring the Alligata Server
footer = character_string
message Footer. Specifies a string to appear at the end of outgoing messages. In the case of split
messages, the string appears on every message.
Example:
footer = -- Sent by Alligata Server --
forced-smsc = smsc_identifier
Forced SMSC Identifier. Forces SMS messages to be sent via the specified SMSC. See smsc-id in
Section 9.3.2.
Example:
forced-smsc = smsc1;smsc2
default-smsc = smsc_identifier
Default SMSC Identifier. Specifies an SMSC via which messages are to be sent, unless an
alternative SMSC is specified in the smsc parameter in the message itself (see Section 13.2.2).
Example:
default-smsc = smsc1
concatenation = 0_or_1
If set to 1, allows concatenation of multiple SMS messages in the client device.
Example:
concatenation = 1
group = otaconfig
location = url
54
Chapter 9. 9 Configuring the Alligata Server
location = http://www.awapsite.net/
service = string
ipaddress = IP_address
IP address of the Alligata Server's Bearer Box.
Example:
ipaddress = 10.0.0.1
phonenumber = telephone_number
Telephone number via which the client device establishes the point-to-point Protocol (PPP)
connection with the Alligata Server.
Example:
phonenumber = 44998123456
bearer = string
calltype = string
Call type, either isdn or analogue.
connection = string
pppsecurity = on or off
authentication = string
Authentication mode, either normal or secure. secure enables WTLS security. Defaults to normal.
login = user_name
secret = password
User password.
Example:
password = KUMquat
55
Chapter 10. 10 Creating WAP Documents
The Alligata Server allows you to offer users of mobile WAP devices an access point to the Mobile
Internet. You do not need to provide any WAP content of your own. However, you will probably want to
set up your own WAP services - either static WML decks, or Common Gateway Interface (CGI)
applications that retrieve data and format it automatically as WML.
In order to disseminate information on the Mobile Internet, all you need is space on the Internet from
which a standard HTTP server such as Apache can retrieve data. In other words, serving WAP data is
almost exactly the same as serving Web data. The only difference from the point of view of the content
provider is that the data sent to the client must be in WML rather than HTML format. To all intents and
purposes, WAP files are Web files, but in a different format to that understood by PC Web browsers.
When the HTTP server to which your Internet space is connected receives a request for WAP data, it
finds the relevant file and sends it - or, if it is a CGI application, its WML output - to the IP address that
requested it. It sends it using HTTP, like a Web file. The IP address to which it sends it is that of a WAP
gateway (for example, an installation of the Alligata Server). The gateway compresses the data and sends
it over the wireless network to the client mobile device that sent the original WAP request. See Section 3
for more information about what the WAP gateway does.
56
Chapter 11. 11 Introduction to WML
This section gives a summary of Wireless Markup Language (WML). WML is the formatting language
used to encode WAP documents. Full details of WML can be found in the official WML specification on
the WAP Forum's Web site at http://www.wapforum.org. here we aim to provide you with enough
information to get started with WML and create some basic WML documents of your own. The Alligata
Server package includes some example WML files, so that you can see how WML works in practice.
WML is derived from Hypertext Markup Language (HTML), the tagging system used to format World
Wide Web pages; if you are familiar with HTML, you should find WML fairly easy to learn. However,
WML is tailored to display information on much smaller display areas than HTML, and to be compact
enough to transmit efficiently, in compressed form, over low-bandwidth, high-latency wireless networks.
Writing WML is straightforward: you can use either a text editor, or one of the increasing number of
dedicated WML editors available on the market. To check the formatting of your WML, we recommend
you get a WAP phone, or download one of several free WAP phone emulators from the World Wide Web.
The rest of this section covers the main features of WML.
<?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="foo" name="bar" title="Static WML"
newcontext="true">
<p>
<img src="3glab.wbmp" alt="3G Lab Logo" align="middle"/>
<br/>
This is static <big>WML</big> text.
</p>
</card>
</wml>
This file, like all WML documents, holds two main types of information: content and tags.
Content is generally textual information to be displayed on the client's microbrowser. It is encoded as
plain text using the Unicode 2.0 character set. The example file's content is the sentence 'This is static
WML text'.
Some characters are not included in the Unicode character set, or are problematic to display because they
are used by WML for purposes other than text display (for example the less than < and greater than >
symbols, which denote the start and end of tags). Such characters are represented by entity references
which begin with an ampersand &, and end with a semicolon ;. Some of the most common entity
references in WML are:
57
Chapter 11. 11 Introduction to WML
Tags are the pieces of information held within angled brackets < >. Tags can do one of several things:
they can describe to the microbrowser how to format content; tell it to display non-textual items where
they occur; or describe an action for the microbrowser to perform in certain circumstances. Tags are not
visible to the user of the client device.
Many tags occur in pairs, with a start tag immediately before the section of the file they relate to, and a
corresponding end tag after it. An end tag always has a forward slash / immediately after the opening
angled bracket.
In the example file, you can see that the letters 'WML' have a <big> tag before them, and a </big> tag
after them. These tags tell the microbrowser to display the content between them in large text. So on your
microbrowser, the sentence will look like this:
A tag that does not have a closing tag is called an empty tag - empty because it has no content or other
tags inside it. An example is the tag <img alt="3G Lab Logo" src="3glab.wbmp"
align="middle"/>. This tag tells the browser to display the image file 3glab.wbmp where it occurs.
Note that an empty tag must end with a forward slash, so that the browser knows not to look for a
companion end tag. In this respect WML differs from HTML, so if you are used to writing HTML,
remember to include these slashes.
58
Chapter 11. 11 Introduction to WML
several cards, a microbrowser will always display the first card by default.
A card contains a 'screen's worth' of information. Because most WAP client devices have small display
areas, the user will often have to scroll downwards to view the whole of a card; but the card should not be
so long that they lose track of where they are. WML's navigation facilities enable you to jump from one
card in a deck to another.
Cards are marked up using the card element. There is no deck element - a deck comprises everything
inside a file's wml element. See Section 11.5 for more information on the wml element.
The tag <?xml version="1.0"?> tells the browser that the file is an XML document, complying with
version 1.0 of the XML specification. XML is a markup language of which WML is a specialised subset.
So every valid WML document is implicitly also a valid XML document.
The second tag tells the browser where to find the Document Type Definition (DTD) for files of its type -
in this case, WML files. A DTD is an electronic specification for a file's format, declaring what elements
are allowed within what other elements, and what attributes each element is allowed to contain. If the
structure of the file does not match the structures allowed by the DTD, then the browser knows that it
contains errors, and may display a message warning the user of this. In practice, browsers are often
tolerant of errors and will do their best to display files, even if they are not structurally valid. However,
you should always try to structure your WML files properly - apart from being good practice, this
guarantees that they will display as you intend on all WML-compliant browsers.
These two tags are not WML tags, but validation tags instructing the browser to parse the rest of the file
as WML.
11.6 Paragraphs
It is good practice to organise WML content into paragraphs. Paragraphs are defined by the p element.
Note that in WML, unlike in HTML, each <p> tag must have a corresponding </p> closing tag. For
example:
<card>
59
Chapter 11. 11 Introduction to WML
By default, text between <p>...</p> tags is left-aligned. You can centre- or right-align it using the
align attribute with the value center or right respectively. For example:
11.7 Hyperlinks
Like HTML, WML allows you to include hyperlinks in your documents. A hyperlink can carry the user
to a different place in the current deck, a different deck on the same WAP site, or a different WAP site.
How a hyperlink is activated by the user is a matter for the browser manufacturer. A typical
implementation might provide two buttons on the device to move a highlight backwards and forwards
between hyperlinks, and a third button to activate the highlighted link.
The hyperlink element in WML is a (as in HTML, this stands for 'anchor'). It takes an attribute href,
which indicates the destination of the link. For example:
Here, the words 'little acorns' are a hyperlink taking the user to the WAP site www.littleacorns.com. On a
browser, the hyperlink may be indicated by underlining, in which case the sentence above would be
displayed like this:
To create hyperlinks between cards in the same deck, give each card a unique id attribute, and refer to
that id in the href attribute of hyperlinks to it. In the href attribute, precede the destination card's name
with a hash #: this indicates that the link is to a card rather than to a file.
The example file below contains two cards, linked by referring to one another's id attributes.
<?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="card1">
<p>
This is a WML card.
</p>
<p>
<a href="#card2">Next card...</a>
</p>
</card>
<card id="card2">
<p>
And this is another.
60
Chapter 11. 11 Introduction to WML
</p>
<p>
<a href="#card1">Previous card...</a>
</p>
</card>
</wml>
You can also link to a specific card in another deck by appending a hash # and the card's id to the URL.
For example:
Here, the link 'Go to that card' takes the user to the card acertaincard in the deck anotherfile.wml.
• The type attribute gives the client browser an indication of what category of tasks the current task
belongs to. Possible values include "accept", "prev", "help", "reset", "options" and
61
Chapter 11. 11 Introduction to WML
"delete". Note that the type attribute has no bearing on the actual function of the task element: it
simply allows the client browser to decide how to display it. For example, the Nokia 7110 WAP phone
displays a do element of the prev type in the bottom right corner of the screen and associates it with
the right navigation button.
• The label attribute tells the browser what wording to assign to the function on-screen. In some
instances, a client device may automatically override a label attribute: for example, the Nokia 7110
phone always labels a do type="prev" function as 'Back', regardless of the content of the label
attribute.
• The name attribute gives the do function an identifier by which scripting languages such as
WMLScript can refer to it.
Suppose a client device associates do type="prev" with its right navigation button, and accepts a
WML-defined label attribute. On such a device, our example do function might appear as shown in the
bottom right corner of Figure 11.1.
Figure 11.1
11.9 Events
WML allows you to specify automatic actions in a client device that are precipitated by particular
'events'. An 'event' must be associated with a particular element in a WML file - either card, wml or
option. The response to an event is defined by the onevent element, which must occur within the
element to which it relates. The type of event to respond to is indicated in the type attribute of the
onevent element.
Possible values for the type attribute are as shown in Figure 11.2.
The action undertaken by the client device in response to an event must be defined by one of the task
elements go, prev, noop or refresh. The task element must be situated within the onevent
element.
For example:
<card>
<onevent type="onenterbackward">
<go href="backwardpeople.wml"/>
</onevent>
You didn't enter this card backwards.
</card>
62
Chapter 11. 11 Introduction to WML
If a user arrives at this card via a hyperlink or a go task, they will see the message
However, if the user arrives at the card via a prev task, they will be redirected to the file
backwardpeople.wml.
There is another way of handling an event that is shorter, but less flexible. Instead of using the onevent
element, you can specify an action in the form of an attribute in the relevant card or wml element. For
example, the sample WML above could be rewritten as follows, and would do exactly the same thing:
<card onenterbackward="backwardpeople.wml">
You didn't enter this card backwards.
</card>
Note that the only kind of action possible using this method is a jump to a URL (in this case,
backwardpeople.wml). This is equivalent to the go action. If you want to perform a prev, a noop or a
refresh action, you have to use the longer method.
63
Chapter 11. 11 Introduction to WML
11.10 Templates
Suppose you create a WML deck consisting of five cards, and you want a prev task on every card except
the first. Rather than repeating the same do statement in each of the four cards - which is laborious for
you as a WML author, and uses up precious bytes in the WML file - you can use the template element
to specify a task to appear automatically on every card you want.
Here is an example of a WML file that uses a template element:
<?xml version="1.0"?>
<!DOCTYPE wml PUBLIC "-//WAPFORUM//DTD WML 1.1//EN"
"http://www.wapforum.org/DTD/wml_1.1.xml">
<wml>
<template>
<do type="prev">
<prev/>
</do>
</template>
<card id="card1">
<do type="prev">
<noop/>
</do>
Love speaks, even when the lips are closed.
<br/>
<a href="#card2">
Next proverb...
</a>
</card>
<card id="card2">
It is an ill dog that deserves not a crust.
<br/>
<a href="#card3">
Next proverb...
</a>
</card>
<card id="card3">
He who wants a mule without fault, must walk on foot.
<br/>
<a href="#card4">
Next proverb...
</a>
</card>
<card id="card4">
Never cast a clout till May be out.
<br/>
<a href="#card5">
Next proverb...
64
Chapter 11. 11 Introduction to WML
</a>
</card>
<card id="card5">
Scabby donkeys scent each other over nine hills.
<br/>
</card>
</wml>
When this file is viewed on a WAP microbrowser, every card except the first one has a 'Back' link on it -
even though, in the WML source, none of them contains a prev task. The explanation for this is that the
prev task is held in the template element at the beginning of the file, and is applied automatically to
every card in the deck, except the first.
The reason there is no 'Back' link on the first card is that the first card contains a noop task. Because a
task defined in a card always overrides a default task of the same type as specified in the template, and
because noop does nothing, this card displays nothing in place of a 'Back' link.
11.11 Variables
One of the most interesting features of WML is its ability to process variables. If you have any
programming experience, you will know that a variable is a 'label' for a numeric value or a string of
characters in a computer program. A common use of variables is to store input from a user or another
external source - in other words, information that can't be written into the program itself.
Variables in WML enable you to implement interactive features into your cards and decks without
getting involved in the complexities of scripting languages like WMLScript. Note that the only variables
allowed in WML are strings.
There are a number of ways in which you can specify variables. One of the most useful is via the input
element, which allows the user to enter information into the client device's interface.
Here is a very simple WML deck that writes a 'proverb' based on terms the user enters through the
input element:
<?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="card1" title="Proverb Wizard">
Name an animal:
<input name="animal"/>
Name a vegetable:
<input name="vegetable"/>
<a href="#card2">
View proverb...
</a>
</card>
65
Chapter 11. 11 Introduction to WML
<go href="#card1"/>
</do>
A small $(animal) may eat a large $(vegetable).
</card>
</wml>
When this file is opened on a microbrowser, the following card will be displayed:
Figure 11.3
As can be seen, there are two input fields. These are created by the tags <input name="animal"/>
and <input name="vegetable"/> in the WML source. The name attributes tell the browser to
create the variables animal and vegetable respectively, based on what the user types into each field.
To select a horse for the animal and a radish for the vegetable, enter horse into the first field and
radish into the second field. (The actual mechanism for entering text will depend on your
microbrowser. For example, it may present you with an Edit option that you activate by pressing one of
the phone's navigation buttons.)
The microbrowser display will now be as in Figure 11.4.
Figure 11.4
Now, activate the 'View proverb...' link. A new card is loaded, showing a proverb based on the terms you
entered in the first card (see Figure 11.5).
66
Chapter 11. 11 Introduction to WML
Figure 11.5
In the source WML you can see how the terms entered in the first card were passed to the second card.
The variables animal and vegetable were set in the tags <input name="animal"/> and <input
name="vegetable"/>.
When the browser encounters a dollar symbol $, it knows that what follows in parentheses is a variable.
So instead of displaying '(animal)' it looks for the variable called animal and displays its value - in this
example, the string 'horse'. It does the same with the variable vegetable, substituting its name with
'radish'.
(If you want to display a dollar symbol on the screen, use two dollar symbols $$ in your WML file.)
11.12 Timers
You can incorporate a timer into a WML card or deck using the timer element. When a timer runs out,
an action is performed as specified in the ontimer event handler. See Section 11.9 for more details
about event handling.
timer takes a value attribute, specifying how long the timer should run for. The value is expressed in
tenths of a second.
Here is an example timer implementation:
<?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="wait">
<onevent type="ontimer">
<go href="#thankyou"/>
</onevent>
<timer value="40"/>
<p>
Please wait.
</p>
</card>
67
Chapter 11. 11 Introduction to WML
<card id="thankyou">
<p>
Thank you for waiting.
</p>
</card>
</wml>
When you first load this file you will see the message 'Please wait.' After about four seconds, the first
card will time out and the second card will appear, showing the message 'Thank you for waiting.'
11.13 Images
WML can include embedded images. These must be in two-colour wireless bitmap (WBMP) format.
There are several free WBMP editors that can be downloaded from the World Wide Web.
To embed an image in a file, use the img element with some or all of the attributes shown in Figure 11.6.
For example:
For example:
<p align="center"> <img src="image.wbmp"
</p>
68
Chapter 11. 11 Introduction to WML
69
Chapter 12. 12 Example WAP Sites
Included on the Alligata Server CD-ROM are five example WAP sites. If you installed the example sites
along with the Alligata Server (see Sections 4 and 5), and you have an HTTP server such as Apache
running on your computer, you can view them from a WAP phone or a WAP phone emulator.
The example sites are illustrations of the kinds of service you can implement using WAP. You can create
simple sites using just WML, or you can incorporate dynamic features into them using scripting
languages like Perl and PHP. The most important thing to remember is to keep the files you serve as
small and simple as possible. A compiled WML file should not be larger than 1400 bytes, which means
the size of your source WML file should not exceed about 3000 characters.
To view the example WAP sites:
1. If you have not already done so, install the Alligata Server as described in Sections 4 and 5. If you
are installing from a graphical user interface, select 'Alligata Server example sites' in the main
installation dialog box. If you are installing from the command prompt, enter Y when you are asked,
'Install Alligata Server examples?'.
2. Start the Bearer Box and the WAP Box using any of the methods described in Section 8.1.
3. Start the Web server. For example, to start Apache:
Linux users:. Type /etc/rc.d/init.d/httpd start at the command prompt, and press
ENTER.
Solaris users:. Type /etc/init.d/apache start at the command prompt, and press ENTER.
4. Configure your WAP client device to use your installation of the Alligata Server as its WAP gateway.
An example configuration is shown in Figure 12.1.
The login and password settings are those of your Point-to-Point Protocol (PPP) server.
5. On your WAP client device, navigate to the URL of the example sites index. By default this will be
the URL of your Web server, followed by /wml/; for example,
70
Chapter 12. 12 Example WAP Sites
http://acomputer.asite.net/wml/.
Figure 12.3
After a few seconds the logo will disappear, to be replaced by a set of links (see Figure 12.4).
71
Chapter 12. 12 Example WAP Sites
Figure 12.4
If you follow a link, you will be taken to the corresponding piece of information. You can also use the
link 'ACME home' to take you back to the home deck. (Since this is a prev task, it may simply be
labelled 'Back' on your device's display - see Section 11.8.)
If you select 'ACME Vacancies', the card in Figure 12.5 will appear on your screen.
Figure 12.5
If you select a link from this card, you will be taken to information about the relevant post. For example,
'Head of Marketing' will show you the card in Figure 12.6.
Figure 12.6
From here you can use the 'ACME Vacancies' link to return to the list of jobs. (Again, this a prev task,
so your device may just label it 'Back'.) To go right back to the home deck, keep navigating backwards in
the same way.
From the home deck, you can navigate through any series of cards in the way just described.
72
Chapter 12. 12 Example WAP Sites
The first file that the microbrowser loaded when it visited the site Static Complex is called
index.wml. Its source is as follows:
<?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="logo" ontimer="#menu" title="Welcome to ACME" newcontext="true">
<timer value="30"/>
<img alt="ACME corp" src="acmelogo.wbmp" align="middle"/>
</card>
<card id="menu" name="menu" title="the ACME menu">
<do type="prev" label="ACME home">
<prev/>
</do>
<a href="info.wml">
What is ACME?
</a>
<br/>
<a href="contact.wml">
Contacting ACME
</a>
<br/>
<a href="employ.wml">
ACME Vacancies
</a>
<br/>
<a href="wpaper.wml">
ACME White Paper
</a>
</card>
</wml>
Remember that your microbrowser does not see this data but a compressed version of it that is less easy
for a human being to decipher, but quicker to transmit and using less of the client device's limited
memory.
The first two tags in the file are the XML validation tags:
<?xml version="1.0"?>
<!DOCTYPE wml PUBLIC "-//WAPFORUM//DTD WML 1.1//EN"
"http://www.wapforum.org/DTD/wml_1.1.xml">
As we saw earlier, every WML file needs to start with these tags, which specify which versions of XML
and WML the file conforms to (see Section 11.4).
Next comes the deck-level <wml> tag. Following that is the first card in the deck:
73
Chapter 12. 12 Example WAP Sites
This is the card containing the ACME logo. Because it is the first card in the deck, it is the one that
appears by default when you load the file.
Here is a description of the card item by item.
First, you will see that the card element contains four attributes:
• id="logo" gives the card a name by which other cards or decks can refer to it.
• ontimer="#menu" tells the microbrowser that when the timer contained in the card runs out, it
should load the card menu. The timer is defined in the timer element.
• title="Welcome to ACME" defines a title to appear at the top of the card in the microbrowser.
• newcontext="true" instructs the microbrowser to reset its 'context' when the card is loaded. A
microbrowser's context consists of information it holds in its memory about recent events. Specifically,
newcontext="true" removes all WML variables, clears the microbrowser's navigation history, and
resets other information in the microbrower to its default value. precisely what information this is
depends on the microbrowser.
The next element is timer. It has the attribute value="30", which tells the microbrowser to wait about
three seconds before performing the action specified in the card's ontimer attribute.
Note that, because timer is an empty element - that is, one without a closing tag - its tag must end in a
forward slash /.
The remaining element in the card is img, with three attributes:
• alt="ACME corp" tells the microbrowser to display the text 'ACME corp' if it cannot load the image
for any reason.
• src="acmelogo.wbmp" tells the microbrowser that the image to be displayed is the file
acmelogo.wbmp.
• align="middle" tells the microbrowser to centre the image vertically, in relation to the surrounding
text.
img, like timer, is an empty element, so the tag needs a forward slash / at the end of it.
74
Chapter 12. 12 Example WAP Sites
</a>
<br/>
<a href="wpaper.wml">
ACME White Paper
</a>
</card>
This is the menu that appeared when the ACME logo card timed out. As you can see, it is a list of
hyperlinks to other WML files, with each hyperlink being defined by its own a element. Note that the
card begins with a do element, which implements a prev link to allow navigation back to the previous
card.
We selected the hyperlink 'ACME Vacancies' from this menu. As you can see from the source WML, that
link goes to the file employ.wml, which looks like this:
<?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="employ" title="Vacancies">
<do type="prev" label="ACME home">
<prev/>
</do>
<a href="#job1">
Systems Analyst
</a>
<br/>
<a href="#job2">
Head of Marketing
</a>
<br/>
<a href="#job3">
Chief of Admin
</a>
<br/>
<a href="contact.wml">
-=Contact ACME=-
</a>
</card>
75
Chapter 12. 12 Example WAP Sites
<prev/>
</do>
<p>
ACME is looking for a new head of Marketing:
someone who is living in Tibet, or can move
there at short notice, with a 3rd tier
university degree and at least five years'
experience in a marketing environment.
Must be a people person.
</p>
</card>
<card id="job3" title="Job: Chief Admin">
<do type="prev" label="ACME Vacancies">
<prev/>
</do>
<p>
ACME is looking for a new chief of administration.
If you are a talented manager with a head for
figures, an eye for detail and a gift for
coercion, we would like to hear from you.
</p>
</card>
</wml>
All the features of this file are described elsewhere in this guide. It is a deck of four cards, with the first
card presenting hyperlinks to the other three. In the earlier example the link 'Head of Marketing' was
chosen, which goes to the card job2.
Note that, once again, every card in the deck has a <prev/> link to return to the previous card.
76
Chapter 12. 12 Example WAP Sites
To view the Alligata Server example Perl site, select 'Sysinfo Perl' from the Site Examples index. You
will see the card in Figure 12.7.
Figure 12.7
The first item in the list is a hyperlink that takes you to a card showing the names of the users currently
logged in to the server machine (see Figure 12.8).
Figure 12.8
The WML generated by the Perl script for this file is as follows:
<?xml version="1.0"?>
<!DOCTYPE wml PUBLIC "-//WAPFORUM//DTD WML 1.1//EN"
"http://www.wapforum.org/DTD/wml_1.1.xml">
<wml>
<template>
<do type="prev" name="back" label="Back">
<prev/>
</do>
</template>
77
Chapter 12. 12 Example WAP Sites
78
Chapter 12. 12 Example WAP Sites
Figure 12.9
Follow any of the three links, 'Load/Uptime', 'Memory' or 'Port Status', to display the relevant card.
Example cards are shown below. For ease of legibility, the content of these cards is shown in full, rather
than on a microbrowser screen. The information in the 'Load/Uptime' card is explained in the right
column; the information in the 'Memory' and the 'Port Status' cards is self-explanatory.
Load/Uptime
--
time: 2:40pm The time according to the system's clock
up: 8 d 1:56 The amount of time the system has been running
users: 7 The number of logins since the system was started up
load (1): 2.91 The system's average load over the last minute
load (5): 2.53 The system's average load over the last 5 minutes
load (15): 2.08 The system's average load over the last 15 minutes
Memory
--
total: 192704
used: 189652
free: 3052
shared: 117292
buffers: 30056
cached: 28444
Port Status
--
21: open
22: open
23: open
53: closed
80: open
<?xml version="1.0"?>
<!DOCTYPE wml PUBLIC "-//WAPFORUM//DTD WML 1.1//EN"
"http://www.wapforum.org/DTD/wml_1.1.xml">
<wml>
<head>
<meta http-equiv="Cache-Control" content="max-age=0" forua="true"/>
</head>
79
Chapter 12. 12 Example WAP Sites
<template>
<do type="accept">
<go href="#"/>
</do>
<do type="prev" name="back" label="Back">
<prev/>
</do>
</template>
<card id="up">
<p align="center">
<b>Load/Uptime</b>
<br/>
--
</p>
<p align="left">
time: 12:29pm
<br/>
up: 8 d 1:56
<br/>
users: 7
<br/>
load (1): 2.91
<br/>
load (5): 2.53
<br/>
load (15): 2.08
<br/>
</p>
</card>
<card id="mem">
<p align="center">
<b>Memory</b>
<br/>
--
</p>
<p align="left">
80
Chapter 12. 12 Example WAP Sites
total: 192704
<br/>
used: 189652
<br/>
free: 3052
<br/>
shared: 117292
<br/>
buffers: 30056
<br/>
cached: 28444
<br/>
</p>
</card>
<card id="ports">
<p align="center">
<b>Port Status</b>
<br/>
--
</p>
<p align="left">
21: open
<br/>
22: open
<br/>
23: open
<br/>
53: closed
<br/>
80: open
<br/>
</p>
</card>
</wml>
<go href="view.php3?username=$username&password=$passwo
81
Chapter 12. 12 Example WAP Sites
rd&server=imap.asite.net"/>
To view the PAT mail site, select the link 'PAT: PHP mail' from the Site Examples index. You will see a
login card:
Figure 12.10
This card is from the file index.wml. Enter your e-mail user name and password and you will be taken
to the top of your e-mail inbox:
Figure 12.11
The inbox shows each message's number in the list and its subject. Owing to the size limitations of WML
files, the inbox is divided into segments of five messages. To view the next five messages in the inbox,
follow the hyperlink 'NEXT 5' at the bottom of the card.
To view a message, select the hyperlinked number preceding it. The message is prefixed by details of the
subject, the send date and time, and the sender:
Figure 12.12
82
Chapter 12. 12 Example WAP Sites
Figure 12.13
Where a message is longer than 700 characters, it is split into several smaller messages.
PAT is composed of several files. These are summarised in Figure 12.14.
File Function
Main files:
index.wml Contains the login card. Receives the user name
and password from the user and invokes
view.php3.
view.php3 Invokes lib/mailbox.php3 to display the
mailbox.
message.php3 Invokes lib/mailmessage.php3 to display a
message.
Library files:
lib/mailbox.php3 Sets up the class mailbox, which defines the
contents of a mailbox.
lib/mailmessage.php3 Sets up the class mailMessage, which defines the
contents of a message.
lib/mesgretrieve.php3 Prepares messages for WML display.
lib/wmlheader.php3 Defines a header for a WML file.
lib/escaper.php3 Converts escape characters.
83
Chapter 13. 13 SMS Messaging
The Alligata Server enables you to use SMS in three ways:
• To implement dynamic services such as retrieval of information from Web pages, in response to
keywords contained in incoming SMS messages from mobile phones.
• To send SMS messages to mobile phones from a personal computer, using HTTP commands.
• To configure WAP phones to use a particular WAP service from a computer workstation.
Before you can set up SMS keyword services or send SMS messages from a computer, you need to
create an SMS Box group and an SMSC group in the configuration file (see Section 9). You must also
have a subscription to an SMSC or a connection to a GSM modem, as explained in Section 9.3.2. Some
example settings are shown in Figure 13.1.
Figure 13.1: Example SMS Box and SMSC group configuration settings
group = smsbox
bearerbox-host = localhost
sendsms-port = 13013
global-sender = 123
log-file = /alligata/admin/smsbox.log
log-level = 0
group = smsc
smsc = at
modemtype = wavecom
device = /dev/ttyS2
group = sms-service
keyword = proverb
aliases = Proverb;PROVERB;potd;Potd;POTD
url = http://www.awebsite.net/potd.html
prefix = <!--beginprov-->
suffix = <!--endprov-->
split-chars = ;:.
split-suffix = -cont-
header = "Today's proverb -- "
max-messages = 10
This group sets up an SMS service that returns a proverb from the Web page
http://www.awebsite.net/potd.html when it receives the message 'proverb' from a mobile
84
Chapter 13. 13 SMS Messaging
device. From the Web page, it retrieves everything between (but not including) the strings
<!--beginprov--> and <!--endprov-->. The content of potd.html could look like this:
<html>
<head>
<title>SMS proverb of the day</title>
</head>
<body bgcolor="#FFFFFF" text="#000000">
<!--beginprov-->
A cat in gloves catches no mice.
<!--endprov-->
</body>
</html>
In this case, a user sending the message 'proverb' to the Alligata Server would receive the reply message
The Alligata Server does not require the prefix and suffix of the message to be in comments
<!--...-->, but bear in mind that if they are not, they will be visible in the Web page if it is viewed
from a desktop browser.
The maximum length of an SMS message is usually 140 or 160 characters (depending on whether it is in
7-bit or 8-bit format). If the text retrieved by the Alligata Server is longer than this limit, the Alligata
Server splits it into several messages. To do this, it uses the variables split-chars and split-suffix.
The message is split at an occurrence of one of the characters specified in split-chars, and all
sections of the message except the last have the text specified in split-suffix appended to them. The
Alligata Server splits the message at the nearest previous occurrence of a split character to the maximum
message length. For example, suppose the proverb in potd.html is a particularly long one:
<html>
<head>
<title>SMS proverb of the day</title>
</head>
<body bgcolor="#FFFFFF" text="#000000">
<!--beginprov-->
Monday's child is fair of
face, Tuesday's child is
full of grace; Wednesday's
child is full of woe,
Thursday's child has far
to go; Friday's child is
loving and giving, Saturday's
child works hard for its living;
and the child that is born on the
Sabbath day, is fair and wise and
good and gay.
<!--endprov-->
</body>
</html>
In this instance, the message needs to be split, and the user will probably receive it in three smaller
messages:
85
Chapter 13. 13 SMS Messaging
The string -cont.- in the first and second messages indicates that they are part of a longer message,
more of which is to follow. It is specified using the split-suffix configuration variable.
Note that the incoming SMS message must only contain the keyword, unless the SMS service allows
parameters after it. Parameters are discussed in Section 13.1.1.
As an example, suppose your company has created a CGI server application that returns an employee's
salary. You want the Personnel department to be able to gain access to this information from their SMS
phones, but no one else. In this case, you could configure the SMS Service group shown in Figure 13.3.
Figure 13.3: Example SMS Service group for a salary retrieval application
keyword = salary
aliases = Salary;SALARY
url = http://intranet.awebsite.net/cgi/salary?user=%s&password=%s&employee=%r
header = "Salary info -- "
When the Alligata Server receives an SMS message starting with the keyword 'salary' (or one of its
aliases), it replaces the first %s in url with the next word in the message after the keyword; replaces the
second %s with the next word after that; and replaces the %r with the rest of the message.
For example, if the CGI account has the user name personnel and the password STARfruit, then a
Personnel member can access the salary details of the employee Emma Thompson by sending the
Alligata Server the following SMS message:
salary personnel STARfruit emma thompson
Upon receiving this message, the Alligata Server sends the following HTTP GET request:
http://intranet.awebsite.net/cgi/salary?user=personnel&
password=STARfruit&employee=emma+thompson
When the HTTP reply arrives, the Alligata Server converts it into an SMS message or messages, and
sends it back to the Personnel member's mobile phone.
86
Chapter 13. 13 SMS Messaging
group = sendsms-user
username = colin
password = AVOcado
user-allow-ip = 10.0.0.5
max-messages = 10
split-chars = .;,
split-suffix = -cont.-
header = "Msg from Colin -- "
This configuration group allows the user colin with the password AVOcado to send SMS messages from
the IP address 10.0.0.5. As with SMS keyword services, outgoing messages that are over the maximum
length of a single SMS message can be split into several smaller messages, up to the maximum specified
in max-messages. The variables split-chars, split-suffix and header work exactly as in SMS
Service groups (see Section 13.1).
http://hostname:port/cgi-bin/sendsms? username=username& password=password &
from=sender's_number & to=receiver's_number & text=message_text
The elements in bold italic type should be replaced with the relevant information. For example:
http://localhost:13013/cgi-bin/sendsms?username=colin&
password=AVOcado&from=0999666666&to=0898999999&text=
All+sales+staff+return+to+office+immediately
The URL should contain no carriage returns and no spaces. Spaces in the message should be represented
by plus signs +.
All non-alphanumeric characters in the message text and the UDH value must be in hexadecimal format
and preceded by a percent sign %.
87
Chapter 13. 13 SMS Messaging
<html>
<head>
<title>SMS Message Sender</title>
</head>
<body bgcolor="#FFFFFF" text="#000000">
<h1>SMS Message Sender</h1>
<form name="sendsms" method="get"
action="http://localhost:13013/cgi-bin/sendsms">
<input type="hidden" name="username" value="tester">
<input type="hidden" name="password" value="foobar">
<input type="hidden" name="from" value="0999666666">
<p>
Telephone number:<br>
<input type="text" size="30" name="to">
</p>
<p>
Message:<br>
<textarea cols="25" rows="5" name="text">
</textarea>
</p>
<p>
User Data Header (optional):<br>
<input type="text" size="30" name="udh">
</p>
<input type="submit" value="Send Message">
<br>
</form>
</body>
</html>
88
Chapter 13. 13 SMS Messaging
• an OTA Configuration group, containing the settings to be sent to the client device
• a Send SMS User group, setting up a user account for sending of OTA messages
• an SMS Service group, pointing to the Alligata Server's sendota CGI application
For details of configuration groups and variables, see Section 9.
An example set of configuration groups for OTA configuration is shown in Figure 13.6.
To configure a WAP client device over the air (system administrator):
89
Chapter 13. 13 SMS Messaging
• Send a message to the Alligata Server via HTTP using the following syntax:
http://hostname:port/cgi-bin/sendota?
username=username&password=password &phonenumber=destination_phone_number
For example:
http://localhost:13013/cgi-bin/sendota?username=otauser&
password=foo&phonenumber=449999123456
The client device will receive a message containing the appropriate configuration information.
1. Send an SMS message to the Alligata Server's telephone number consisting of the keyword for the
OTA configuration service. For example, for the configuration in Figure 13.6:
ota
2. After a while, you will receive an SMS message from the Alligata Server containing the new
settings. How long this message takes to arrive depends on the capabilities and load of your SMSC.
3. Use the relevant feature of your device to add the configuration settings to your list of WAP
providers and, if required, make the new service your default one.
group = sms-service
keyword = ota
# In one line!
url =
"http://localhost:13013/cgi-bin/sendota?
username=otauser&password=GRAPefruit&phonenumber=%p"
group = otaconfig
location = "http://www.asite.net"
service = Company Home
ipaddress = 100.100.100.100
phonenumber = 01487772268
bearer = data
calltype = analogue
connection = cont
pppsecurity = off
authentication = normal
login = phoneuser
secret = barfoo
group = sendsms-user
username = otauser
password = GRAPefruit
user-deny-ip = ""
user-allow-ip = ""
max-messages = 2
concatenation = 1
90
Appendix A. Appendix: Troubleshooting Guide
If you encounter any problems while running the Alligata Server, in the first instance you should check
the log files for information. By default, the log files are held in the directory /var/log/alligata.
You can view the log files by using the UNIX less command (for example, less
/var/log/alligata/bearerbox.log). To watch a log file update while the Alligata Server is
running, press SHIFT+F from within less.
91
Appendix A. Appendix: Troubleshooting Guide
Outgoing SMS messages are not The connection to your SMSC or Check the connection to your
being sent by the Bearer Box. GSM modem is faulty. SMS Centre or GSM modem.
Ensure that the SMS Box and
SMSC groups in the
configuration file are properly set
up.
92
Appendix A. Appendix: Troubleshooting Guide
93