WMLScript

Libraries

The WAP standards provide a rich set of standard libraries as well as libraries to provide application-level security and access to telephony functions. We list theses libraries, but to use the library functions, you will need to download the "WMLScript Standard Libraries Specification" and optionally the "WMLScript Crypto Library" and "Wireless Telephony Application Interface Specification," all available from the WAP Forum's Web site.

Lang

The Lang library contains functions that directly extend the WMLScript language, including integer arithmetic, conversion from string to numeric, random number generation, and implementation-specific values (such as the maximum supported integer). To access these functions from your WMLScript code, use the Lang library prefix—for example, var smallest = Lang.min(x, y);.

Some Lang functions are listed here:

• min(x, y)—Returns the smaller of x and y (or invalid), where x and y are numbers

• max(x, y)—Returns the larger of x and y (or invalid), where x and y are numbers

• abs(x)—Returns the absolute value of the specified number x.

• isInt(s)—Returns true if s can be converted to a legal integer

• parseInt(s)—Converts the contents of s to an integer

• isFloat(s)—Returns true if s can be converted to a legal floating point number

• parseFloat(s)—Returns true if s can be converted to a legal floating point number

Float

This library contains basic floating point operations. Some devices may not be capable of supporting such operations (verify this using the Lang.float() function, which will return false if floating pont operations are not supported), in which case these functions will return invalid. Functions include those that return integers related to the specified floating point number, powers and roots, as well as implementation-specific information.

Float functions include these:

• int(n)—Truncates n, returning only the integer part

• round(n)—Rounds n to the nearest integer (rounding up if two integers are equally close to n)

• pow(x, y)—Returns the result of raising x to the power of y

• sqrt(n)—Returns the square root of n

String

String functions provide convenient operations to access and update strings. WMLScript strings can be thought of as arrays of characters, with the first character located at index 0. Functions are provided to access, modify, compare, convert to, and format strings.

Some String functions include these:

• length(s)—Returns the number of characters in s

• isEmpty(s)—Returns true if s contains no characters

• subString(s, start, length)—Returns the portion of s starting at start, which is length characters long

• charAt(s, index)—Returns the character in s at position index

URL

This library contains functions that work with absolute and relative URLs. Functions are provided that get the various parts of a URL, test validity, merge two URLs, perform escaping operations, and get the contents of a URL.

Some URL functions include these:

• getHost(url)—Returns the host (domain) portion of url (such as www.mydomain.com)

• getPort(url)—Returns the server port number of url (such as 80)

• getPath(url)—Returns the path portion of url (such as "/scripts/myScripts.wmls")

• getParameters(url)—Returns the parameters associated with the last path segment of url

• escapeString(s)—Returns a string based on s, but with the appropriate escape sequence substitutions

• unescapeString(`s')—Removes escape sequence substitutions from s, returning a new string

WMLBrowser

This library gives you access to the WML user agent context (when the WMLScript was called from WML). Most of these functions have analogs in WML, and functions are provided to manipulate variables, perform tasks, reset the context, and get the relative URL of the current card.

Functions include these:

• getVar(name)—Returns a string containing the value of name from the current browser context, or an empty string, if this variable does not exist

• setVar(name, value)—Returns true if the variable named by name containing value is successfully set in the current browser context

• go(url)—Has the same effect as the element in WML. Following completion of the WMLScript function in which the go function is called, control will return to the WML Browser and the card referred to by url will be loaded. This URL may be relative to the current deck or may be absolute.

• prev()—Has the same effect as the WML element. Following completion of the containing WMLScript function, the previous card in the WML Browser history will be loaded.

• refresh()—Has the same effect as the WML element, except that a suspended timer task will not be restarted. Refresh will occur immediately when this is supported by the device; otherwise, it will occur when control is returned to the WML Browser following script completion

The newContext() function clears the entire WMLBrowser context, including all variables and the card history stack. This task returns an empty string if it is successful and returns invalid if it is not.

Dialogs

The Dialogs library provides common user interface functions:

• prompt(message, default)—Displays message and the default response, and returns the user's response as a string, as in Dialog.prompt("Number of children: ", "0");.

• confirm(message, ok, cancel)—Displays message and offers two options as defined in ok and cancel, as in Dialog.confirm("Is that your final answer?", "Yes", "No");. This returns Boolean true if the user selects ok and returns false if the user selects the cancel option.

• alert(message)—Displays message and waits for the user to confirm before returning an empty string.

Crypto

The Cryptographic Library Specification currently supports digital signatures. Although the Wireless Transport Layer Security (WTLS) standard provides for client authentication during a session, the Crypto library adds a way to provide a lasting record of a user transaction. This is useful when there must be a fool-proof way to determine that a user has approved a particular transaction (as in the purchase of goods or services).

The signText function requests that the user digitally sign a specified string. A special digital certificate is used for this. This may be stored on a smart card in the mobile device (or a SIM card, as used in some GSM handsets). The user is presented with the text that is to be signed and must explicitly indicate acceptance and enter a secret PIN. The function then signs the text using the user's private key. Typically, the digital signature created by this, as well as the original text, will be used by a server to validate the transaction; the signature may be stored for later reference.

The signText function has this format:

Crypto.signText(s, instructions, keyIdType, keyId) 

The parameters are as follows:

• s is the string that will be displayed to the user and used to create the digital signature.

• instructions is an integer that instructs the browser to return information in addition to the signed text.

• keyIdType is an integer code that specifies which key should be used.

• keyId is a string that contains one or more (concatenated) Secure Hash Algorithm (SHA-1) hashes if the keyIdType parameter is set to 1 or 0.

Note that this function may not be supported on many wireless devices because it requires some form of personalized locally stored security information (such as a Wireless Identity Module, or WIM) to be accessible to the WML Browser.

WTA Public

The Wireless Telephony Application interface provides functions to create telephony applications. Only one library in this interface is available for use by general WML decks or other WMLScript functions: the Public library. The Public library is identified by wp when called from WML and by WTAPublic when called from WMLScript functions.

When calling the Public library from WML, a special URI format is used, as follows:

wtai://wp//functionName; parameters [!result]  

Here, wtai identifies the Wireless Telephony Application Interface, wp is the Public library, and functionName is either mc to make a call, sd to send a Dual Tone Multi-Frequency (DTMF) tone sequence, or ap to add a number to the phone book. Parameters are passed for all these functions, following a semicolon separator, and an optional variable name can be specified preceded by an exclamation mark (!). When calling the public library from WMLScript, a standard library function call is used, such as WTAPublic.functionName(param1, param2);. The function output is returned as a result of the function call.

Telephone numbers and DTMF digits used in telephony calls must be formatted as follows. International phone calls are prefixed by the plus (+) sign. All phone numbers simply consist of a string of ASCII digits (0 to 9), with no spaces or separators. DTMF digits may contain any combination of the following characters: *, #, A, B, C, D, ,, and 0 to 9.

The Public WTA library supports the following:

• makeCall(number)

• SendDTMF(tones)

• addPBEntry(number, name)

The result of these functions is zero if valid and negative if an error has occurred.

Note that not all phones support the WTA. For example, the Nokia 7110 requires that you use the "Use Number" function (a mechanism borrowed from SMS) to dial a number.

That concludes our discussion of libraries. The next sections illustrate the use of both WMLScript and the library functions through a series of examples.