Grandstream GXP2200XML User Manual

Grandstream Networks, Inc.
GXP2200
XML Based Downloadable Phonebook Guide
Index
INTRODUCTION ........................................................................................... 3
WHAT IS XML ...................................................................................................................................... 3
WHY XML ............................................................................................................................................ 3
XML API ARCHITECTURE .................................................................................................................. 3
XML PHONEBOOK CONFIGURATION ....................................................... 6
FIRMWARE ......................................................................................................................................... 6
LCD CONFIGURATION ....................................................................................................................... 6
PROVISIONING .................................................................................................................................. 9
IMPORT/EXPORT PHONEBOOK ....................................................................................................... 9
XML PHONEBOOK SYNTAX ..................................................................... 14
HEADER ............................................................................................................................................ 14
PHONEBOOK XML STRUCTURE .................................................................................................... 14
PHONEBOOK XML ELEM ENT .......................................................................................................... 15
ROOT ELEMENT <AddressBook> ............................................................................................. 16
<pbgroup> ELEMENT ................................................................................................................ 16
<Contact> ELEMENT ................................................................................................................. 17
<Phone> ELEMENT ................................................................................................................... 18
XML PHONEBO OK EXAMPLE .................................................................. 19
FIRMWARE VERS IO N 1 .0.3.2 XML BASED DOWNLOADABLE PHONEBOOK GUIDE Page 1 of 21
Table of Figure s
GXP2200 XML Based Downloadable Phone Book Guide
Figure 1: GXP2200 XML API via HTTP ....................................................................................................... 4
Figure 2: GXP2200 XML API Structure 1 .................................................................................................... 4
Figure 3: GXP2200 XML API Structure 2 .................................................................................................... 5
Figure 4: Contacts->Options ....................................................................................................................... 6
Figure 5: XML Phone Book Download ........................................................................................................ 7
Figure 6: Import and Export Phone Book XML File ................................................................................... 10
Figure 7: Import Phone Book XML File: Settings ...................................................................................... 10
Figure 8: Import Phone Book XML File: Choose File .................................................................................11
Figure 9: Import Phone Book XML File: Import ..........................................................................................11
Figure 10: Export Phone Book XML File: Settings .................................................................................... 12
Figure 11: Export Phone Book XML File: Choose Directory ...................................................................... 12
Figure 12: Export Phone Book XML File: Export ....................................................................................... 13
Ta ble of Tables
GXP2200 XML Based Downloadable Phone Book Guide
Table 1: <AddressBook> Element ............................................................................................................. 16
Table 2: <pbgroup> Element ..................................................................................................................... 16
Table 3: <Contact> Element ...................................................................................................................... 17
Table 4: <Phone> Element ........................................................................................................................ 18
FIRMWARE VERS IO N 1 .0.3.2 XML BASED DOWNLOADABLE PHONEBOOK GUIDE Page 2 of 21

INTRODUCTION

The Grandstream GXP2200 supports XML based downloadable phone book for users to share and maintain a phone book remotely easily. Besides directly importing vcard/csv format contacts, loading contacts from synced-up accounts and manually editing from LCD, the GXP2200 offers this XML API as a user-friendly download method via the phone's LCD.
For the ease of efficient deployment and management, the XML phone book file could be stored on a web server for the phones to download. There are also applications that require a centralized directory server and have all phones synchronized with the server periodically.
This document specifies the Grandstream XML based downloadable phone book configuration that will be applied to GXP2200 firmware versi on 1.0.3.2 or newer. An example XML phone book file is provided at the end of this guide. Users could start a phone book by adding contacts to the example file or exporting the existed phone book file from phone's LCD.

WHAT IS XML

XML (eXtensible Markup Language) is a markup language* for documents and applications containing structured information. This information contains both content (text, pictures, input box and etc.) and an indication of what role that content plays (e.g. contents in a section header is different from contents in a footnote). Almost all documents are structured.
*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 and allows the phones to interact with external applications in a flexible and programmable manner.

XML API ARCHITECTURE

