Grandstream Networks GXV3240 User manual

GXV3240 XML Based Downloadable Phonebook Guide
Grandstream Networks, Inc.
GXV3240 IP Multimedia Phone for AndroidTM
XML Based Downloadable Phonebook Guide

GXV3240 XML Based Downloadable Phonebook Guide
Page 1 of 21
GXV3240 XML Based Downloadable Phone Book Guide
Index
INTRODUCTION ........................................................................................3
WHAT IS XML........................................................................................................................................3
WHY XML ..............................................................................................................................................3
XMLAPI 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 ELEMENT ...........................................................................................................15
ROOT ELEMENT <AddressBook>...............................................................................................16
<pbgroup> ELEMENT ..................................................................................................................16
<Contact> ELEMENT...................................................................................................................17
<Phone> ELEMENT.....................................................................................................................18
XML PHONEBOOK EXAMPLE................................................................19

GXV3240 XML Based Downloadable Phonebook Guide
Page 2 of 21
Table of Figures
GXV3240 XML Based Downloadable Phone Book Guide
Figure 1: GXV3240 XMLAPI via HTTP ........................................................................................................4
Figure 2: GXV3240 XMLAPI Structure 1......................................................................................................4
Figure 3: GXV3240 XMLAPI Structure 2......................................................................................................5
Figure 4: Contacts->Menu.............................................................................................................................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
Table of Tables
GXV3240 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

GXV3240 XML Based Downloadable Phonebook Guide
Page 3 of 21
INTRODUCTION
The Grandstream GXV3240 supports XML based downloadable phone book for users to share and
maintain a phone book remotely with ease. Besides directly importing vcard/csv format contacts, loading
contacts from synced-up accounts and manually editing from LCD, the GXV3240 offers this XML API as a
user-friendly downloading method via the phone's LCD and web UI.
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 GXV3240 firmware version 1.0.1.20 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 GXV3240 could use HTTP or TFTP as the transport
protocol. The following figure shows how it works via HTTP as an example. First, the GXV3240 initiates the
HTTP GET Request to the HTTP server and waits for the response. Once the phone receives the

GXV3240 XML Based Downloadable Phonebook Guide
Page 4 of 21
response with XML content in BODY, it displays the information.
Figure 1: GXV3240 XML API via HTTP
Two types of XMLAPI architecture are introduced below, depending on whether the transaction is via LAN
or Internet.
1. A transaction in the LAN may exchange information in the following manner. The GXV3240 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 display. The following figure shows downloading XML phone book file via
HTTP within a LAN.
Figure 2: GXV3240 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 GXV3240.

GXV3240 XML Based Downloadable Phonebook Guide
Page 5 of 21
Figure 3: GXV3240 XML API Structure 2
As illustrated above, all the logic lies within the server side of the architecture. The GXV3240 phone just
receives the XML documents and displays it accordingly.

GXV3240 XML Based Downloadable Phonebook Guide
Page 6 of 21
XML PHONEBOOK CONFIGURATION
FIRMWARE
Before the XML phone book is used on GXV3240, 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 GXV3240, go to LCD Menu->Contacts and tap on
Menu->Download to open the XML Phone Book download interface.
Figure 4: Contacts->Menu

GXV3240 XML Based Downloadable Phonebook Guide
Page 7 of 21
Figure 5: XML Phone Book Download
Download Mode
The phone book XML file could be downloaded via HTTP or TFTP. Users could also set it to "OFF" to
disable phone book download.
Delete the History
If this option is set to "ON", all the existed entries in the GXV3240 Contacts will be automatically
removed when the XML phone book is downloaded to the phone. The default value is "OFF".
Replace duplicate entries
If this option is set to "ON", the duplicate entries in the Contacts will be automatically replaced with the
ones in the downloaded XML phone book. The default value is "OFF".
Slide
Down

GXV3240 XML Based Downloadable Phonebook Guide
Page 8 of 21
File encoding
The encoding format for the XML phone book file. Users could select "UTF-8", "GBK" (for Chinese
characters), "UTF-16", "UTF-32", "Big5", "Big5-HKSCS", "SHIFT-JIS", "ISO8859-1", "ISO8859-15",
"Windows-1251" and "EUC-KR". 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 GXV3240 will always look for the phone book file phonebook.xml for downloading if no file
name is specified in the server path. Users could also change the phone book name if desired. In
this case, the phone book file name needs to be specified in the server path. For example, if the
phone book file name is GXV3240contacts.xml and the server directory is 192.168.40.10/XML, the
download server path should be 192.168.40.10/XML/GXV3240contacts.xml.
Time Interval
This allows users to select the phone book automatic download time interval. The available intervals
are 2 hour, 4 hour, 6 hour, 8 hour and 12 hour. If it's set to None, automatic download will be disabled.
After the above configuration, tap on "Save" to save the change. Users could also always tap on
"Download Now" to start the downloading process.

