Grandstream XML Application Guide

Grandstream XML Application Guide

Three XML Applications

PART A – Application Explanations
PART B – XML Syntax, Technical Detail, File Examples

Grandstream XML Application Guide - PART A

Three XML Applications

Grandstream GXP Series supports both simple and advanced XML applications. Part A of this application
note will describe Grandstream’s three XML applications: 1) XML Custom Screen, 2) XML Downloadable
Phonebook and 3) Advanced XML Survey Application.

Grandstream Networks XML Application Note – Version 1 Page 2 of 21

Revised: 9/2007

Three XML Applications

Grandstream GXP Series supports both simple and advanced XML applications: 1) XML Custom Screen, 2)
XML Downloadable Phonebook and 3) Advanced XML Survey Application.

WHAT IS XML?

XML is a markup language* for documents and applications containing structured information. This
information contains both content (words, pictures, etc.) and an indication of what role that content plays
(e.g. content in a section heading is different than content in a footnote, which is different than content in a
figure caption or content in a database table, etc.). Almost all documents have some 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.

W

HY XML?

What benefits does XML provide to SIP endpoints? XML enables our SIP phones to serve as output devices
for many exciting applications. The XML infrastructure allows our phones to interact with external
applications in a flexible and programmable manner. Three specific XML applications supported by
Grandstream include XML Custom Screen, XML Phonebook, and XML Survey Application. The last
application is a custom application where the XML framework is an interactive, real-time implementation
and XML messaging is dynamic, depending on a configurable object set.

Grandstream Networks XML Application Note – Version 1 Page 3 of 21

Revised: 9/2007

XML ARCHITECTURE

XML applications can be initiated in several ways.

1. The first architecture is if the phone initiates a request for a service. In this instance, the GXP will

receive a 200 OK with a XML document as its content.

2. The second architecture is if the server initiates the transaction. The server will use HTTP POST

with the XML document in the body instructing the GXP what to display and the possible actions.

3. The third architecture is in a closed network. An application in a closed network may exchange

information in the following manner:

Grandstream Networks XML Application Note – Version 1 Page 4 of 21

Revised: 9/2007

4. A fourth architecture enables the internal web server to interact with outside web server via HTTP.

As illustrated above, all of the application logic lies within the server side of the architecture. This allows
faster applications development and minimal phone side maintenance. Users may develop customized
applications using this infra structure.

XML CUSTOM SCREEN APPLICATION

The GXP Series supports idle screen customization. The design and layout of the LCD screen is customer
dependent. The following API configuration will work with all GXP Series models.

USTOM SCREEN API CONFIGURATION

C

The XML Custom Screen API is configurable in 2 steps:

1. Enable Idle Screen XML Download (P340): NO/YES-HTTP/YES-TFTP (default NO). Possible

values 0 (NO)/1 (HTTP)/2 (TFTP), other values ignored.

2. Idle Screen XML Server Path (P341): This is a string of up to 128 characters that contains a path

to the XML file. It must

follow the host/path format. i.e. “directory.grandstream.com/engineering”

The XML feature is activated when “Enable Idle Screen XML Download” is set to YES (HTTP or TFTP)
and

a valid “Idle Screen XML Server Path” is set.

To download the XML file, the following 2 options should be selected in the Preference LCD GUI
submenu:

• Download SCR XML

• Erase Custom SCR

Select the Download SCR XML using the Preference Keypad menu to start the download process. The phone
will download the gs_screen.xml file specified in “Idle Screen XML Server Path”. The XML application is
effective immediately after download. Save the file for future use.

NOTE: the Idle Screen file name is fixed and cannot be changed based on personal preference.

XML PHONEBOOK APPLICATION

The GXP Series supports a downloadable phonebook with up to 500 entries. This application can also be
used in large organizations where there is a central directory server so employees can efficiently download

Grandstream Networks XML Application Note – Version 1 Page 5 of 21

Revised: 9/2007

the most current directories. The following Phonebook API configuration will work with all GXP Series
models.

HONEBOOK API CONFIGURATION

P

The XML Custom Screen API is configurable in 4 steps:

1. Enable Downloadable Phonebook (P330): NO/YES-HTTP/YES-TFTP (default NO). Possible

values 0 (NO)/1 (HTTP)/2 (TFTP), other values ignored.

2. Phonebook XML Path (P331): This is a string of up to 128 characters tha t contains a path to the

XML file. It must

follow the host/path format. i.e. “directory.grandstream.com/engineering”

3. Phonebook Download Interval (P332): This field sets the time interval to download the

phonebook (in hours) automatically. Valid value range is 0-720 (default 0).

4. Remove manually remove edited entries on download: YES/NO (default NO) P333, possible

values 0/1, other values ignored.

The XML phonebook feature is activated when “Enable Downloadable Phonebook” is set to YES (HTTP or
TFTP) and

a valid “Phonebook XML Path” is set.

The phone will download the gs_phonebook.xml file specified in “Phonebook XML Path”. The XML
application is effective immediately after download. Save the file for future use. During this process the
LCD will display a message to indicate the XML Phonebook download is in progress.

NOTE:

• The phonebook file name is fixed and cannot be changed based on personal preference.

• If the “Phonebook Download Interval” is set to a non-zero value x, the phonebook is automatically

updated every x hours.

• If the “Remove manually edited entries on download” option is set to No (by default), the phone

will keep ALL previously stored phonebook entries, insert the downloaded phonebook entries, and
then save the phonebook. If set to Yes, the downloaded phonebook entries will replace the existing
phonebook stored on the phone.

• At any time, you can immediately download the phonebook by choosing the “Download

Phonebook” in the GUI Phone Book Menu (you can use the down arrow key when the phone is on­hook).

Grandstream Networks XML Application Note – Version 1 Page 6 of 21

Revised: 9/2007

Grandstream XML Application Guide - PART B

XML Syntax, Technical Detail, File Examples

Part B of this application note will guide you through the technical details of our three applications: 1)
XML Custom Screen, 2) XML Downloadable Phonebook and 3) Advanced XML Survey Application.

Grandstream Networks XML Application Note – Version 1 Page 7 of 21

Revised: 9/2007