The XML based phone book downloading for the GXP2200 coul d use HTTP or TFTP as the transport protocol. The fo llow ing f igure shows how it w o rks via HTTP as an example. First, the GXP2200 initiates the HTTP GET Request to the HTTP server and waits for the response. Once the phone receives the
FIRMWARE VERS IO N 1 .0.3.2 XML BASED DOWNLOADABLE PHONEBOOK GUIDE Page 3 of 21
response with XML content in BODY, it displays the information.
Figure 1: GXP2200 XML API via HTTP
Two types of XML API architecture are introduced below, depending on whether the transaction is via LAN or Internet.
1. A transaction in the LAN may exchange informati on in the following manner. The GXP2200 sends a request to the web server via HTTP/TFTP and waits for a response with the XML contents. The web server will handle the request and communicate with the application server to get the information for the XML phone book content d isp lay. The following figure shows dow nloading XML phone book file via HTTP within a LAN.
Figure 2: GXP2200 XML API Structure 1
2. If the above Web Server accesses Internet, it could interact with outside web server and respond with real-time content to the GXP2200.
FIRMWARE VERS IO N 1 .0.3.2 XML BASED DOWNLOADABLE PHONEBOOK GUIDE Page 4 of 21
Figure 3: GXP2200 XML API Structure 2
As illustrated above, all the logic lies within the server side of the architecture. The GXP2200 phone just receives the XML documents and displays it accordingly.
FIRMWARE VERS IO N 1 .0.3.2 XML BASED DOWNLOADABLE PHONEBOOK GUIDE Page 5 of 21

XML PHONEBOOK CONFIGURATIO N

FIRMWA R E

Before the XML phone book is used on GXP2200, please make sure the firmware on the phone is upgraded to the latest version. Please refer to the following link for firmware upgrading information:
http://www.grandstream.com/support/firmware

LCD CONFIGURATION

To download the XML phone book file to GXP2200, go to LCD Menu->Contacts and tap on Options->Download to open the XML Phone Book download interface.
Figure 4: Contacts->Options
FIRMWARE VERS IO N 1 .0.3.2 XML BASED DOWNLOADABLE PHONEBOOK GUIDE Page 6 of 21
Slide
Down
Figure 5: XML Phone Book Download
Download Mode The phone book XML file could be downloaded via HTTP or TFTP. Use r s c ould als o se t i t to "OFF" to disable phone book download.
Clear The Old List If this option is set to "Yes", all the existed entries in the GXP2200 Contacts will be automatically removed when the XML phone book is downloaded to the phone. The default value is "No".
FIRMWARE VERS IO N 1 .0.3.2 XML BASED DOWNLOADABLE PHONEBOOK GUIDE Page 7 of 21
Replace Duplicate Items If this option is set to "Yes", the duplicate entries in the Contacts will be automatically replaced with the ones in the downloaded XML phone book. The default value is "No".
File Encoding The encoding format for the XML phone book file. Users could select "UTF-8" or "GBK" (for Chinese characters). The default value is "UTF-8".
Download Server This specifies the path where the phone is going to download the XML phone book file. Since download method is already specified in the previous selection, users do not have to provide this information in the server path. The accepted format are as follows:
IP_address[:port]/dir Hostname[:port]/dir
Examples:
192.168.40.10/XMLphonebookdir
192.168.40.10:443/XMLphonebookdir
service.mycompany.com/XML/phonebook mycompany.com:8080/phonebook
Note:
1. If "[:port]" is not specified, port 80 will be used as default for HTTP and Port 69 will be used as
default for TFTP;
2. The GXP2200 will always look for the phone book file phonebook.xml for downloading if no file
name is specified in the server path. Users coul d also change the phone book name if desired. In this case, the file name needs to be specified in the server path (e.g.,
192.168.40.10/XML/gxp2200contacts.xml).
Interval This specifies the phone book automatic dow nload interv a l (in m inutes ). The va lid va lue is 0, 120, 240, 360, 480 and 720. If it's set to 0, automatic download will be disabled.
After the above configuration, tap on "OK" to save the change. Users could also always tap on "Download Now" to start the downloading process.
FIRMWARE VERS IO N 1 .0.3.2 XML BASED DOWNLOADABLE PHONEBOOK GUIDE Page 8 of 21

