MANUAL WIB
User Manual:
Open the PDF directly: View PDF 
.
Page Count: 54
| Download | |
| Open PDF In Browser | View PDF |
Developer’s Guide Development of Wib Services – Universal Gateway and Wireless Service Management Document number: 90-291 Revision: 1.9 2011-06-15 © 2011 Giesecke & Devrient 3S AB. Proprietary/Confidential. All rights reserved. Developer's Guide, Development of Wib Services Universal Gateway and Wireless Service Management Contents 1 Introduction _______________________________________________________ 4 2 References ________________________________________________________ 5 3 Definitions and abbreviations _______________________________________ 6 4 Background _______________________________________________________ 7 4.1 Use cases................................................................................................ 7 4.2 Wib ........................................................................................................ 8 4.2.1 User interaction ........................................................................... 8 4.2.2 Execution model .......................................................................... 9 4.2.3 Variables .................................................................................... 11 4.2.4 “Wait-for-response” state......................................................... 12 4.2.5 Events ......................................................................................... 12 4.2.6 Timers ......................................................................................... 14 4.2.7 Plug-ins ...................................................................................... 14 4.2.8 Error handling ........................................................................... 15 4.3 Wiblet .................................................................................................. 15 4.3.1 Installed wiblets......................................................................... 16 4.4 Wib services ......................................................................................... 16 4.4.1 Installed Wib services ................................................................ 16 4.5 DP and the UG .................................................................................... 17 4.5.1 WIG WML ................................................................................... 17 4.5.2 Communication via SMS ........................................................... 17 5 Robust WIG WML design __________________________________________ 19 5.1 Splitting text ....................................................................................... 19 5.2 Alphanumeric passwords ................................................................... 21 5.3 Text Size in Select element ................................................................. 21 5.4 STK Limitations in the mobile phone ................................................ 21 6 WIG WML how-to _________________________________________________ 23 6.1 Coding style ........................................................................................ 23 6.2 Closing Card element stops wiblet .................................................... 24 6.3 Jumping as the result of a selection .................................................. 25 6.4 Using icons .......................................................................................... 26 6.5 Retrieving event specific information ............................................... 26 6.6 Static URL references .......................................................................... 27 6.6.1 Static URL References in WIG WML .......................................... 27 6.7 Changing the Wib operational mode................................................ 28 6.8 Addressing installed wiblets .............................................................. 29 6.9 Using executewiblet (Wib 2.0 and later) ........................................... 31 -2- Developer’s Guide Developer's Guide, Development of Wib Services Universal Gateway and Wireless Service Management 6.10 WIG WML examples.......................................................................... 31 7 Some additional UG features_______________________________________ 35 7.1 Caching................................................................................................ 35 7.2 Cookies ................................................................................................ 35 7.3 Sending SMs ........................................................................................ 35 7.4 Tariff class ........................................................................................... 36 Appendix A WIG WML v5 migration guide _________________________ 38 Appendix B WIG WML migration guide ____________________________ 39 Appendix C Error codes ___________________________________________ 43 Appendix D Wib compatibility information _________________________ 46 Appendix E WIG compatibility information ________________________ 50 Appendix F WIG WML FAQ _______________________________________ 52 -3- Developer’s Guide Developer's Guide, Development of Wib Services Universal Gateway and Wireless Service Management 1 Introduction The purpose of this document is to provide guidelines and help to developers of Wib services. The document comes as a complement to the WIG WML specification (see WIG WML Specification – Version 5 [7]), and is specifically aiming to empower Wib services developers to create services that are robust with regard to variable aspects such as mobile phone capabilities etc. utilize Wib and DP capabilities to the maximum are well written and maintainable are user friendly This document is derived from an original document, that was made obsolete in DP 6.1, – “WIG Application Guidelines, Delivery Platform 6.0”. That document was then replaced by “Guidelines – Development of Wib Services – Delivery Platform 6” which was considerably rewritten with a clear focus on the needs of the Wib service developer. The current document is an updated version of that document. The document may not be used for any other purposes than the ones described above. Specifically, it may not be used as a source of information when implementing Wib. -4- Developer’s Guide Developer's Guide, Development of Wib Services Universal Gateway and Wireless Service Management 2 References [1] 3GPP. TS 23.040. Technical realization of the Short Message Service (SMS). Version 5.1.0 (2001-09). Available: http://www.3gpp.org/ [2] Ericsson Mobile Communications AB. Enhanced Messaging Service – White Paper. April 2001. Publication nr. LZT 108 4854 R1C. Available: http://www.ericsson.com [3] ETSI. GSM 11.14. SIM Application Toolkit (SIM-ME) Interface. Version 8.5.0. Release 1999. [4] Nokia. Smart Messaging Specification. Rev3.0.0. 2000-12-18. Available: https://secure.forum.nokia.com/ [5] Universal Gateway Request Protocol – Interface Specification. G&D SmartTrust. [6] Universal Gateway Push Request Protocol – Interface Specification. G&D SmartTrust [7] WIG WML v5 – Specification. G&D SmartTrust. [8] SmartTrust Wib™ Plug-ins – Specification. G&D SmartTrust. [9] Sony Ericsson, et al. How to Create EMS Services. Version 1.2 September 2002. Available: http://www.ericsson.com/ [10] Sony Ericsson. Enhanced Messaging Service (EMS) – Developers Guidelines. September 2002. Publication nr. EN/LZT 108 5256 R2A. Available: http://www.ericsson.com [11] Wireless Application Protocol Forum. WAP Billing Framework. Prototype Version 7 Aug 2001. -5- Developer’s Guide Developer's Guide, Development of Wib Services Universal Gateway and Wireless Service Management 3 Definitions and abbreviations Acronym CGI DP EMS HTML NSM STK SMS SM UG (U)SIM URL WAP Wib Wib command wiblet WIG WIG WML v3 WIG WML v4 WIG WML v5 WML Definition Common Gateway Interface G&D SmartTrust Delivery Platform Enhanced Message Service HyperText Markup Language Nokia Smart Messaging SIM Application Toolkit Short Message Service Short Message Universal Gateway (Universal) Subscriber Identity Module Universal Resource Locator Wireless Application Protocol SmartTrust Wib™ The smallest executable unit in Wib. A program that may be executed in the Wib runtime platform. Wireless Internet Gateway WIG WML version 3. Supported by all version of DP. Sometimes referred to as “Old WML”. WIG WML version 4. Supported by DP 6.1. WIG WML version 5. Supported by DP 8.0. Wireless Markup Language -6- Developer’s Guide Developer's Guide, Development of Wib Services Universal Gateway and Wireless Service Management 4 Background This section aims at presenting concepts and terminology which are fundamental to the understanding of a Wib service as well as the environment in which Wib services are developed and deployed. 4.1 Use cases The following use-cases are the two basic use cases of Wib. Wib Request In this use case, the end-user brings up the Wib menu and selects one of the menu items. The selection will invoke a locally installed wiblet which eventually sends a request to the UG. The Wib request contains binary data. DP (UG) receives the request and interprets its contents as a URL and possibly also a query string and translates it into a standard HTTP GET or POST request. The MSISDN of the originating mobile phone may optionally be attached by DP at the end of the HTTP request as a query parameter. The HTTP request is then sent to the content provider Web server, which normally responds with a WIG WML document. The UG compiles the document into a wiblet and sends it to the waiting Wib, which completes the loading and starts executing the dynamically incoming wiblet. For details of the HTTP communication between the UG and the content provider Web server, see reference [5]. Wib Push Request In this use-case the sequence of actions is initiated from the content provider side, and the end-user might not even be aware of that he or she will soon be involved in a Wib service. The first action is when the content provider web server, or some other entity at the content provider side, sends a push message to the UG. This message contains information about the recipient(s) MSISDN as well as a WIG WML document. The UG compiles the WIG WML document into a wiblet and forwards the wiblet to the recipient‟s Wib, which executes the wiblet. Optionally, the originator of the push message may also get confirmation that the wiblet was successfully delivered to Wib. For details of the HTTP communication as well as the WAP Push Access Protocol used in this use-case, see reference [6]. -7- Developer’s Guide Developer's Guide, Development of Wib Services Universal Gateway and Wireless Service Management 4.2 Wib Wib is an execution platform for executing special programs known as wiblets. As such, Wib provides an interpretation environment and acts as a virtual machine for wiblets. A wiblet is a sequence of Wib commands that may be executed by Wib. Section “Wiblet” on page 15 presents wiblets in more detail. Wiblets can interact with the user. Wib was originally designed as a flexible way of offering STK applications. Therefore a significant number of the commands offered by Wib have a direct counterpart in the STK command set, defined in GSM 11.14 [3]. As an example, there are Wib commands like “Display Text”, “Send SM” and “Set Up Call”, to mention a few. Nevertheless, many Wib commands are unrelated to STK and offer functions that are internal to Wib, extending the capabilities of Wib far beyond what STK offers. Together, these groups of Wib commands span over functionalities such as data communication, program flow, user interaction and data conversion. Over the years, several versions of Wib have emerged: (Wib 1.0 – Year 1999, prototype version) Wib 1.1 – Year 2000 Wib 1.2 – Year 2001 Wib 1.3 – Year 2003 Wib 2.0 – Year 2009 It is important to note that the different Wib versions are always backward compatible. This means that features supported in Wib 1.1 are also supported in the same way by more recent Wib versions. The reverse is obviously not true, and therefore this document always tries to point out if a certain feature described in the text or by WIG WML in an example, is not supported by all Wib versions. Appendix D summarizes the differences between the Wib versions released to date. 4.2.1 User interaction Wib is not equipped with any device for user interaction, like a screen or a keyboard. Instead Wib relies on the mobile phone to perform this task. Thus, for Wib to interact with a user properly, the mobile phone shall provide the following features. A screen capable of displaying text and optionally also icons. -8- Developer’s Guide Developer's Guide, Development of Wib Services Universal Gateway and Wireless Service Management A keyboard for entering text and digits. Buttons for navigation: Cancel button; used to terminate the wiblet execution. OK button; used to select a choice or acknowledge the information on the screen. Backward move button; used to restart the currently executing wiblet, clearing all the variables. If the wiblet is already at the start position, the execution will stop. A tone-generator (not strictly required) 4.2.2 Execution model An in-depth discussion of the execution model of Wib falls outside the scope of this document. Still, some basic facts are required to fully understand the behavior of Wib in certain situations. In the state diagram below, the solid boxes represent the different states that Wib may occupy and the arrows represent transition between the states due to some action which is indicated beside the arrow. Menu selection Event Incoming WIBlet Timer expiration Exit handler installed Executing Cancel button1 WIBlet terminates normally1 Idle Error processing complete Error1 Error handler installed Error WIB request op. mode = PULL or Incoming WIBlet forced “Wait-forresponse” Repeated menu selections Wait-forresponse -9- Developer’s Guide Developer's Guide, Development of Wib Services Universal Gateway and Wireless Service Management 1 With Wib2.0 there is a possibility to start execution of another installed wiblet or show the main menu both on normal exit and if an error occurs. In this case Wib remains in the Executing state and does not transit to Error state or Idle state respectively The “Error” and “Wait-for-response” states are described in more detail later in this document. The “Executing” state is where Wib is busy actually executing a wiblet. In may be seen in contrast to the “Idle” state when Wib is doing nothing. The transition from “Idle” to “Executing” state due to a “Menu selection”, “Event” or “Timer expiration” action, requires the wiblet to be installed in Wib in order to be executed. An “Incoming wiblet” action starting from the “Idle” or “Wait-for-response” state leads to execution of the incoming wiblet, which has in this case been dynamically loaded from the content provider. Wib enters “Wait-for-response” state based on a set of rules. The most important rule to know for a Wib service developer, is that “Wait-for-response” state is entered based on the so called Wib operational mode. The operational mode is determined by how the currently executing wiblet was invoked. If it was invoked via a Wib menu selection, the operational mode is PULL. Conversely, if it was invoked by a Wib push and thereby coinciding with the “Wib push” use-case described in section 4.1 , the operational mode is PUSH. The operational mode determines the default behavior of Wib when it sends a Wib request to the content provider. The below describes the default behavior for the PULL and PUSH modes. PUSH mode – After sending a request to the content provider, Wib will continue execution of the current wiblet with the next Wib command. It will not wait for a response. PULL mode – After sending a request to the content provider, Wib will halt execution of the current wiblet and enter the “Wait-for-response” state. This also leads to that all Wib commands following the command that caused “Wait-for-response” to be entered, will not be reached by the wiblet execution. - 10 - Developer’s Guide Developer's Guide, Development of Wib Services Universal Gateway and Wireless Service Management If the above described logic does not fit with the desire of the Wib service developer, the operational mode may be changed using the WIG WML element setreturntarvalue. In Wib 1.3 and later, it is also possible to explicitly control whether Wib should enter the “Wait-for-response” state or not, through the go:enterwait attribute. For an WIG WML example how to manipulate the operational mode, refer to section “Changing the Wib operational mode” on page 28. 4.2.3 Variables Wib has a reserved area of memory where variables may be written to or read from as Wib executes a wiblet. The most common way of setting a variable in Wib is through the WIG WML elements setvar, select or input. Reading a variable occurs automatically whenever the variable is referred to by name. In WIG WML, variables can be given names describing their use like $(PRICE) or $(IMEI). When this is compiled to a wiblet, variables are identified through numerical identifiers commonly known as variable IDs. Variables come in two different flavors linked to their maximum persistence in Wib: Local variables are variables that are created during the execution of a wiblet and deleted automatically when the same wiblet stops executing. Local variables occupy variable IDs in the range '00'h to 'DF'h. This variable type is supported by all Wib versions. Global variables are variables that can be persistent throughout the execution of multiple wiblets. Their maximum life-length is limited by SIM reset, normally caused by a ME power-off. Global variables are cleared when the following WIG WML elements are executed:Global variables are also cleared when Wib abnormally terminates execution of a wiblet. That may happen when a user has pressed 'cancel' or when an error has occurred. In Wib 2.0 and later it is possible to install an exit handler with the WIG WML element handleexit. With this element it is possible to configure to not clear the global variables on error exit. - 11 - Developer’s Guide Developer's Guide, Development of Wib Services Universal Gateway and Wireless Service Management Global variables are intended primarily for passing data to and from wiblets, and are supported by Wib 1.3 and later. The amount of memory available to variables is limited in all versions of Wib. Wib 1.1 and Wib 1.2 – Support for up to 252 variables in each wiblet and a maximum variable size of 255 bytes. The total size of the variable area is manufacturer specific. Wib 1.3 – Support for up to 252 variables in each wiblet and a maximum variable size of 255 bytes. The guaranteed size of the variable area is at least 1000 bytes for 30 variables. Wib 2.0 – Support for up to 252 variables in each wiblet and a maximum variable size of 8191 bytes. The guaranteed size of the variable area is at least 1000 bytes for 30 variables. 4.2.4 “Wait-for-response” state The purpose of the “Wait-for-response” state is to provide a user friendly waiting-period after Wib has stopped executing a wiblet and the next wiblet is being loaded. User friendly means that Wib should give the end user clear guidance what is actually going on, and provide updated progress information as frequently as possible. Different Wib versions succeed differently well to achieve this goal: Wib 1.1 and Wib 1.2. Wib falls back to showing the Wib menu, which is not very user friendly since the end user may easily think that the wiblet execution has stopped. Wib 1.3 and later. Wib provides textual and graphical (icon) information on the screen of the mobile phone in three different phases. When the request is sent from Wib. In the intermediate phase after sending the request but before reception of the response has started. When Wib is receiving the response. The textual information is modifiable by the Wib service developer. The “Wait-for-response” state also provides an opportunity to cancel the “Wait-for-response” state and force Wib back to the “Idle” state by repeated menu selections from the Wib menu. 4.2.5 Events Wib 1.2 and later versions support invocation of installed wiblets through a mechanism known as events. An event - 12 - Developer’s Guide Developer's Guide, Development of Wib Services Universal Gateway and Wireless Service Management Event MT call Call connected Call disconnected Location status User activity Idle screen available Card reader status Language selection Browser termination Data available Channel status Access Technology Change Display parameters changed Local connection Network Search Mode Change Browsing status Frames Information Change can be generated by the mobile terminal as defined in STK or be internally generated on the card. In both cases, the event will trigger Wib to look for a configured wiblet to be executed as a consequence of the event. If no wiblet is configured, Wib will not invoke any wiblet. When a wiblet is invoked due to an event, Wib will optionally set one or possibly two variables to values that are associated with the event, so that additional information may be propagated to the invoked wiblet. The following table shows events mapped to affected variables and what data they hold. Variable id and the data to be stored „90‟h: Address of calling line identity „91‟h: Called party subaddress „90‟h: Device identities „90‟h: Device identities „91‟h: Cause of disconnection „90‟h: Location status „91‟h: Location information „90‟h: Card reader status „90‟h: Language selection „90‟h: Termination cause „90‟h: Channel status „91‟h: Channel data length „90‟h: Channel status '90'h: Access technology '90'h: Display parameters '90'h:Service Record '91'h: Remote Entity Address '92'h UICC/terminal interface transport level '93'h: Remote entity transport level address '90'h: Network search mode '90'h: Browsing status '90'h: Frames information - 13 - Developer’s Guide Developer's Guide, Development of Wib Services Universal Gateway and Wireless Service Management I-WLAN Access Status Event Start-up Network Available Incoming Cell Broadcast Message Country Change Network Change '90'h: I-WLAN Access Status For more information regarding these events, please consult GSM 11.14 [3]. Wib 1.3 adds a new event, the Start-up event, to the list above. This event is sent to Wib when the (U)SIM has finished initializing after a power-up or reset. Wib 2.0 adds four new events. The Wib specific events can be found in the table below. Additionally, a separate event specification that defines additional events is available. Variable id and the data to be stored '90'h: Location information '90'h: Cell broadcast header data '91'h: Cell Broadcast message '90'h: Location Information '90'h: Location Information 4.2.6 Timers From version 1.3, Wib is equipped with 8 timers that may be utilized by the Wib service developer. A timer can be thought of as a clock that can be set to alarm at a certain time into the future relative to the present time. In other words it functions as a count-down. When the timer fires, Wib executes an installed wiblet specified when the timer was started. Since the actual work is performed by a wiblet, it is up to the Wib service developer to decide the use-case for timers. Typically it may be used for periodic tasks like monitoring or periodic retrieval of information. 4.2.7 Plug-ins In addition to the built-in Wib commands, Wib offers an extension mechanism known as plug-ins. This mechanism enables access to functionality which is not part of the standard Wib command set and that can be added at a later stage. Wib 1.3 and later even supports downloading and installing new plug-ins over-the-air. Currently there are around 30 standard plug-ins defined by SmartTrust, mainly covering functionality in the area of security and data retrieval. For a detailed description of these plug-ins and examples how they are used, refer to [8]. - 14 - Developer’s Guide Developer's Guide, Development of Wib Services Universal Gateway and Wireless Service Management 4.2.8 Error handling Occasionally an error situation arises where Wib has no other option than to prematurely abort the wiblet execution. As the last action before it stops, Wib will display an error code and possible also an error-message on the screen of the mobile phone, with information what caused the error. Most likely this situation will be confusing to the end user if it occurs in a “live” Wib service. Therefore it is very important to test Wib service thoroughly before they are deployed in order to remove as many potential errors as possible. As a means of debugging a Wib service, the error codes are useful. Appendix C lists the different error codes along with associated error messages. Wib 2.0 and later offers the possibility to start execution of another installed wiblet or show the main menu in case an error occurs. The WIG WML element handleexit is used to configure this behavior. 4.3 Wiblet As described earlier, a wiblet is a sequence of Wib commands. It is important to note that a wiblet is not the same as a WIG WML document. The relation between WIG WML and wiblet is similar to the relation between source code and object code observed in almost any system for program development. The source code (WIG WML) is compiled into object code (wiblet) which is understood by a computer, in this case Wib. The compilation from WIG WML to wiblet is always carried out by DP in some way or another, with the UG as the foremost example. The fact that a wiblet is actually object code that Wib executes may seem obvious when described in this context. Still, it has subtle implications on the way Wib services should be designed, since WIG WML is more of a “pagedescription” language in the spirit of HTML and WAP WML where the notion of linear program order is suppressed in favor of a more tree-like view. - 15 - Developer’s Guide Developer's Guide, Development of Wib Services Universal Gateway and Wireless Service Management 4.3.1 Installed wiblets The term installed wiblet is used throughout this document to indicate that a wiblet is stored locally in Wib, prior to the moment when it is executed. In other words, loading is not required. It should be seen in contrast to the term dynamically loaded wiblets, which is used to express that a wiblet is loaded from the content provider before it is executed. 4.4 Wib services A Wib service may be perceived in different ways depending on the point-of-view: From Wib point-of-view, it is a one or more wiblets that may be executed in Wib. From an end-user point-of-view, it is the collective experience created by repeated interactions with Wib in order to reach a certain goal. Using this rather vague “definition” it is not always easy to know when transition between Wib services occurs. From a service development point-of-view, it is mainly a collection of WIG WML documents, CGI scripts and related data residing on a Web server, together forming the application. All these attempts to capture the nature of a Wib service should be taken rather informally, since they all omit information that is not so easily categorized. 4.4.1 Installed Wib services Holding on to the view that a Wib service is a collection of wiblets, it is possible to install a Wib service, in parts or as a whole. The main reason for installing parts of a Wib service is to reduce the total loading time of the service and possibly also reduce over-the-air traffic. In some cases all pieces of a Wib service may be installed in Wib, even if that is not the most common case. If part of the Wib service is installed and part of the Wib service is loaded dynamically, certain limitations related to transition between wiblets arise. - 16 - Developer’s Guide Developer's Guide, Development of Wib Services Universal Gateway and Wireless Service Management Wib 1.1 and Wib 1.2. A Wib Service may have its starting point in a installed wiblet, but once transition occurs to a wiblet loaded dynamically, there is no way of “getting back” to the installed wiblet without the enduser restarting the Wib service. Wib 1.3 and later. Wib services may be designed so that transition between installed and dynamically loaded wiblets can occur in both directions without restrictions. Wib 2.0 and later. With Wib 2.0 there is the possibility to launch a wiblet stored in a variable. 4.5 DP and the UG DP offers a versatile environment for developing and deploying Wib services. It hides from the Wib service developer many of the complex issues related to the GSM network, such as over-the-air security, formatting of SMS messages and SMS-C protocols. Instead the Wib service developer is offered, through the UG, a Web based interface which should be reasonably familiar to developers that have at some point developed Web based applications. 4.5.1 WIG WML The principal language used to develop Wib services is WIG WML, which is also the application language supported by the UG. Initially WIG WML was aligned with WAP WML, but from version 4, which is supported by DP 6.1 and later it has evolved into a language in its own right. WIG WML 5, which is supported by DP8 and later, was introduced to make use of the new Wib 2.0 commands. Appendix F covers frequently asked questions concerning the rationale behind WIG WML, while Appendix B covers migration of Wib services written in an earlier version of WIG WML to version 4 and 5. 4.5.2 Communication via SMS Even if the over-the-air communication aspects are hidden from the Wib service developer, some preconditions should be pointed out. - 17 - Developer’s Guide Developer's Guide, Development of Wib Services Universal Gateway and Wireless Service Management The Short Message Service (SMS) which is used to send data to Wib is a narrow-band communication channel by today‟s standards. Each SM can hold around 120 bytes of service (wiblet) data. If the payload exceeds this limit, it will be split into two or more SMs. The delay experienced by the end-user accessing the Wib service will increase with the number of SMs required to send a complete wiblet to Wib. There is also a fixed limit to how many SMs that may be consumed by a single wiblet if the wiblet is loaded dynamically. Wib 1.1 and Wib 1.2. 5 SMs from the content provider to Wib and 3 SMs from Wib to the content provider. Wib 1.3. 7 SMs from the content provider to Wib and 5 SMs from Wib to the content provider. Wib 2.0. 9 SMs from the content provider to Wib and 5 SMs from Wib to the content provider. - 18 - Developer’s Guide Developer's Guide, Development of Wib Services Universal Gateway and Wireless Service Management 5 Robust WIG WML design This section deals with a number of constraints related to the mobile phone and the SIM card that must be kept in mind when developing a Wib service. 5.1 Splitting text When working with WIG WML documents containing text, it is important to understand that there is a limit for how many characters the mobile phone can display at the same time. The limit differs between different SIM card manufactures and mobile phones vendors, but it is usually between 110 - 140 characters. If a text contains more characters than the display limit, the UG will impose a split of the text when the document is compiled to a wiblet. The text will then be contained in two or more consecutive screens on the mobile phone, regardless of how the text is constructed. The developer may take control over this process by splitting the text manually using several p elements in succession in the WIG WML document. This is the recommended way of dealing with long texts since the outcome is now under the control of the developer. In the two examples below, the display limit has been set to 110 characters. The doctype has changed in WIG WML v5, see “WIG WML v5 migration guide” on page 38. Example [1] The following WIG WML document will trigger the “autosplit” feature of UG to handle the text. Result: - 19 - Developer’s Guide Developer's Guide, Development of Wib Services Universal Gateway and Wireless Service Management This sentence has too much text and could not be displayed at the same time on the mobile phone. Because of The user must press the Yes button. this, the text has been split into two paragraphs. OK? Yes No Yes No Example [2] Here the WIG WML document uses two This sentence has too much text and could not be displayed at the same time on the mobile phone. Because of this, the text has been split into two paragraphs.
tags to handle the text.
Result: This sentence has too much text and could not be displayed at the same time on the mobile phone. The user must press the Yes button. Because of this, the text has been split into two paragraphs. OK? Yes No Yes - 20 - No Developer’s Guide Developer's Guide, Development of Wib Services Universal Gateway and Wireless Service Management 5.2 Alphanumeric passwords Some mobile phones do not allow the use of the input:type="password" attribute together with alphanumeric input. Thus, for the type="password" to work on all mobile phones, it has to be used together with format="*N" which indicates numerical input. Example [3] 5.3 Text Size in Select element The select element may only be used with a limited number of characters. The sum of all character displayed on some mobile phones, that is the title plus the text in each option, may not exceed 110 characters. Example [4] This sentence have too much text and could not be displayed at the same time on the mobile phone.
Because of this, the text has been split into two paragraphs.
In this example the number of characters is ("Colour" = 6) + ("Blue" = 4) + ("Red" = 3) + ("Yellow" = 6) = 19. The select:title attribute is unfortunately displayed in many different ways and sometimes not at all, depending on the mobile phone manufacturer. Wib and/or the UG configuration also puts limitations on how much information (i.e. select:title, option text, option:value and option:onpick URLs) you can totally have within one select element. It is advisable to try to keep the total length of all the information as short as possible to ensure proper operation for all configurations. 5.4 STK Limitations in the mobile phone Many Wib functions lead to STK functions. Some of these have traditionally had a varying level of support in the mobile terminals. Example of such functions are listed below. - 21 - Developer’s Guide Developer's Guide, Development of Wib Services Universal Gateway and Wireless Service Management Icons (Wib 1.3) Events (Wib 1.2) Timers (Wib 1.3) Launch browser (Wib 1.2) Execute STK (Wib 2.0) When developing a Wib service that builds on one of these features, it is inevitable that the service will fail on some mobile phones. This fact must be considered by the service developer, and weighted against the value gained by using the feature(s). For icons and event usage, the failure shall be soft, meaning that nothing will happen on the device. The usage of timers and launch browser may trigger an error on a terminal that does not support them. Therefore, the Wib service should use the checkterminalprofile element to handle the case properly. Testing may reveal to what extent a Wib service works on different mobile phones. - 22 - Developer’s Guide Developer's Guide, Development of Wib Services Universal Gateway and Wireless Service Management 6 WIG WML how-to 6.1 Coding style Because of the limitations pointed out in section “Communication via SMS” on page 17, it is desirable to design a Wib service in such a way that the number of SMs required in the SMS communication is kept to a minimum. The following provides some general recommendations for achieving this. Small WIG WML documents are better that big Short URL‟s are better that long Exploit the use the static URL references to reduce the wiblet size. These can be regarded as compressed server-side bookmarks and also provide value in creating a more dynamic environment. See section 6.6 for details. Simple logic is better that complex Make dynamically loading of a wiblets occur in places where it seems natural from an end user point-of-view, and thereby causing least annoyance. Use Wireless Application Creator, supplied by SmartTrust, to analyze and optimize the wiblet size. UG supports caching of WIG WML documents. This may be utilized by the Wib service developer to reduce wiblet loading time. Avoid repeating text strings within the same WIG WML document. Instead use variables wisely. The Wib 1.3 function enabling calling locally stored wiblets as subroutine can provide great improvement in user experience. Wisely used bookmarking can provide the end-user with shortcuts into often used functions. Learn how to design compact end-user dialogs without sacrificing usability. In fact, using too many words on a small display has a negative impact on comprehension. The last recommendation is a very important one, since designing a Wib service requires a somewhat different mind-set than when designing an ordinary web application where screen size and bandwidth are issues of minor importance. - 23 - Developer’s Guide Developer's Guide, Development of Wib Services Universal Gateway and Wireless Service Management 6.2 Closing Card element stops wiblet The wiblet execution will stop when a closing card element is encountered. Jumping between cards is possible using a card reference in the go:href attribute. The examples below illustrate the two cases: Example [5] In this example only the text "Hi!" is displayed since Wib stops after the first card.
Example [6] In this case both "Hi!" and "Hi again!" are displayed since Wib will jump to the next card in the document. Hi!
Hi again!
- 24 - Developer’s Guide Developer's Guide, Development of Wib Services Universal Gateway and Wireless Service Management 6.3 Jumping as the result of a selection The option:onpick attribute is very powerful since it allows three types of “jumps” to occur as the result of a selection. Example [7] This example shows how to jump to a card depending on the selection. Hi!
Hi again!
.
. .. Example [8] This example shows how to load and execute a new wiblet depending on the selection.Example [9] Compatibility note: This example is only applicable for Wib version 1.3 or later. This example shows how to execute an installed wiblet depending on the selection. - 25 - Developer’s Guide Developer's Guide, Development of Wib Services Universal Gateway and Wireless Service Management
6.4 Using icons Compatibility note: This section is only applicable for Wib version 1.3 or later. To be able to use icons in a Wib service, the following tasks must be accomplished first: The SIM card must have icon data installed. Exactly how this is performed is outside the scope of this document. The Wib service developer must be provided with a list of installed icons and the icon identifier for each of them. When icons are in place in the SIM, actually using them from WIG WML is rather straightforward. Example [10] In this example, an icon is displayed alongside with the text “Icons are cool!!”.
6.5 Retrieving event specific information Compatibility note: This section is only applicable for Wib version 1.2 or later. To be able to read variables set by Wib when an event occurs, a special syntax must be used where the variable ID is specified as part of the variable name. Example [11] - 26 - Developer’s Guide Developer's Guide, Development of Wib Services Universal Gateway and Wireless Service Management Icons are cool!!
6.6 Static URL references This feature allows the UG operator to predefine a set of URLs that are often used and store them permanently in the UG. Instead of sending the full URL back and forth between the UG and Wib, only a reference ID is sent thus reducing the wiblet size and minimizing the number of SMs over the air interface. Static URL references may be used in installed wiblets as well. Also, using static URL references instead of full URLs makes is possible to change the URL, or even change between HTTP and HTTPS, for dynamically loaded wiblets, without updating any of the installed wiblets. The figure below illustrates a scenario where Wib sends a request containing a static URL reference to the UG. Originally, the static URL reference was specified in a WIG WML go:href attribute like this: MT Call Event Ocurred.
Address: $(ADDRESS:IDx90)
Subaddress: $(SUBADDRESS:IDx91)When the UG receives the request, it looks up "myref" in the database and constructs the full URL. Then it handles the URL as if it was received directly from Wib. "myref" = "http://myhost/test.asp?a=" !myref!b http://myhost/test.asp?a=b WIG Web Server 6.6.1 Static URL References in WIG WML In WIG WML, the static URL reference is indicated in a URL with a leading ! character followed by the reference ID and another ! character. E.g.: - 27 - Developer’s Guide Developer's Guide, Development of Wib Services Universal Gateway and Wireless Service Management Only one static URL reference is allowed per URL, and the static URL reference has to be first in the URL. Variables are not supported in a static URL reference. Example [12] This example illustrates the use of static URL references. 6.7 Changing the Wib operational mode As described earlier in this document, it is possible to change the operational mode of Wib through the setreturntarvalue element. Changing the operational mode affects how Wib behaves upon sending a Wib request. Note that for Wib 1.3, the “Wait-for-response” state can be controlled explicitly through the go:enterwait attribute. Example [13] In this example, Wib is forced into PUSH operational mode through the setreturntarvalue element, which will prevent Wib from entering the “Wait-for-response” state when executing the go element. - 28 - Developer’s Guide Developer's Guide, Development of Wib Services Universal Gateway and Wireless Service Management
Example [14] In this example, Wib is forced into PULL operational mode through the setreturntarvalue element, which will cause Wib to enter “Wait-for-response” state after executing the go element.
6.8 Addressing installed wiblets As described earlier in this document, installed wiblets can be invoked from other wiblets. For that purpose, a wiblet Uniform Resource Identifier (Wiblet-URI) is used to identify the installed wiblet. See [7] for details. To define a wiblet-URI for a wiblet is optional, and it is only needed if the wiblet is to be called by other wiblets or by timer expirations. The process of choosing the wibletURI for a wiblet, is something that involves the DP operator. The wiblet-URI must be unique within a DP installation. - 29 - Developer’s Guide Developer's Guide, Development of Wib Services Universal Gateway and Wireless Service Management Example [15] The wiblet-URI is specified for a wiblet in WIG WML according to this example. The wiblet-URI of this wiblet is “wiblet://smarttrust.com/demo/myApp”, and if it is installed it can be invoked from other wiblets.
Example [16] This wiblet illustrates how the wiblet in Error! Reference source not found. can be addressed. This wiblet could be installed or it can be dynamically loaded. This service may be invoked by another service by specifying wiblet://smarttrust.com/demo/myApp as wiblet-URI.
- 30 - Developer’s Guide Developer's Guide, Development of Wib Services Universal Gateway and Wireless Service Management 6.9 Using executewiblet (Wib 2.0 and later) Wib 2.0 introduces the feature to launch wiblets stored in a variable. When using the WIG WML element executewiblet, care has to be taken in which variable the wiblet is stored. It is strongly recommended to store the wiblet in a global or a stack variable. Using this practice, the application programmer can make sure that the variable that the called wiblet is running in is not modified by the running wiblet itself. This example shows a wiblet that is making an USSD request and the answer is a wiblet stored in stack variable 1. The received wiblet is then executed. This wiblet will now invoke an installed wiblet.
6.10 WIG WML examples This section contains a number of WIG WML examples to show some basic constructs for a Wib service. Example [17] This example illustrates navigation between cards within a WIG WML document. - 31 - Developer’s Guide Developer's Guide, Development of Wib Services Universal Gateway and Wireless Service Management
Example [18] This example illustrates use of the playtone element. The phone shall play a dial tone during 3 seconds and the text "Tone!" will be displayed at the same time. Card selection example.
Now you’re in CARD1.
Now you’re in CARD2.
Example [19] - 32 - Developer’s Guide Developer's Guide, Development of Wib Services Universal Gateway and Wireless Service Management This example illustrates navigation to WIG WML documents that will be delivered as dynamic loaded wiblets from a remote server. The WIG WML documents are fetched using two different URLs. In the example, this is done by setting the variable "service" to the name of the WIG WML document. This example will play a tone! Press ok.
For the sake of the example, it is possible that the two below WIG WML are referenced by the above example. File document1.wml: Document selection example.
File document2.wml: - 33 - Developer’s Guide Developer's Guide, Development of Wib Services Universal Gateway and Wireless Service Management Service 1 You entered $(firstname).
- 34 - Developer’s Guide Developer's Guide, Development of Wib Services Universal Gateway and Wireless Service Management 7 Some additional UG features This section describes features that are of interest when building Wib services. 7.1 Caching The UG acts like a proxy cache for requests coming from Wib. This means that the UG will save a copy of the WIG WML document it receives from web servers, so that the next time there is a request for the same document, the UG will use the copy it has instead of asking the original Web server. The main reason for caching WIG WML documents is to reduce the time it takes to dynamically load a wiblet to Wib. It is recommended to use the UG cache as far as possible. The UG cache may be controlled by the Wib service developer using cache control HTTP headers. For details see reference [5]. 7.2 Cookies When the UG requests a WIG WML document from a web server, the web server may also respond with a piece of state information in addition to the WIG WML document. Included in the state object is a description of the range of URLs for which that state is valid. Any further requests made by the UG which fall in that range will also include transmittal of the current value of the state object back to the Web server. The state object is commonly referred to as a cookie. Note that cookies are never actually sent to Wib and therefore do not consume bandwidth. Instead they are managed and stored in the UG, on behalf of Wib. Cookies are most often used to enable user-side customization of Web applications. See reference [5] for more information on cookies. 7.3 Sending SMs The UG/Wib system supports two different ways of sending an SM. One way is to let UG send it and that can be called a server SM The other way is to let Wib send the SM as a consequence of executing a wiblet containing the sendsm Wib command. - 35 - Developer’s Guide Developer's Guide, Development of Wib Services Universal Gateway and Wireless Service Management The server-based method is activated by using the UG server-side plug-in call sendserversm (or sendserverdatasm) for server SM. The Wib-based method is reached by using the sendsm element. The originating address in a server SM will be the same as if the SM had been sent using a Wib SM, i.e. the MSISDN of the mobile phone. It is possible to send both Enhanced Message Service (EMS) and Nokia Smart Messaging (NSM) messages by using the sendserverdatasm plug-in or the sendsm element (requires Wib 1.3 or later). Details regarding the format and creation of EMS messages may be found in Enhanced Messaging Service – White Paper [2], Enhanced Messaging Service (EMS) – Developers Guidelines [10] and How to Create EMS Services [9]. Details regarding the technical realization of EMS may be found in TS 23.040. Technical realization of the Short Message Service (SMS) [1]. Details regarding the NSM format may be found in Smart Messaging Specification [4]. 7.4 Tariff class To charge for a WIG WML document, a tariff class may be used. The tariff class should be included among the HTTP headers in the Web server response to a UG request. The syntax for the tariff class follows the WAP syntax according to WAP Billing Framework [11]. X-WAP-Payment-Info: content-value-class = 1*10 digit (Zero is not allowed.) Before a content provider can use a tariff class, it has to be defined in DP. The tariff class and a corresponding SMSC id should be defined by the DP Administrator. Then each content provider has to be provided with a list of tariff classes that he is allowed to use. When the response/push request reaches the UG, the tariff class is checked against the content provider's white list of tariff classes. If the content provider is not allowed to use the tariff class, it is removed from the response/push request. If the content provider is allowed to use the tariff class it is used internally by DP for creating the correct charging information. - 36 - Developer’s Guide Developer's Guide, Development of Wib Services Universal Gateway and Wireless Service Management Tariff classes can be used together with caching. The tariff class will then be cached according to the same rules that apply to the WIG WML document. Example [20] This is an example of how to generate the tariff class header in a JSP document. Service 2 Location data will be sent to location service Press ok
Example [21] This example shows an ASP document that will generate the same result as the previous example. <%=Response.AddHeader ("X-WAP-Payment-Info", "content-value-class=123") %> <% response.addHeader("X-WAP-PaymentInfo", "content-value-class=123");%> Tariff class included in HTTP header.
- 37 - Developer’s Guide Developer's Guide, Development of Wib Services Universal Gateway and Wireless Service Management Appendix A WIG WML v5 migration guide A.1 Change from DTD to XSD In WIG WML v5 the doctype has been removed and replaced by a scheme declaration according to the example below. Instead of using a dtd as in WIG WML v4 a scheme is defined in the element wml. Tariff class included in HTTP header.
Note that the declaration is case-sensitive. Failing to reproduce this document type declaration in the beginning of the document will cause the UG to interpret the document as being written in an older WIG WML version. - 38 - Developer’s Guide Developer's Guide, Development of Wib Services Universal Gateway and Wireless Service Management Appendix B WIG WML migration guide This appendix aims to be a quick-reference for those who migrate Wib services written in older WIG WML versions to WIG WML v4 or later. B.1 Add doctype WIG WML v4 requires that the following document type declaration occurs before any of the WIG WML elements. Note that the declaration is case-sensitive. Failing to reproduce this document type declaration in the beginning of the document will cause the UG to interpret the document as being written in an older WIG WML version. That would most likely lead to errors. Note: WIG WML v5 use a scheme declaration instead of a doctype. See Appendix A B.2 a) b) Change document encoding Earlier versions of WIG WML had a concept whereby the document encoding in the XML declaration also determined the default character encoding in Wib. In addition, the default document encoding was ISO-8859-1 if the XML declaration was omitted or did not contain an encoding declaration. These two concepts have been abandoned in later WIG WML versions. Instead, the default document encoding is now UTF-8, which is in line with the XML standard, and the default encoding in Wib is no longer determined by the document encoding, but by the wml:wibletenc attribute. To convert older versions of WIG WML, do one of the following: If the WIG WML document does not contain an XML declaration or the document encoding is missing in the XML declaration, add or modify the XML declaration in the beginning of the document so that it reads: If the WIG WML document does contain the document encoding in the XML declaration, and the encoding is ISO8859-1 or ISO-8859-7, nothing needs to be done. - 39 - Developer’s Guide Developer's Guide, Development of Wib Services Universal Gateway and Wireless Service Management c) If the WIG WML document does contain the document encoding in the XML declaration, and the encoding is UTF8, modify the wml element according to: B.3 Remove a and anchor elements All occurrences of the a and the anchor element must be rewritten using the select element with options using the onpick attribute instead. B.4 Remove emphasis elements WIG WML v4 and later does not allow the following elements: b, i, u, big, string, em, small Since none of these elements had any visible effect, they may all be safely removed. B.5 Remove img elements All occurrences of the img element must be removed. This is always safe since the element had no effect in older WIG WML versions. B.6 Remove do elements All occurrences of the start and end do tags should be removed. Elements contained within the do element should be kept as before. B.7 Attribute values are case sensitive Since all attribute values are case sensitive in WIG WML v4 and later, the document must be corrected with this in mind. B.8 Tag names are case sensitive In WIG WML v4 and later all tag names are case sensitive. I.e. is different from
. The rule in WIG WML v4 and later is that tag names are written using exclusively lower case letter. - 40 - Developer’s Guide Developer's Guide, Development of Wib Services Universal Gateway and Wireless Service Management B.9 WMLScript function calls must be rewritten The WMLScript syntax has been removed as part of WIG WML v4 and later. This is actually the biggest change compared to older versions of WIG WML. Consequently, all WMLScript function calls must be rewritten using new language elements as specified in the WIG WML v4 or later specifications. The general rule to find the right element to use in WIG WML v4 or later is to remove the „wig‟ prefix from the WMLScript function name and use the new name as the look up in the WIG WML v4 or later specification. Often attributes in the element that replaces a WMLScript function call have a close resemblance with the parameters to the WMLScript function, which makes migration rather simple in most case. In the process, make sure that URL escaped values (like %XX where XX is a hexadecimal number) are replaced with their unescaped value. B.10 No automatic title in Select element In an earlier version of WIG WML, there was a rule that said if the select:title attribute was omitted, the text preceding the select element would be used as title for the select command in Wib. This is not the case in WIG WML v4 and later, and omitting the title attribute in the select or input element will cause the title to be empty in Wib, independent of any preceding text. B.11 userdata parameter for wigSendServerDataSM must be divided into two parameters When converting the wigSendServerDataSM WMLScript function call to the sendserverdatasm server-side plug-in call in WIG WML v4 or later, the userdata parameter value must be divided into a user data header parameter and possibly also a user data parameter. The user data header length (UDHL) which is the first byte in the original userdata parameter must also be removed. B.12 Strict card id attribute value card:id attributes which does not start with an underscore or a letter must be rewritten to do so. - 41 - Developer’s Guide Developer's Guide, Development of Wib Services Universal Gateway and Wireless Service Management B.13 Replace and Character entities and are not supported in WIG WML v4 and must be replaced with numeric character entities and respectively. B.14 Rewrite WIGVARxHH WIGVARxHH variable names, where HH is a hexadecimal number, must be replaced with :IDxHH It is recommendable, although not mandatory, to have a describing (variable) name in front of the colon, e.g.: LOCATION:IDx91 B.15 Rewrite dial-strings In all dial-strings, occurrences of lower-case characters “a” “e” must be replaced with “A”- “E”, respectively. This affects the wigSendSM and the wigSetupCall WMLScript function call. - 42 - Developer’s Guide Developer's Guide, Development of Wib Services Universal Gateway and Wireless Service Management Appendix C Error codes If an error occurs, the error is presented to the end user according to the format description described below. Note that different Wib version present errors somewhat differently. Wib 1.3 and later: [ErrorMessage] ErrorCode CommandTag [TerminaleResponse | FileIdentifier] Wib 1.1 and Wib 1.2: [ErrorMessage] ErrorCode CommandTag (Note: [] encloses an optional field(s) and | symbols an alternative) ErrorMessage is a descriptive text explaining the nature of the error, but may not always be presented to the end user. It may also be a general text message like “Error”. The ErrorCode is always displayed, and may be used to locate the error message associated with the error in cases where the ErrorMessage is omitted. CommandTag is the numeric tag of the Wib command that was executing when the error occurred. If the error did not occur as the result of a failed Wib command, the CommandTag field is set to "XX" TerminalResponse is the terminal response general result value if a proactive SIM command was issued as part of the Wib command. When the error code is „1F‟h, “Failed to access file”, the file identifier of the file that could not be accessed shall be given instead of the TerminalResponse. Error Description Code „01‟h Failed to find/read EFBytecode Failed to find/read EFTAR „03‟h Failed to access/read EFErrorText „04‟h Failed to find/read EFSMSHeader „05‟h Failed to read key file. „06‟h Failed to find/read EFVersionInformation „1F‟h Failed to access file. „20‟h Unknown Wib command found. „21‟h Variable substitution failed. File Access Errors Byte Code Errors „02‟h Note Not used since Wib 2.0 - 43 - Mobile Phone Errors Developer’s Guide Developer's Guide, Development of Wib Services Universal Gateway and Wireless Service Management Error Description Code Note „22‟h Too many variables used. Not used since Wib 2.0 „23‟h Out of variable memory. '24'h Wiblet too large to handle „25‟h SMS TPDU Tag in incoming SMS not found. „26‟h Creation of SELECT ITEM failed. „27‟h Encryption/decryption failed. „28‟h Out of buffer space. „29‟h Plug-in not found. „2A‟h Bad format on proactive STK command. „2B‟h "Goto" out of bounds. „2C‟h E2PROM memory problem. „2D‟h Command error in client bound message. „2E‟h Configuration error. „2F‟h SET RETURN TAR VALUE not allowed. „30‟h Wiblet not found. „31‟h Timer management failure. „32‟h Return from wiblet not allowed. „33‟h Invalid input data to Wib command. „34‟h Invalid incoming message. '35'h Variable too large in submit data „40‟h Proactive command rejected by ME. „41‟h Wrong type of command returned by ME in terminal response. „42‟h GET INPUT did not return a string. - 44 - Not used since Wib 2.0 Obsolete since Wib 2.0. Error code '33'h is used instead Obsolete since Wib 2.0. Error code '40'h and '46'h is used instead Obsolete since Wib 2.0. Error code '20'h and '33'h is used instead Developer’s Guide Developer's Guide, Development of Wib Services Universal Gateway and Wireless Service Management Proprietary Errors Note „43‟h No item identifier was returned by ME in the terminal response to a SELECT ITEM. „44‟h Temporary error occurred in application. Please try again later. „45‟h Error in format of received SM. „46‟h Command not supported by the mobile. „47‟h SET UP CALL failed. Not used since Wib 2.0 „48‟h SET UP EVENT LIST failed. Not used since Wib 2.0 „60‟h Invalid input parameters. „61‟h Input out of bounds. „62‟h Output overflow. „63‟h RSA error. „64‟h Illegal operation. „65‟h Integrity error. „66‟h PIN length error. „D0‟h Error in application occurred. Please call support. „E0‟h – „FF‟h Error codes in the ('E0'h..'FF'h) range are proprietary and depend on the Wib implementation. Default Errors Plug-in Errors Error Description Code - 45 - Developer’s Guide Developer's Guide, Development of Wib Services Universal Gateway and Wireless Service Management Appendix D Wib compatibility information This appendix describes the differences between the Wib versions released to date. D.1 Wib 1.1.1 compared to Wib 1.1 Wib 1.1.1 has the same functionality as Wib 1.1 with the exception of one new feature that was added to Wib 1.1.1. D.2 Wib 1.2 compared to Wib 1.1 The list below shows new Wib functions added in Wib 1.2. D.3 Check Terminal Profile: Better error handling in Wib. Conditional Jump: Jump to different WIG WML cards depending on a variable value. Display Text Clear After Delay: Clears the text on the screen of the mobile phone after a time interval without interaction from the user. Launch Browser: Enables starting a WAP browser session from Wib. Set Extended: Allows value data for the setvar element to be a mix of static data and variable references. Substring: Copies a sub-string from one variable to another variable. Wib 1.2.1 compared to Wib 1.2 Wib 1.2.1 has the same functionality as Wib 1.2 with the exception of one new feature. D.4 SMS Default in Get Input: The change applies to the input element, where it is now possible to mix UCS2 text with SMS Default input. SMS Default in Get Input: The change applies to the input element, where it is now possible to mix UCS2 text with SMS Default input. Wib 1.3 vs. Wib 1.2.1 The list below shows new Wib commands added in Wib 1.3. - 46 - Developer’s Guide Developer's Guide, Development of Wib Services Universal Gateway and Wireless Service Management Execute Local Wiblet: Enables “local links”, i.e. the ability to go from any wiblet to an installed wiblet. Submit Extended: Support for extensive progress information using both text and icons. Optional support for bookmarks. Launch Browser Extended: Fixes several issues with the “old” command which was more or less broken. Add/Subtract: Enables simple arithmetic in Wib. Convert Variable: Enables various forms of conversion between text and binary data. Group/Ungroup: Packing of many variables into one and vice versa. Set Up Call Extended: New formats for the destination address with support for variable references. New alpha identifier for call set up phase. Icon support. Display Text Extended: Support for text clearing, immediate response indicator and text priority. Icon support. Set Up Idle Mode Text Extended: Icon support. Send SM Extended: New formats for the destination address with support for variable references. New alpha identifier for call set up phase. Icon support. Swap nibbles: Swapping the nibbles of an individual byte. BCD to GSM 7bit Default Conversion: Conversion of binary BCD data to readable text. GSM 7bit Default to UCS2 Conversion: Conversion from SMS default character set to UCS2 and vice versa. Timer Management: Timers in Wib. Some of the existing (Wib 1.2) Wib commands have also been changed in a backward compatible way in Wib 1.3, to add more features. - 47 - Developer’s Guide Developer's Guide, Development of Wib Services Universal Gateway and Wireless Service Management D.5 Get Input: Icon support. Select Item: Variable reference may now be used in the options. Icon support for each option as well as in the title. Skip: Two byte skip-length. New Context: Enables more fine grained control over which variables that should be cleared. Send USSD: Icon support and improved variable reference support. Variable substitution: Empty variables are substituted by an empty string in Wib 1.3. In Wib 1.2, an error would have been generated. Wib 2.0 vs. Wib 1.3 The list below shows new Wib commands added in Wib 2.0. Get Terminal Profile: Get terminal profile as sent by terminal in PROFILE DOWNLOAD Execute Wiblet: Executes a wiblet(byte code) received as input. Go On Exit: Command to change default behaviour when Wib exits execution of a Wiblet normally or due to error. Options include display of main menu and execution of another Wiblet. Execute STK Command: Wib command to execute any STK command. Create TLV: Creates a TLV structure from a tag and a value. Extract TLV: Breaks down a TLV structure into its components. Convert Text Formats: Conversion between Text and AlphaIdentifier as well as between packed and unpacked Text. Send Supplementary Service: Allows for sending a SS string to the network. Get ICCID: Allows for retrieval of the ICCID of the card. The list below shows commands which have had their functionality extended in Wib 2.0. - 48 - Developer’s Guide Developer's Guide, Development of Wib Services Universal Gateway and Wireless Service Management Check Terminal Profile: Support for variables. Allows for check against a single large bitmask. Substring: Support for variables. Larger max values for span and start attribute to support large variables. Possible to use negative values in span attribute. Submit Extended: Added ability to catch errors when submitting data. Submit header added to inform about large variables in data and to allow for sending additional data (IMEI, location information, language information). Send USSD: Added ability to catch errors when sending USSD. Retry added. Possibility to override input and output DCS values. Launch Browser: Added ability to catch errors when launching the WAP browser. Retry added. Setup Call: Added ability to catch errors when setting up call. Retry added. Send SM Extended: Added ability to catch errors when sending SM. Add/Subtract: New number formats introduced. Group/Ungroup Variable: Added support for long variables. Refresh: Added support for lists of network. Allows steering of roaming. - 49 - Developer’s Guide Developer's Guide, Development of Wib Services Universal Gateway and Wireless Service Management Appendix E WIG compatibility information This appendix lists issues related to backward compatibility of the WIG. E.1 WIG 3.3 vs. WIG 3.2 (DP 6.0 vs. DP 5.2.3) WIG 3.3 is backward compatible with WIG 3.2, with these exceptions: New URL decoding of Push WIG WML documents: Push documents will not be URL decoded anymore. Any push application depending on this has to be updated. Restricted variable ID range: The syntax WIGVARxFF does not work anymore for variable IDs in the range (0xE0..0xFF). For all other variable IDs, the syntax works as before. Variables not supported in wigLaunchBrowser: Variables in the URL for the STK command wigLaunchBrowser are no longer supported. Binary data in WIG WML: The ÿ syntax can no longer be used in WIG WML documents for binary data. Instead the \xFF syntax shall be used. ' not supported as before: The ' character entity in WIG/Wib specific commands such as wigSendSM can not be used anymore. Instead %27 shall be used for indicating the ' character. Cache and cookies: A WIG WML document will now be fetched from cache although there are cookies associated with the request. The Content Provider is still in control, since the WIG will only cache a WIG WML document if the HTTP headers indicate that caching is allowed. Cache and query string: A WIG WML document will now be cached, although the URL contains a query string. The Content Provider is still in control, since the WIG will only cache a WIG WML document if the HTTP headers indicate that caching is allowed. - 50 - Developer’s Guide Developer's Guide, Development of Wib Services Universal Gateway and Wireless Service Management E.2 WIG 4.0 vs. WIG 3.3 (DP 6.1 vs. DP 6.0) WIG 4.0 supports a new and redesigned version of the WIG WML language called WIG WML v4. The WIG still supports earlier versions of WIG WML, but it is recommended that all new Wib services are developed using WIG WML v4. Appendix F covers frequently asked questions concerning the rationale behind WIG WML v4. Since WIG WML v4 is a new language, it is not meaningful to talk about backward compatibility. Instead Appendix B includes a migration guide for those who consider migration of their Wib services to WIG WML v4. - 51 - Developer’s Guide Developer's Guide, Development of Wib Services Universal Gateway and Wireless Service Management Appendix F WIG WML FAQ Q1. Why do we need a new version WML? There are two main reasons why the updated WML syntax was created. 1. 2. 3 The old WIG WML syntax, which is called WIG WML v3, is not very user friendly when it comes to functionality which is not covered by similar functionality in WAP WML. A good example is the WML Script calls which are used to call some of the used STK commands. This syntax is error prone and with a low verbosity, affecting the possibility to create and later on comprehend a WML document. Wib 1.3 introduced many new features that must be reachable from WIG WML. Continuing on the WIG WML v3 track would create syntax that breaks the principle of WAP WML compatibility and at the same time make a mess out of the language. Instead we decided to break the principle of WAP WML compatibility with style by redesigning certain aspects of the language, and thereby improving the usability of the language as well as the fitness for its purpose. Wib 2.0 introduced even more new features and WIG WML v5 required to be developed. Q2. What WIG WML version shall I use? For DP6.1 up to DP7.2 platforms WIG WML 4 is supported and shall be used. For DP8 platforms and later WIG WML 5 is supported. It is recommended to use this language if developing new services. Q3. Do we have to update all our existing applications? No. An application only needs to be updated if you want to make use features in Wib 1.3 and later. Naturally, the applications can be enhanced by doing that. So it might be worth considering even if you are not forced to do so. - 52 - Developer’s Guide Developer's Guide, Development of Wib Services Universal Gateway and Wireless Service Management Q4. Can the new WML be used for Wib 1.1 and Wib 1.2? Yes! Naturally, you will only be able to use features that are available in the actual Wib version being used. We strongly recommend all new applications to use WIG WML v5 since it is more user-friendly and also catches more errors at an earlier stage. It also simplifies migration to Wib 1.3. Q5. Why do I have to update my application completely just to add icons? You do not have to update your application completely. Only those documents that require icons have to be updated, and in many cases the change involves only adding the WIG WML v4 header and adding the icons in the right places, which you would have to do in any case. Q6. I want to upgrade from DP 5. Will it cause any problems? That will work fine! WIG WML v3 is still supported in DP 6.1 and later. Q7. I want to upgrade from DP 6.0. Will it cause any problems? No. Same answer as Q6. Q8. I want to upgrade from DP 7.x. Will it cause any problems? No. Same answer as Q6. Q9. Our developers cannot learn this new WML. Why can't we use the old one? You can use WIG WML v3 in DP 6.1 and later. The drawback is that you will not be able to use Wib 1.3 or Wib 2.0 specific features. Q10. Can new and old WML be mixed? Not within the same WML document. A Wib service consisting of several WML documents may mix WIG WML v3, v4 and v5 freely between the documents. - 53 - Developer’s Guide Developer's Guide, Development of Wib Services Universal Gateway and Wireless Service Management Q11. The wiblet size appears bigger for Wib 1.3 compared to Wib 1.2. Is this the case? In general the answer is yes. Many of the Wib 1.3 commands are extended versions of the same commands in Wib 1.2 and Wib 1.1. They offer more features but also occupy slightly more space. However, Wib 1.3 also introduces some features that can be used to quite significantly decrease wiblet size and improve userexperience. You should look at the possibility of invoking locally stored wiblets as subroutines and to use bookmarks in an efficient manner. - 54 -
Source Exif Data:
File Type : PDF File Type Extension : pdf MIME Type : application/pdf PDF Version : 1.5 Linearized : No Page Count : 54 Language : en-US Tagged PDF : Yes Author : Malin Nordin Creator : Microsoft® Office Word 2007 Create Date : 2011:06:15 10:59:55 Modify Date : 2011:06:15 10:59:55 Producer : Microsoft® Office Word 2007EXIF Metadata provided by EXIF.tools