The Grandstream GVC32XX Full HD Video Conferencing System supports XML based downloadable phonebook for users to share and maintain a phonebook remotely with ease. Besides directly importing VCard/CSV format contacts, loading contacts from synced-up accounts and manually editing from LCD or web UI, the GVC32XX offers this XML API as a user-friendly download method via the GVC32XX’s LCD and web UI.
For the ease of efficient deployment and management, the XML phonebook file could be stored on a web server for the SIP endpoints to download. There are also applications that require a centralized directory server and have all SIP endpoints synchronized with the server periodically.
This document specifies the Grandstream XML based downloadable phonebook configuration that will be applied to GVC32XX. An example XML phonebook file is provided at the end of this guide. Users could start a phonebook by adding contacts to the example file or exporting the existed phonebook file from its LCD or web UI.
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.
XML API Architecture
The XML based phonebook downloading for the GVC32XX could use HTTP or TFTP as the transport protocol. The following figure shows how it works via HTTP as an example.
First, the GVC32XX initiates the HTTP GET Request to the HTTP server and waits for the response. Once the device receives the response with XML content in BODY, it displays the information.
Two types of XML API architecture are introduced below, depending on whether the transaction is via LAN or Internet.
- A transaction in the LAN may exchange information in the following manner. The GVC32XX 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 phonebook content display. The following figure shows downloading XML phonebook file via HTTP within a LAN.
- If the above Web Server accesses Internet, it could interact with outside web server and respond with real-time content to the GVC32XX.
As illustrated above, all the logic lies within the server side of the architecture. The GVC32XX just receives the XML documents and displays it accordingly.
XML PHONEBOOK CONFIGURATION
Firmware
Before the XML phonebook is used on GVC32XX, please make sure the firmware on the device is upgraded to the latest version. Please refer to the following link for firmware upgrading information:
https://www.grandstream.com/support/firmware
Web Configuration
To configure XML phonebook file download, go to web UI -> Contacts, click on “More” icon on the bottom and select “Download” on GVC3200/3202/3210. This will open the XML Phonebook download interface in a new window.
For the GVC3220 go to web UI -> Call -> Contacts, click on “More” icon on the bottom and select “Download”.
- Clear The Old List
If this option is set to “ON”, all the existed entries in the GVC32XX Contacts will be automatically removed when the XML phonebook is downloaded to the device. The default value is “OFF”.
- Clear The Old List Mode
If set to “Clear All”, the device will delete all previous records before downloading the new records. If set to “Keep Local Contacts”, manually added local contacts will not be deleted when downloading new records.
Note:
This is only available on the GVC3220.
- Replace Duplicate Entries/Items
If this option is set to “ON”, the duplicate entries in the GVC32XX Contacts will be automatically replaced with the ones in the downloaded XML phonebook. The default value is “OFF”.
- Replace Duplicate Entries Mode
If set to “Replace by Name”, records of the same name will be replaced automatically when downloading new records. If set to “Replace by Number”, records of the same number will be replaced when downloading new records.
Note:
This is only available on the GVC3220.
- Download Mode
The phonebook XML file could be downloaded via HTTP/TFTP/HTTPS. Users could also set it to “OFF” to disable phonebook download.
- File Encoding
This option specifies the encoding format for the XML phonebook file. Users could select “UTF-8”, “GBK” (for Chinese characters), “UTF-16”, “UTF-32”, “Big5”, “Big5-HKSCS”, “SHIFT-JIS”, “ISO8859-1”, “ISO8859-15” and “Windows-1251”. The default value is “UTF-8”.
- Download Interval/Automatic Download Interval
This specifies the phonebook 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.
- Download Server
This specifies the path where the device is going to download the XML phonebook 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 is 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
- HTTP/HTTPS Username
If the HTTP/HTTPS server has access control set up that requires HTTP/HTTPS authentication, the user needs to fill up the HTTP/HTTPS username here.
- HTTP/HTTPS Password
If the HTTP/HTTPS server has access control set up that requires HTTP/HTTPS authentication, the user needs to fill up the HTTP/HTTPS password here.
Note:
- If “[:port]” is not specified, port 80 will be used as default for HTTP, port 8089 will be used as default for HTTPS, and Port 69 will be used as default for TFTP.
- The GVC32XX always looks for the phonebook file phonebook.xml for downloading if no file name is specified in the server path. Users could also change the phonebook name if desired. In this case, the phonebook file name needs to be specified in the server path. For example, if the phonebook file name is GVC320xcontacts.xml and the server directory is 192.168.40.10/XML, the download server path should be 192.168.40.10/XML/GVC320xcontacts.xml.
After the above configuration, click on “Save” to save the changes. Users could click on “Download” to start the downloading process.
LCD Configuration on GVC3200/3202/3210
Besides using the web UI to configure XML phonebook download, the users could also achieve the same configuration via GVC3200/3202/3210 LCD display using the GVC remote control.
- On the GVC3200/3202/3210 LCD main screen, click on “Contacts”.
- Press button
on the remote control and select “Download”.
on the remote control and select “Download”. 
- Use the remote control to configure phonebook download parameters, which are the same as described in section Web Configuration.
- Press the yellow shortcut key on the GVC remote control or press –> Save to save the configuration.
–> Save to save the configuration.
- The users can press the red shortcut key on the GVC remote control or press –> Download Now to download the phonebook XML immediately. Or the users can wait for the next downloading interval (if configured) for the phonebook to be downloaded to GVC3200/3202/3210.
–> Download Now to download the phonebook XML immediately. Or the users can wait for the next downloading interval (if configured) for the phonebook to be downloaded to GVC3200/3202/3210.
Note:
LCD configuration is not possible on the GVC3220.
Provisioning
Users may also use the config file to provision GVC32XX with the above XML phonebook downloading options. The corresponding P values are as shown below:
- P330: Download Mode. Possible values: 1 (TFTP) / 2 (HTTP) / 3 (HTTPS) / 0 (OFF); 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 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. 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: Download 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).
- P6713: HTTP/HTTPS Username for phonebook downloading
- P6714: HTTP/HTTPS Password for phonebook downloading
GVC32XX will be set up with the P values when the provisioning routine is completed. It will attempt to download the phonebook XML file specified in “Download Server” with configured interval and process it. If the “Download Interval” is set to a non-zero value, a recurring timer will be activated periodically to check the phonebook file in the server and the device will repeat this process automatically.
Note:
- As you may know, it is also possible to enter the XML phonebook 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.
- The downloaded XML phonebook file can be displayed but it won’t be saved internally on the device. It is recommended to save the XML phonebook file externally on your PC or server for your reference and future use.
Import/Export Phonebook
Besides downloading phonebook file from remote server, users could also directly import phonebook.xml to the GVC32XX from the web UI. If there is an existing phonebook in the device’s Contacts already, users may export the phonebook file to PC as well. The “Import” and “Export” settings are under web UI–> Contacts: More on the GVC3200/3202/3210 or under web UI –> Call –> Contacts: More on the GVC3220.
- Import
Click on “Import” and the following figure will show:
Configure import options “Clear The Old List”, “Replace Duplicate Entries”, “File Encoding” format and select “File Type” as “XML” (with “Clear The Old List Mode” and “Replace Duplicate Entries Mode” on the GVC3220 only). Then, click on “Browse” button to specify the path where the phonebook.xml is located in the PC.
After selecting the file, GVC32XX will start importing and finish importing (see figure above) automatically. If the file fails to be imported, please check the format and syntax of the phonebook xml file.
- Export
Click on “Export” and the following figure will show:
Select “File Encoding” format and select “File Type” as “XML”. Then, click on “Export” to download phonebook.xml, this file will be saved in PC, under the default downloading directory.
Note:
- The Import/Export options are also available in GVC3200/3202/3210 LCD main screen 🡪 Contacts. Click on 🡪 select Import/Export.
🡪 select Import/Export.- For “Import”, the phonebook file needs to be located in GVC3200/3202/3210 file system or SD card/USB storage plugged into the GVC for selection; for “Export”, choose the GVC file system directory for the phonebook xml file to be saved to.
- The users could manually add contacts to GVC3200/3202/3210 via web UI or LCD first, and then export the phonebook XML file, which can be used as a template of phonebook xml file to import or download.
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 GVC32XX, UTF-8, GBK, UTF-16, UTF-32, Big5, Big5-HKSCS, SHIFT-JIS, ISO8859-1, ISO8859-15 and Windows-1251 can be used as encoding method for correct display. Example:
<?xml version=”1.0″ encoding=”UTF-8″?>
Phonebook XML Structure
An XML phonebook example for GVC32XX can be found in the last section of this document. The main structure is represented as below. (Some of the elements are optional).
Phonebook XML Element
This section describes details of the XML element used in GVC32XX XML phonebook file. Please note that the element name is case-sensitive when being used in XML document.
ROOT Element <AddressBook>
<pbgroup> Element
<pbgroup>
<id>Enter group id here</id>
<name>Enter group name here</name>
<ringtones>Enter ring tone URL for the group</ringtones>
</pbgroup>
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 GVC32XX. |
<Contact> Element
<Contact>
<FirstName>Enter first name here</FirstName>
<LastName>Enter last name here</LastName>
<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>
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 | |
Phone | Child element | Optional | - | Phone number information |
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. |
Table 2: <Contact> Element
<Phone> Element
<Phone type=”Specify phone type here“>
<phonenumber>Enter phone number here</phonenumber>
<accountindex>Enter account index here</accountindex>
</Phone>
Object | Position | Type | Values | Comments |
Phone | Element | Mandatory | – | It has attribute “type”. Type: Work/Home/Mobile/Fax/Others |
Phonenumber | Child element | Mandatory | Number | Phone number |
accountindex | Child element | Mandatory | Number | From 0 to 5 for account 1 to account 6 |
<?xml version=”1.0″ encoding=”UTF-8″?>
<AddressBook>
<version>1</version>
<pbgroup>
<id>1</id>
<name>Work</name>
<ringtones/>
</pbgroup>
<Contact>
<FirstName>Jane</FirstName>
<LastName>Doe</LastName>
<Phone type=”Work”>
<phonenumber>81234567</phonenumber>
<accountindex>1</accountindex>
</Phone>
<Mail type=”Other”>JaneDoe@mycompany.com</Mail>
<Group>1</Group>
</Contact>
<Contact>
<FirstName>Alex</FirstName>
<LastName>Smith</LastName>
<Phone type=”Home”>
<phonenumber>1234567890</phonenumber>
<accountindex>1</accountindex>
</Phone>
<Mail type=”Other”>smith.alex@mycompany.com</Mail>
</Contact>
<Contact>
<FirstName>John</FirstName>
<LastName>Williams</LastName>
<Phone type=”Mobile”>
<phonenumber>5432154321</phonenumber>
<accountindex>1</accountindex>
</Phone>
<Mail type=”Home”>Johnwilliams@mycompany.pbx.com</Mail>
</Contact>
</AddressBook>
SUPPORTED DEVICES
Following table shows Grandstream products supporting xml phonebook protocol.
Model | Firmware |
GVC3200/3202 | 1.0.1.74 or higher |
GVC3210 | 1.0.1.69 or higher |
GVC3220 | 1.0.1.24 or higher |