PROVISIONING

Users may also use the config file to provision the phone with the above XML phone book downloading options. In th is case, the GXP2200 needs to be rebooted and provisioned. The co rresp ond in g P values are as shown below.
P330: Download Mode. Possible values: 1 (HTTP) / 2 (TFTP); other values are ignored. The default value is 0.
P1435: Clear The Old List. Possible values: 0 (No) / 1 (Yes); other values are ignored. The default value is 0.
P1436: Replace Duplicate Items. Possibl e values: 0 (No) / 1 (Yes); other values are ignored. The default value is 0.
P1681: File Encoding. Possible values: UTF-8 / GBK; other values are ignored. The default value i s UTF-8.
P331: Download Server. This is a stri ng f or t he path to download the phonebook.xml fil e. It MUST be in the host/path format.
P332: Interval (in minutes). Possible values: 0, 120, 240, 360, 480, and 720; other values are ignored. The default value is 0 (automatic download disabled).
The phone will be set up with the P values when the provisioning routine is completed. It will attempt to download the phone book XML file specified in "Download Server" with configured interval and process it. If the "Interval" is set to a non-z ero va lue, a recurring t im er w ill be activate d periodically to check the phone book file in the server and the phone will repeat this process automatically.
Note:
1. As you may know, it i s also possible to enter the XML phone book file server path into a web
browser. In this way you’ll be ab le to see t he e x act XM L docum ent on your P C that y our phone will be receiving.
2. The downloaded XML phone book file can be displayed but it won't be saved internally on the
phone. It is recommended to save the XML phone book file externally on your PC or server for your reference and future use.

IMPORT/EXPORT PHONEBOOK

Besides downloading phone book file from remote server, users could also directly import phonebook.xml to the GXP2200 in the LCD from local storage/USB storage/SD card. If there is an existing phone book in the phone's Contacts already, users may export the file to internal storage/USB storage/SD card as well. The "Import" and "Export" settings are under LCD Menu->Contacts->Options.
FIRMWARE VERS IO N 1 .0.3.2 XML BASED DOWNLOADABLE PHONEBOOK GUIDE Page 9 of 21
Figure 6: Import and Export Phone Book XML File
Import Tap on "Import" in Contacts->Options and the following figure will show. Configure import options "Clear The Old List", "Replace Duplicate Items", "File Encoding" format (UTF-8 or GBK) and select "Fi le Type" as "xml". Then tap on "Choose file" button to specify the path where the phonebook.xml is located in the internal storage or USB storage/SD card.
Figure 7: Import Phone Book XML File: Settings
FIRMWARE VERS IO N 1 .0.3.2 XML BASED DOWNLOADABLE PHONEBOOK GUIDE Page 10 of 21
Figure 8: Import Phone Book XML File: Choose File
After selecting the file, tap on "OK" to start importing (see figure below).
Figure 9: Import Phone Book XML File: Import
Export Tap on "Export" in Contacts->Options and the following figure will show. Select "File Encoding" format (UTF-8 or GBK) and "File Type" as "xml". Then tap on "Choose Directory" to specify the path where the phonebook.xml will be saved.
FIRMWARE VERS IO N 1 .0.3.2 XML BASED DOWNLOADABLE PHONEBOOK GUIDE Page 11 of 21
Figure 10: Export Phone Book XML File: Settings
Figure 11: Export Phone Book XML File: Choose Directory
After specifying the path, tap on "OK" to start exporting (see figure below).
FIRMWARE VERS IO N 1 .0.3.2 XML BASED DOWNLOADABLE PHONEBOOK GUIDE Page 12 of 21
Figure 12: Export Phone Book XML File: Export
FIRMWARE VERS IO N 1 .0.3.2 XML BASED DOWNLOADABLE PHONEBOOK GUIDE Page 13 of 21

XML PHONEBOOK SYNTAX

HEADER

