Grandstream GXP21xxXML User Manual
Grandstream Networks, Inc.
GXP21xx XML Application Guide
Version 1.0.0.2
GXP21xx XML APPLICATION GUIDE
GXP21xx XML Application Guide
Index
INTRODUCTION ........................................................................................ 4
REVISION HISTORY ............................................................................................................................. 4
VERSION 1.0.0.1 ............................................................................................................................ 4
VERSION 1.0.0.2 ............................................................................................................................ 4
WHAT IS XML ........................................................................................................................................ 5
WHY XML .............................................................................................................................................. 5
XML API ARCHITECTURE .................................................................................................................... 5
XML APPLICATION CONFIGURA TION ..................................................... 7
FIRMWARE ............................................................................................................................................ 7
WEB GUI CONFIGURATION ................................................................................................................ 7
USING LCD AND KEYP AD .................................................................................................................... 8
NAVIGATION IN XML APPLICATION .......................................................................................... 10
SCREEN LAYOUT ............................................................................................................................... 11
XML APPLICATION FORMA T .................................................................. 13
HEADER .............................................................................................................................................. 13
SPECIAL CHARACTERS .................................................................................................................... 13
GXP21xx SCREEN XML STRUCTURE .............................................................................................. 13
GXP21xx XML ELEMENT ........................................................................ 16
ROOT ELEMENT <Screen> ................................................................................................................ 16
<Screen> ELEMENT DETAILS .................................................................................................... 16
<LeftStatusBar> ELEMENT ................................................................................................................. 16
<LeftStatusBar> ELEMENT DETAILS .......................................................................................... 17
<SoftkeyBar> ELEMENT ..................................................................................................................... 18
<SoftkeyBar> ELEMENT DETAILS .............................................................................................. 19
<Page> ELEMENT .............................................................................................................................. 19
<Page> ELEMENET DETAILS ..................................................................................................... 19
<Contents> ELEMENT ........................................................................................................................ 20
<Contents> ELEMENET DETAILS ............................................................................................... 20
<DisplayString> ELEMENT .................................................................................................................. 21
<DisplayString> ELEMENET DETAILS ........................................................................................ 21
<DisplayBitmap> ELEMEN T ................................................................................................................ 21
<DisplayBitmap> ELEMENET DETAILS ...................................................................................... 22
FIRMWARE VERSION 1.0.4.23 GXP21xx XML APPLICATION GUIDE Page 2 of 36
<input> ELEMENT ............................................................................................................................... 24
<input> ELEMENET DETAILS ...................................................................................................... 24
<select> ELEMENT ............................................................................................................................. 27
<select> ELEMENET DETAILS .................................................................................................... 28
<SoftKeys> ELEMENT ........................................................................................................................ 28
<SoftKeys> ELEMENET DETAILS ............................................................................................... 29
<SoftKey> ELEMENT .......................................................................................................................... 29
<SoftKey> ELEMENET DETAILS ................................................................................................. 29
<Events> ELEMENT ............................................................................................................................ 31
<Events> ELEMENET DETAILS .................................................................................................. 32
<Event> ELEMENT .............................................................................................................................. 32
<Event> ELEMENET DETAILS .................................................................................................... 32
XML APPLICATION ELEMENT ATTRIBUTE ........................................... 33
ATTRIBUTE color/bgcolor .................................................................................................................... 33
ATTRIBUTE halign ............................................................................................................................... 33
ATTRIBUTE state................................................................................................................................. 34
SYSTEM VARIABLES IN STRING DISPLAY ........................................... 35
FIRMWARE VERSION 1.0.4.23 GXP21xx XML APPLICATION GUIDE Page 3 of 36
INTRODUCTION
The Grandstream GXP21xx supports XML Application on firmware version 1.0.3.30/1.0.4.x. This XML API
allows users to access service information in web server, present the information in LCD as well as
customize screen display. It's a custom application wher e the XML fram ework is an interactive, rea l-time
implementation and XML message is dynam ic, depending on a conf igurable obj ect set. It coul d be easily
developed with all the programming languages for web application development (e.g., PHP, ASP, and etc).
Typical XML applications could be call center service, survey, reservations and much more.
REVISION HISTORY
VERSION 1.0.0.1
• Initial version for GXP21xx firmware version 1.0.3.30.
VERSION 1.0.0.2
• Updated for GXP21xx firmware version 1.0.4.23.
• Added HTTPS support in XML application, for both XML application server path and Softkey action.
• The allowed XML Server Path length is extended from 128 characters to 256 characters.
• Element <LeftStatusBar> is removed from template.xml. This element is optional. If present, it will
override the default LeftSt atusBar display pre-defined on the phone.
• Element <SoftkeyBar> is removed from template.xml. This element is optional. If present, it will
override the default SoftkeyBar display pre-defined on the phone.
• Added Radio button support by using type="radio" in <input> element. Supported attributes are
"group", "value", "sel ected" and "label". When the qu ery is sent back the result is group =value. For
example, a radio with group "answerToQ1" with a value of "B" would result in "answerToQ1=B".
• Added Checkbox support by using type="checkbox" in <input> element. Supported attributes are
"name", "value" and "label". When the query is sent back the result is name=value.
• Added Selection list support by using <select> element.
• Added "password" type in <input> element so the entered digits will be displayed as *.
• Added "hidden" type i n <input> elem ent so the input file d and entered digits won't displ ay. It can be
used to pass value which is preferred to be hidden on LCD.
• Added system variable $xU for account x' s SIP User ID to be used in XML application where x is 0 to 5
for account 1 to account 6.
• Added system variable $x N for account x' s Displa y Name if filled in, other wise account x' s Acc ount
Name (x is 0 to 5 for account 1 to account 6).
• Added system variable $xS for account x' s SIP Server where x is 0 to 5 for account 1 to account 6.
FIRMWARE VERSION 1.0.4.23 GXP21xx XML APPLICATION GUIDE Page 4 of 36
WHAT IS XML
XML (eXtensible Markup Language) is a markup language* for docum ents and applications containing
structured inform ation. This information contains both content (text, pictures, inp ut box and etc.) and an
indication of what role that content plays (e.g. content in a sectio n header is different fr om content in a
footnote, or cont ent in a figure cap tion, or content in a database table, etc .). Almost a ll documents have
certain kind of structure.
*A markup language is a mechanism to identify structures in a document. The XML specification defines a
standard way to add markup to documents.
WHY XML
What benefits does XML provide to SIP endpoints? XML enables our SIP phones to serve as output
devices for web services and other online applications. The XML infrastructure allows the phones to
interact with external applications in a flexible and programmable manner. Three specific XML API
supported by GXP21xx are XML Custom Screen, XML Phonebook and XML Application.
XML API ARCHITECTURE
The XML application on GXP21xx is us ing HTTP/HTTPS as the transport protocol. The following f igure
shows how it work s. Basic ally, GXP21xx initiates the HTTP/HT TPS GET Reques t to the server and waits
for the response. Once the phone receives the response with XML content in BODY, it displays the
information.
Two types of XML API architecture are introduced below, depending on if the application is within LAN or
accessed via Internet.
FIRMWARE VERSION 1.0.4.23 GXP21xx XML APPLICATION GUIDE Page 5 of 36
1. An application in LAN area may exchange information in the following manner. GXP21xx sends
request and accepts XML contents via HTTP/HTTPS, directly communicating with the server. The
server will then handle t he r eques t and r esp ons e via a n y protoc ols w ith t he o ther application server to
get the expected information for the XML service.
2. If the above Web Server accesses Internet, it could interact with outside web server and respond
real-time content to GXP21xx.
As illustrated abo ve, all of the application lo gic lies within the server side of the ar chitecture. This a llows
faster applications development and minimal phone side maintenance.
FIRMWARE VERSION 1.0.4.23 GXP21xx XML APPLICATION GUIDE Page 6 of 36
XML APPLICATION CONFIGURATION
FIRMWARE
Before the XML appl ication is launched on GXP21xx , the firmware on the phone m ust be upgraded to
version 1.0.3.30/1.0.4.x. This document describes functions and features based on firmware version
1.0.4.23. Please refer to the following link for firmware upgrading information:
http://www.grandstream.com/support/firmware
WEB GUI CONFIGURATION
To launch the XML application on GXP21xx, firstly set the XML application server path and softkey label in
web GUI->Settings->Advanced Settings page.
The Server Path must be set to t he web s er ver directory wher e the a pp lication is located. C urr e ntly HTTP
and HTTPS are supported. The accepted format are as below (content in [ ] is optional).
• For HTTP
IP_address[:port]/dir/filename or http://IP_address[:port]/dir/filename
Hostname[:port]/dir/filename or http://Hostname[:port]/dir/filename
• For HTTPS
https://IP_address[:port]/dir/filename
https://Hostname[:port]/dir/filename
https://username:password@IP_address[:port]/dir/filename
https://username:password@Hostname[:port]/dir/filename
FIRMWARE VERSION 1.0.4.23 GXP21xx XML APPLICATION GUIDE Page 7 of 36
• Examples:
http://192.168.40.10/XMLapp/welcome.xml
mycompany.com:8080/surveyapp.xml
https://service.mycompany.com/XMLapp/reservation.xml
https://admin:adminpassword@192.168.40.123/GXP2120/API.xml
Note:
• If "http://" is not specified in the Server Path, the phone will use HTTP by default. Therefore, "http://" is
not necessary to be included in the path if HTTP is used.
• For HTTPS, users must specify "https://" in the Server Path. If username and password are required by
the HTTPS server, users could use "https://username:password@server_address/directory" to access.
• The content in [ ] is optional. If ":port" is not specified, by default port 80 will be used for HTTP and port
443 will be used for HTTPS.
The default value for Softkey Label is "XML Service". Users presses this softkey to launch the XML
application. Please make sure the label string does not exceed the softkey maximum length on each model.
After the above configurat ion, click on "Update" in web GUI->Settings->Advanced Settings page. The
GXP21xx wil l then display the X ML Serv ice s of tkey on LCD. Press the softkey with the configured la be l to
launch the application.
Users may also use config file to provision the XML Application Server Path and Softkey Label to the phone.
In this case, GXP21xx needs to be provisioned and rebooted. The corresponding P values are as below.
• P337: Server Path.
This is a string of up to 256 characters that should contain the path to the XML application file.
• P352: Softkey Label.
This is a string of up to 16 characters to display the softkey label on LCD.
USING LCD AND KEYPAD
Without configuration, the default idle screen (GXP2120) is like below.
FIRMWARE VERSION 1.0.4.23 GXP21xx XML APPLICATION GUIDE Page 8 of 36
Once the XML Application server path and softkey label are successfully configured, the label will be displayed
as the second softkey. Press this key to load the application.
As you may know, it is also possible to enter the appl ication server path into PC's web browser. In this way you’ll
be able to see the exact XML document on your PC that your phone is receiving.
An example application screen will be like below.
FIRMWARE VERSION 1.0.4.23 GXP21xx XML APPLICATION GUIDE Page 9 of 36
NAVIGATION IN XML APPLICATION
Now the XML application is started on the phone. To navigate and proceed i n the application, use the keypad
and softkeys to complete the following different actions.
• Keypad digit input
- Enter the digits on the phone's keypad if the application requires input.
- To delete an input digit, press "Left" arrow key on the phone as backspace.
- If there are multiple input fields, press "UP" or "DOWN" arrow to toggle among the input fields.
- For example, enter the digits for Your Applicant ID in the input field as the above figure shows.
• Radio button selection
- Press "UP" or "DOWN" arrow to move the selection cursor to the desired radio button.
- Press "MENU" to make the selection.
• Checkbox selection
- Press "UP" or "DOWN" arrow to move the selection cursor to the desired checkbox.
- Press "MENU" to make the selection.
• Selection list
- Press "UP" or "DOWN" arrow to move the selection cursor to the desired list field .
- Press "LEFT" or "RIGHT" to toggle among different selections defined in the list.
• Softkey navigation
- Press the corresponding softkeys to navigate. The softkeys are defined in the XML code. Each softkey
could contain label for display, action and URL to trigger the phone to display another page. In the
above example, "Submit" will navigate you to the next step of the screening process. "Exit" allows you
to quit the application. "Tutorial" will launch the information page for users to browse.
FIRMWARE VERSION 1.0.4.23 GXP21xx XML APPLICATION GUIDE Page 10 of 36
- In the case when there are more than 3 or 4 softkeys (depending on the GXP21xx model) used in the
XML application, a "MORE" softkey will automatically show. Click on it to view more softkeys.
• Quit application.
- During the XML application, there is a default way for users to quit and return to normal idle screen. To
quit, press and hold the "HOLD" button on phone's keypad for about 3 seconds.
- A warning window will then be popped out "Quit Application: Are you sure you want to exit the current
application?".
- Press softkey "OK" to quit, or press "Cancel" to continue the application.
- This operation is not applicable for GXP2124 yet on firmware version 1.0.4.23.
• Make/Answer call during application.
- When the phone is running the application, users could make or answer call without exit.
- Make call by offhook the handset, or press the speaker button.
- Answer incoming call by offhook the handset, or press the speaker button, or press the softkey
"AnswerCall".
- Once the call screen is triggered, "ResumeAPP" softkey will display. Press this key to continue the
application.
Note:
The above exam ple and screenshots are taken on GXP2120. The c onfigurations and operat ion are the
same for all the other GXP21xx models, but the screen size and softkey layout may vary.
SCREEN LAYOUT
The GXP2120/2110/2100/2124 have different screen s ize and softk ey layout. The LC D size (in p ixel) and
default layout are described below as reference.
FIRMWARE VERSION 1.0.4.23 GXP21xx XML APPLICATION GUIDE Page 11 of 36
Loading...