GXV3240 XML Based Downloadable Phonebook Guide
Page 9 of 21
PROVISIONING
Users may also use the config file to provision the phone with the above XML phone book downloading
options. In this case, the GXV3240 needs to be rebooted and provisioned. The corresponding 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: Delete the History. Possible values: 0 (No) / 1 (Yes); other values are ignored. The default
value is 0.
P1436: Replace duplicate entries. Possible values: 0 (No) / 1 (Yes); other values are ignored. The
default value is 0.
P1681: File encoding. Possible values: UTF-8, GBK, UTF-16, UTF-32, Big5, Big5-HKSCS, SHIFT-JIS,
ISO8859-1, ISO8859-15, Windows-1251, EUC-KR. The default value is UTF-8.
P331: Download Server. This is a string for the path to download the phonebook.xml file. It MUST be
in the host/path format.
P332: Time Interval (in minutes). Possible values: 0 - "None", 120 - "2 hour", 240 - "4 hour", 360 - "6
hour", 480 - "8 hour", and 720 - "12 hour"; 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 "Time Interval" is set to a non-zero value, a recurring timer will be activated 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 is also possible to enter the XML phone book file server path into a web
browser. In this way you’ll be able to see the exact XML document on your PC that your 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 GXV3240 in the LCD from local storage/USB storage/SD card. If there is an existing phone book in

GXV3240 XML Based Downloadable Phonebook Guide
Page 10 of 21
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->Menu.
Figure 6: Import and Export Phone Book XML File
Import
Tap on "Import" in Contacts->Menu and the following figure will show.
Figure 7: Import Phone Book XML File: Settings

GXV3240 XML Based Downloadable Phonebook Guide
Page 11 of 21
Configure import options "Delete the History", "Replace duplicate entries", "File encoding" format and
select "File Type" as "xml". Then tap on "Select the file" button to specify the path where the
phonebook.xml is located in the internal storage or USB storage/SD card.
Figure 8: Import Phone Book XML File: Choose File
After selecting the file, tap on "OK" to start importing.
Figure 9: Import Phone Book XML File: Import
Export
Tap on "Export" in Contacts->Menu and the following figure will show.

GXV3240 XML Based Downloadable Phonebook Guide
Page 12 of 21
Figure 10: Export Phone Book XML File: Settings
Select "File encoding" format and "File Type" as "xml". Then tap on "Choose Directory" to specify the
path where the phonebook.xml will be saved.
Figure 11: Export Phone Book XML File: Choose Directory
After specifying the path, tap on "OK" to start exporting.

GXV3240 XML Based Downloadable Phonebook Guide
Page 13 of 21
Figure 12: Export Phone Book XML File: Export

GXV3240 XML Based Downloadable Phonebook Guide
Page 14 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 GXV3240, UTF-8, GBK, UTF-16, UTF-32, Big5, Big5-HKSCS,
SHIFT-JIS, ISO8859-1, ISO8859-15, Windows-1251, and EUC-KR can be used as encoding method for
correct display. Example:
PHONEBOOK XML STRUCTURE
An XML phone book example for GXV3240 can be found in the last section of this document. The main
structure is represented as below.
<?xml version="1.0" encoding="UTF-8"?>

GXV3240 XML Based Downloadable Phonebook Guide
Page 15 of 21
PHONEBOOK XML ELEMENT
This section describes details of the XML element used in GXV3240 XML phone book file. Please note that
the element name is case-sensitive when being used in XML document.
<AddressBook>
<version>Enter version number here. Usually 1</version>
<pbgroup>
<id>Enter group id here</id>
<name>Enter group name 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 or 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>

GXV3240 XML Based Downloadable Phonebook Guide
Page 16 of 21
ROOT ELEMENT <AddressBook>
<AddressBook> is the root element of the XML document. This element is mandatory.
Table 1: <AddressBook> Element
Object
Position
Type
Values
Comments
AddressBook
Root element
Mandatory
-
Root element 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
Table 2: <pbgroup> Element
Object
Position
Type
Values
Comments
pbgroup
Element
Optional
-
Each pbgroup is a group. More than 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
The directory/path to the ring tone file
stored in the GXV3240.
<AddressBook>
<!-- Enter phone book information here -->
</AddressBook>
<pbgroup>
<id>Enter group id here</id>
<name>Enter group name here</name>
<ringtones>Enter ring tone URL for the group</ringtones>
</pbgroup>

GXV3240 XML Based Downloadable Phonebook Guide
Page 17 of 21
<Contact> ELEMENT
Table 3: <Contact> Element
Object
Position
Type
Values
Comments
Contact
Element
Mandatory
-
Each contact is an entry
FirstName
Child element
Optional
String
Specify first name and last name. At least
one of them has to be specified.
LastName
Child element
Optional
String
Primary
Child element
Optional
Number
Specify the default phone number.
For example, the contact has 3 different
phone numbers saved. If <Primary> value
is 0, the first number will be used as
default when dialing out. If <Primary>
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
The directory/path to the ring tone file
stored in the GXV3240.
Phone
Child element
Optional
-
Phone number information
Mail
Child element
Optional
String
Specify Email address. It has attribute
"type". type: Work/Home/Others
Group
Child element
Optional
number
Specify group ID for this contact.
<Contact>
<FirstName>Enter first name here</FirstName>
<LastName>Enter last name here</LastName>
<Primary>Primary number or 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 Email address here</Mail>
<Group>Enter group ID here</Group>
</Contact>

GXV3240 XML Based Downloadable Phonebook Guide
Page 18 of 21
<Phone> ELEMENT
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
<Phone type="Specify phone type here">
<phonenumber>Enter phone number here</phonenumber>
<accountindex>Enter account index here</accountindex>
</Phone>

GXV3240 XML Based Downloadable Phonebook Guide
Page 19 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/system/media/audio/ringtones/Bollywood.ogg</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">[email protected]</Mail>
<Group>1</Group>