In the first line of the XML document, the following header can be set as XML declaration. It defines the XML version and encoding. On the GXP2200, UTF-8 and GBK can be used as encoding method for correct display. Example:
<?xml version="1.0" encoding="UTF-8"?>

PHONEBOOK XML STRUCTURE

An XML phone book example for GXP2200 can be found in the last section of this document. The main structure is represented as below.
FIRMWARE VERS IO N 1 .0.3.2 XML BASED DOWNLOADABLE PHONEBOOK GUIDE Page 14 of 21
<AddressBook> <version>Enter version number here. Usually 1</version> <pbgroup> <id>Enter group id here</id> <name>Enter group nam e here</name> <ringtones>Enter ring tone URL for the group</ringtones> </pbgroup> <pbgroup>
<!-- Enter another group information here, same format as above -->
</pbgroup> <Contact> <FirstName>Enter first name here</FirstName> <LastName>Enter last name here</LastName> <Primary>Primary number o r not</Primary> <Frequent>Favorite contact or not</Frequent> <Ringtone>Enter ring tone URL here</Ringtone> <Phone type="Specify phone type here"> <phonenumber>Enter phone number here</phonenumber> <accountindex>Enter account index here</accountindex> </Phone> <Mail type="Specify phone type here">Enter Email address here</Mail> <Group>Enter group ID here</Group> </Contact> <Contact>
<!-- Enter another contact information here, same format as above -->
</Contact> </AddressBook>

PHONEBOOK XML ELEMENT

This section describes det a ils of the XML element used in GXP2200 XML phone book file. Please not e that the element name is case-sensitive when being used in XML document.
FIRMWARE VERS IO N 1 .0.3.2 XML BASED DOWNLOADABLE PHONEBOOK GUIDE Page 15 of 21

ROOT ELEMENT <AddressBook>

The directory/path to the ring tone file
</AddressBook>
<AddressBook> is the root element of the XML document. This element is mandatory.
<AddressBook>
<!-- Enter phone bo ok informati on her e -->
Table 1: <AddressBook> Element
Object Position Type Values Comments
AddressBook Root element Mandatory - Root ele m ent of the XML document
version Child element Optional Number XML format version number. Usually 1. pbgroup Child element Optional - Define groups. Contact Child element Mandatory - Each contact is a phone book entry.

<pbgroup> ELEMENT

<pbgroup> <id>Enter group id here</id> <name>Enter group name here</name> <ringtones>Enter ring tone URL for the gro up</ringtones> </pbgroup>
Table 2: <pbgroup> Element
Object Position Type Values Comments
pbgroup Element Optional - Each pbgrou p i s a group. More th an 1
group can be defined
id Child element Optional Number To specify group ID. name Child element Mandatory String Group name. ringtones Child element Optional String
stored in the GXP2200.
FIRMWARE VERS IO N 1 .0.3.2 XML BASED DOWNLOADABLE PHONEBOOK GUIDE Page 16 of 21

<Contact> ELEMENT

Specify first name and last name. At least
For example, the contact has 3 different
is 0, the first number will be used as default when dialing out. If <Primary> The directory/path to the ring tone file
Specify Email address. It has attribute
<Contact> <FirstName>Enter first name here</FirstName> <LastName>Enter last name here</LastName> <Primary>Primary number o r not</Primary> <Frequent>Favorite contact or not</Frequent> <Ringtone>Enter ring tone URL here</Ringtone> <Phone type="Specify phone type here"> <phonenumber>Enter phone number here</phonenumber> <accountindex>Enter account index here</accountindex> </Phone> <Mail type="Specify mail type here">Enter Em ail address here</Mail> <Group>Enter group ID here</Group> </Contact>
Table 3: <Contact> Element
Object Position Type Values Comments
Contact Element Mandatory - Each contact is an entry
FirstName Child element Optional String LastName Child element Optional String
one of them has to be specified.
Primary Child element Optional Number Specify the default phone number.
phone numbers saved. If <Primary> value
value is 1, the second number will be used as default when dialing out.
Frequent Child element Optional Number 0: Default
1: Mark this contact as frequent/favorite
Ringtone Child element Optional String
stored in the GXP2200. Phone Child element Optional - Phone number information Mail Child element Optional String
"type". type: Work/Home/Others Group Child element Optional number Specify group ID for this contact.
FIRMWARE VERS IO N 1 .0.3.2 XML BASED DOWNLOADABLE PHONEBOOK GUIDE Page 17 of 21

