Grandstream Networks XML Application Manual

Grandstream XML Application Guide

Three XML Applications

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

Grandstream Networks, Inc. XML Application Guide Page 2 of 24
Last Updated: 3/2009

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 XML applications: 1) XML Custom Screen, 2) XML Downloadable
Phonebook and 3) Advanced XML Survey Application.

Grandstream Networks, Inc. XML Application Guide Page 3 of 24
Last Updated: 3/2009

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 differe nt 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 implemen ta tion and
XML messaging is dynamic, depending on a configurable object set.

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 in a closed network. An application in a closed network may exchange
information in the following manner:

 



Grandstream Networks, Inc. XML Application Guide Page 4 of 24
Last Updated: 3/2009

3. A third 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 infrastructure.

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.

C

USTOM SCREEN API CONFIGURATION

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 “Ena ble Idle Screen XML Download” is se t to YES (HTT P or TFTP) and
a valid “Idle Screen XML Server Path” is set.

To download or erase the XML file, the following 2 options sh ould 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: GXP2020 sup ports custom Idle Screen file name. For othe r GXPs, the Id le 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
the most current directories.

Grandstream Networks, Inc. XML Application Guide Page 5 of 24
Last Updated: 3/2009

NOTE: As of April 2008 Grandstream Networks is working on a solution to be able to download phonebooks

that are 100+ entries large. The phones currently only support 500 entries if they are entered manually.
As a recommendation we suggest all XML phonebooks to be limited to 100 entries for the time being.

The following Phonebook API configuration will work with all GXP Series models.

P

HONEBOOK API CONFIGURATION

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 that 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 down load 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, Inc. XML Application Guide Page 6 of 24
Last Updated: 3/2009

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, Inc. XML Application Guide Page 7 of 24
Last Updated: 3/2009

Application One: XML Custom Screen Details

XML

CUSTOM SCREEN SYNTAX

XSD FILE

<?xml version="1.0"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="Screen">
<xs:complexType>
<xs:sequence>
<xs:element name="IdleScreen" minOccurs="1" maxOccurs="1">
<xs:complexType>
<xs:sequence>
<!-- The ShowStatusLine element is now optional and default to false. Ignored by GXP2020 -->
<xs:element name="ShowStatusLine" type="xs:boolean" minOccurs="0" maxOccurs="1"

default="false"/>

<xs:element name

="DisplayBitmap" type="BitmapType" minOccurs="0" maxOccurs="unbounded"

nillable="true"/>

<xs:element name="DisplayString" type="StringType" minOccurs="0" maxOccurs="unbounded"

nillable="true"/>

<!-- The DisplaySoftKey element apply only to GXP-2020/2010 and is ignored by GXP-2000 -->
<xs:element name="DisplaySoftKey" type="SoftKeyType" minOccurs="0" maxOccurs="12"

nillable="true"/>

<!-- The UseDefaultSoftKeys element apply only to GXP-2020/2010 and is ignored by GXP-2000

If it is missing by default it is false, when it is true, any DisplaySoftKey elements
would be ignored and the system default softkeys would apply -->

<xs:element name="UseDefaultSoftKeys" type="xs:boolean" minOccurs="0" maxOccurs="1"

default="false"/>

</xs:sequence>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>

<xs:complexType name="BitmapType">
<xs:sequence>
<xs:element name="Bitmap" type="xs:base64Binary" minOccurs="1" maxOccurs="1"/>
<xs:element name="

X" type="xs:integer" minOccurs="1" maxOccurs="1" default="0"/>

<xs:element name="Y" type="xs:integer" minOccurs="1" maxOccurs="1" default="0"/>
<!-- The new element displayCondition deprecates the old attribute alreg.

If displayCondition is found alreg will be ignored.
The old attribute al1reg is kept for backward compatibility -->

<xs:element name="displayCondition" type="IdleScreenConditionType" minOccurs="0" maxOccurs="1"

nillable="true"/>

</xs:sequence>
<!-- This attribute is deprecated, please use the displayCondition element instead -->

<xs:attribute name="a1reg" type="xs:boolean"/>
</xs:complexType>

<xs:complexType name="StringType">
<xs:sequence>
<xs:element name="DisplayStr" type="xs:string" minOccurs="1" maxOccurs="1" />
<xs:element name="X" type="xs:integer" minOccurs="1" maxOccurs="1" default="0"/>
<xs:element name="

Y" type="xs:integer" minOccurs="1" maxOccurs="1" default="0"/>

<!-- The new element displayCondition deprecates the old attribute alreg.

If displayCondition is found alreg will be ignored.
The old attribute al1reg is kept for backward compatibility -->

<xs:element name="displayCondition" type="IdleScreenConditionType" minOccurs="0" maxOccurs="1"

nillable="true"/>

</xs:sequence>
<!-- This attribute is deprecated, please use the displayCondition element instead -->

<xs:attribute name="a1reg" type="xs:boolean"/>
<xs:attribute name="font" default="f8"

>
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:enumeration value="f8"/>

Grandstream Networks, Inc. XML Application Guide Page 8 of 24
Last Updated: 3/2009

<xs:enumeration value="f10"/>
<xs:enumeration value="f13h"/>
<xs:enumeration value="f13b"/>
<xs:enumeration value="f16"/>
<xs:enumeration value="f16b"/>
<!-- c suffix fonts are Comic fonts -->
<xs:enumeration value="f18c"/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>

<xs:attribute name="halign" default="Left">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:enumeration value="Left"

/>
<xs:enumeration value="Center"/>
<xs:enumeration value="Right"/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>

<xs:attribute name="valign" default="Top">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:enumeration value="Top"/>
<xs:enumeration value="Center"/>
<xs:enumeration value="Bottom"/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>

</xs:complexType>
<xs:complexType name

="IdleScreenConditionType">
<xs:sequence>
<xs:element name="conditionType">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:enumeration value="alwaysDisplay"/>
<xs:enumeration value="a1reg"/>
<xs:enumeration value="a2reg"/>
<xs:enumeration value="a3reg"/>
<xs:enumeration value="a4reg"/>
<xs:enumeration value="a5reg"/>
<xs:enumeration value="a6reg"/>
<xs:enumeration value="a1voiceMsg"/>
<xs:enumeration value="a2voiceMsg"/>
<xs:enumeration value="a3voiceMsg"/>
<xs:enumeration value="a4voiceMsg"/>
<xs:enumeration value="a5voiceMsg"/>
<xs:enumeration value="a6voiceMsg"/>
<xs:enumeration value="missCall"/>
<xs:enumeration value="callFwded"/>
<xs:enumeration value="dnd"/>
</xs:restriction>
</xs:simpleType>
</xs:element>
</xs:sequence>

<!-- The noptional negate element negates the evaluated result to create opposite behavior -->
<xs:attribute name="negate" type="xs:boolean"

default="false"/>

</xs:complexType>
<xs:complexType name="SoftKeyType">

<xs:sequence>
<xs:element name="KeyLabel" minOccurs="1" maxOccurs="1">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:minLength value="1"/>
<xs:maxLength value="32"/>
</xs:restriction>
</xs:simpleType>
</xs:element>

<xs:element name="KeyAction" minOccurs="1" maxOccurs="

1">
<xs:simpleType>
<xs:restriction base="xs:string">
<!-- the UseURL option will also require the URL element and is not used now -->
<xs:enumeration value="UseURL"/>
<xs:enumeration value="NewCall"/>
<xs:enumeration value="FwdAll"/>