Grandstream Networks, Inc.
GXP2200
XML Based Downloadable Phonebook Guide
GXP2200 XML Based Downloadable Phone Book 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...