<Phone> ELEMENT

<Phone type="Specify phone type here"> <phonenumber>Enter phone number here</phonenumber> <accountindex>Enter account index here</accountindex> </Phone>
Table 4: <Phone> Element
Object Position Type Values Comments
Phone Element Mandatory - It has attribute "type".
type: Work/Home/Mobile/Fax/Other
phonenumber Child element Mandatory Number Phone number accountindex Child element Mandatory Number From 0 to 5 for account 1 to account 6
FIRMWARE VERS IO N 1 .0.3.2 XML BASED DOWNLOADABLE PHONEBOOK GUIDE Page 18 of 21

XML PHONEBOOK EXAMPLE

<?xml version="1.0" encoding="UTF-8"?>
<AddressBook> <version>1</version> <pbgroup> <id>1</id> <name>Blacklist</name> <ringtones/> </pbgroup> <pbgroup> <id>2</id> <name>Work</name> <ringtones/> </pbgroup> <pbgroup> <id>3</id> <name>Friend</name> <ringtones>/app/ringtone/brokenglass.mp3</ringtones> </pbgroup> <Contact> <FirstName>John</FirstName> <LastName>Doe</LastName> <Primary>0</Primary> <Frequent>0</Frequent> <Ringtone>/system/media/audio/ringtones/Backroad.ogg</Ringtone> <Phone type="Work"> <phonenumber>8001</phonenumber> <accountindex>1</accountindex> </Phone> <Phone type="Home"> <phonenumber>3000001</phonenumber> <accountindex>0</accountindex> </Phone> <Phone type="Mobile"> <phonenumber>1234567890</phonenumber> <accountindex>0</accountindex> </Phone> <Mail type="Home">JohnDoe@mycompany.com</Mail> <Group>1</Group>
FIRMWARE VERS IO N 1 .0.3.2 XML BASED DOWNLOADABLE PHONEBOOK GUIDE Page 19 of 21
</Contact> <Contact> <FirstName>Michael</FirstName> <LastName>Tsai</LastName> <Primary>2</Primary> <Frequent>0</Frequent> <Phone type="Work"> <phonenumber>8002</phonenumber> <accountindex>1</accountindex> </Phone> <Phone type="Home"> <phonenumber>3000002</phonenumber> <accountindex>0</accountindex> </Phone> <Phone type="Mobile"> <phonenumber>1234567889</phonenumber> <accountindex>0</accountindex> </Phone> <Mail type="Other">MichaelTsai@mywebsite.com</Mail> <Group>2</Group> </Contact> <Contact> <FirstName>Alex</FirstName> <LastName>Smith</LastName> <Primary>0</Primary> <Frequent>1</Frequent> <Ringtone>/system/media/audio/ringtones/bellcore-dr1.ogg</Ringtone> <Phone type="Work"> <phonenumber>8003</phonenumber> <accountindex>0</accountindex> </Phone> <Phone type="Home"> <phonenumber>3000002</phonenumber> <accountindex>0</accountindex> </Phone> <Phone type="Mobile"> <phonenumber>2345678888</phonenumber> <accountindex>0</accountindex> </Phone> <Mail type="Work">AlexSmith@myserver.com</Mail> <Group>3</Group>
FIRMWARE VERS IO N 1 .0.3.2 XML BASED DOWNLOADABLE PHONEBOOK GUIDE Page 20 of 21
</Contact> </AddressBook>
Note:
The maximum number of contacts supported on GXP2200 is 1000. Users could open Contacts->Options->Storage status to check the number of contacts.
FIRMWARE VERS IO N 1 .0.3.2 XML BASED DOWNLOADABLE PHONEBOOK GUIDE Page 21 of 21
Loading...