Grandstream Networks GXV-3140 User manual

Grandstream Networks, Inc.
GXV3140 IP Multimedia Phone
GMI HTML SDK and API Guide

Grandstream Networks, Inc. GMI HTML SDK and API Guide Page 2 of 43
www.grandstream.com Last Updated: 09/2010
1 What is GMI?
GMI (Grandstream Manager Interface) is a management API developed by
Grandstream Networks. It is designed for our IP Multimedia phones, and allows partners
to develop customized applications on the phone.
GMI supports standard HTML/CSS/Javascript code, so that users can use these
dynamic web page development languages to develop their customized application. GMI
will display the application on the phone based on the pages generated.
Additionally, GMI provides several basic API functions (packaged in Javascript) so
that users can call the existing applications on the multimedia phone or obtain the phone
status etc…This allows users with basic web application programming skills to develop
their customized application on the multimedia phone easily, without learning a new
programming language. All that is required is for the user to understand how the GMI
works and how to use these simple APIs to interact with the phone.
2 GMI Working Model
The GMI working model is a cross-domain model; it must interact with servers in two
domains to implement the functions needed.
Interact with the user’s web server: Send page request, obtain page content and
remodel it for display as an application on the multimedia phone.
Interact with the GMI server on the phone：Control the phone behavior (e.g. initiate
a call, launch the phonebook application etc...) by calling the Javascript packaged
GMI interface.
Therefore, by interacting with the user’s web server, it obtains the user-defined
display content, style and data for the customized application and redraw it for display
on the phone (at this point, it is similar to a browser). When any action from the phone
is needed (e.g. making a call, launching some applications on the phone etc…), it is
then required to control the phone behavior through calling the GMI API functions.
Refer to the GMI Working Model below:

Grandstream Networks, Inc. GMI HTML SDK and API Guide Page 3 of 43
www.grandstream.com Last Updated: 09/2010
Figure 1: GMI Working Model
3 How do I add a GMI application?
To use the GMI application, users need to add the following in menu.xml:
<link icon="icon/Grandstream.png" dynamic-icon="icon/Grandstream.gif" display-name="GMI" t
ype="gmiapp">
<link-url>
www.grandstream.com/support/gxv_series_phone/gxv3140/resources/gxv3140_gmi_example
</link-url>
</link>
This line of code will add a menu selection in your phone menu called “GMI Example”.
The parameter “Icon”specifies the icon displayed and the parameter “dynamic-icon”
specifies the icon displayed when it is selected. The parameter func-name="gmiapp"
specifies that this is a GMI application, and the parameter “url” specifies the URL address
at which this application is stored. In this example, the phone will point to
www.grandstream.com/support/gxv_series_phone/gxv3140/resources/gxv3140_gmi_exa
mple to get the corresponding application to display on the phone. The parameter
“display-name” specifies the text displayed in the phone menu and the parameter “ver”
specifies the menutree version. Users can modify these four parameters -
icon/dynamic-icon/url/display-name to suit their needs.

Grandstream Networks, Inc. GMI HTML SDK and API Guide Page 4 of 43
www.grandstream.com Last Updated: 09/2010
For more details regarding menu.xml, please refer to the following document:
《GXV31XX XML Based GUI Customization Guide》.
The example files are available for download here.
4 GMI API Description
In order to facilitate the ease of controlling the phone behavior within the html code,
we have developed and provided several basic API functions (packaged in Javascript).
This chapter provides introduction to all theAPI functions available.
4.1 GMIEngine.refresh()
Function: GMIEngine.refresh()
Purpose: Used to refresh the current page. The phone will o
btain the current
page from the web server and reload the page on the phone.
Parameter and Return
Value:Parameter:
None
Return Value:
None
Additional Description: This API function is mainly used for testing during development.
It is
advised to remove this function call
in your program before official
release, so that the program will run as smoothly as the built-
in
applications on the phone, providing users with
better user
experience.
4.2 GMIEngine.historypage()
Function: GMIEngine.historypage(num)
Purpose: Go to the pages visited in history, as specified by num.
Parameter and Return
Value:Parameter:
num - Any natural number. Negative numbers
represents the
number of page records to go backward. 0 represen
ts the current
page. Positive numbers
represents the number of page records to

Grandstream Networks, Inc. GMI HTML SDK and API Guide Page 5 of 43
www.grandstream.com Last Updated: 09/2010
go forward.
For example, the user visited these web pages
in this order:
www.google.com, www.yahoo.com and www.baidu.com.
When the
user is browsing the webpage www.baidu.com
, the function call to
GMIEngine.historypage(-1) will allow the user to return to
the last
page visited (returning to www.yahoo.com)
. At this point, the last
page visited will be www.google.com
, if the function call
GMIEngine.historypage(-1) is called again, the
user will return to
www.google.com. If the num specified is a non-existent
record,
nothing will take effect.
Return Value:
None
Additional Description: This API function can be used to implement the “back” functi
on for
the softkey, allowing users to re-visit the upper level menus.
4.3 GMIEngine.gotourl()
Function: GMIEngine.gotourl(url)
Purpose: Go to the URL address specified in the url parameter.
Parameter and Return
Value:Parameter:
url – Can be any URL address.
Return Value:
None
Additional Description: This API function is used to implement a hyperlink.
4.4 GMIEngine.call()
Function: GMIEngine.call(acct, number, cb_call)
Purpose: Used to call a specified number from a specified account.
Parameter and Re
turn
Parameter:

Grandstream Networks, Inc. GMI HTML SDK and API Guide Page 6 of 43
www.grandstream.com Last Updated: 09/2010
Value:acct – Specifies the account used to dial out. (Starting from 0).
number – Specifies the number to call to.
cb_call - Callback function after the call request
is sent. The
function prototype is function cb_call(result), the paramete
r
“result” is the response to the call request
result is a text string in json format.
For example,
{"Response":" Success", ","Message": "Call Originate" }
or
{"Response": "ERROR", ","Message": "User can't be null"");
“Response” returns the result. There
are two
possibilities- “Success” or “ERROR”, “Message”
returns the
specific error message.
Return Value:
None
Additional Description: None
4.5 GMIEngine.getURI()
Function: GMIEngine. getURI (acct, cb_get)
Purpose: Used to obtain the URI of the specified account
Parameter and Return
Value:
Parameter:
acct – Specifies the account to be used. (Starting from 0)
cb_get—
Callback function after the getURI request is sent. The
function prototype is function cb_get(result)，
the parameter
“result” is the response to the function call.
result is a text string in json format. For example,
{"Response":"Success",","Message": "[email protected]:48879"}
or
{"Response": "ERROR", ","Message": "Acct can't be null"");
“Response”
returns the result. There are two
possibilities- “Success” or “ERROR”, “Message” returns the URI
.
When the specified account is configured, the URI returned will
contatin “@”.
Return Value:
None

Grandstream Networks, Inc. GMI HTML SDK and API Guide Page 7 of 43
www.grandstream.com Last Updated: 09/2010
Additional Description: None
4.6 GMIEngine. hangup()
Function: GMIEngine. hangup(cb_hangup)
Purpose: Used to hang up the current call
Parameter and Return
Value:
Parameter:
cb_hangup—
Callback function after the hangup request is sent.
The function prototype is function cb_ hangup (result), ”result”
is
the response to the hangup function call.
Return Value:
None
Additional Description: None
4.7 GMIEngine. getstate()
Function: GMIEngine. getstate (acct, cb_get)
Purpose: Used to obtain the state of the specified account
Parameter and Return
Value:
Parameter:
acct—Specifies the account (starting from 0)
cb_get—Callback function after the gestate request
is sent. The
function prototype is function cb_ get (result)，”result”
is the
response to the getstate function call.
result is a text string in json format
. For example, if the
function call is:
GMIEngine.getstate(0, cb_get)
If account 1 is currently in a call on line 1 with 810010
0, it
will return the following:
{"Response":"Success","registered":"1","line":"1","line-0“ : ”8100100"};
This specifies that account 1
is registered and using 1
line, it is currently in a call with 8100100 on line 1.
If account 1 is idle, the response will be as follows:
{"Response":"Success","registered": "1", "line": "0"};

Grandstream Networks, Inc. GMI HTML SDK and API Guide Page 8 of 43
www.grandstream.com Last Updated: 09/2010
This specifies that account 1 is registered and is not
using any line currently.
Return Value:
None
Additional Description: None
4.8 GMIEngine.launch()
Function: GMIEngine.launch(program,cb_launch)
Purpose: Used to launch the program specified.
Parameter and Return
Value:Parameter:
program – Specifies the program to be launched
using the
program code.
See the program (program name as displayed on the phone) and
the corresponding program code below:
Phone Book--"phonebook"
Call History--"callhistory"
Messages--"messages"
Social Networks --"socialnetwork"
IM--"IM"
Twitter--"twitter"
Facebook--"facebook"
Google Voice--"googlevoice"
Skype--"skype"
Web Browser--"webbrowser"

Grandstream Networks, Inc. GMI HTML SDK and API Guide Page 9 of 43
www.grandstream.com Last Updated: 09/2010
Multimedia--"multimedia"
Gstris--"gstris"
Photo Viewer--"gphoto"
Photo Album--"webalbum"
Media Player--"player"
Internet Radio--"internetradio"
Online Music--"onlinemusic"
News Videos--"mulnews"
Online Video--"onlinevideo"
World Photos--"panoramio"
Slide Show--"slide_show"
Applications--"officetools"/"application"
Calendar--"calendar"
Alarm Clock--"alarmclock"
Calculator--"calculator"
Weather-"weatherupdate"
Direct IP Call--"ipcall"
File Manager--"filemanager"
Stock--"stock"
Currencies--"currencies"
IP2Location--"ip2location"
Today--"today"
Settings--"settings"
Display--"display"
Time--"time"
Accounts--"account"
Network--"connection"
Maintenance--"maintenance"
Call Features--"callfeature"
Camera--"camera"

Grandstream Networks, Inc. GMI HTML SDK and API Guide Page 10 of 43
www.grandstream.com Last Updated: 09/2010
Video Setting--"video"
FXO Setting--"fxo"（
This is only applicable to phones to FXO
support）
Personalize--"personalize"
Softkeys--"softkey_def"
Screen Saver--"screen_display"
RSS News--"rssnews"
Screen Layout--"screen_layout"
Language--"language"
My Profile--"myprofile"
Tones--"tones"
Horoscopes--"horoscope"
Info--"status"
cb_launch— Callback function after the launch request
is sent.
The function prototype is function cb_launch(result)
, the
parameter “result” is the response to the launch request
result is a text string in json format. For example, {"Response":"
Success", ","Message": " Launch Originate" } or
{"Response":
"ERROR", ","Message": " Program can't be null"");
“Response” returns the result. There are two possibilities-
“Success” or “ERROR”, “Message”
returns the specific error
message.
Return Value:
None
Additional Description:None
4.9 GMIEngine.message()
Function: GMIEngine.message(acct, user, msg, cb_message)

Grandstream Networks, Inc. GMI HTML SDK and API Guide Page 11 of 43
www.grandstream.com Last Updated: 09/2010
Purpose: Send message to a specified number from a specified account.
Parameter and Return
Value:Parameter:
acct- Specifies the account used to send the message. (Sta
rting
from 0).
user- Specifies the number to send the message to.
msg- Message Body
cb_message - Callback function for the send message request
.
The function prototype is function cb_message(result)
, the
parameter “result” is the response to the message request
result is a text string in json format.
For example,
{"Response":" Success", ","Message": “Message Send"}
or
{"Response": "ERROR", ","Message": "MSG can't be null").
“Response”
returns the result. There are two
possibilities- “Success” or “ERROR”, “Message”
returns the
specific error message.
Return Value:
None
Additional Description: None
4.10 GMIEngine.exit()
Function: GMIEngine.exit()
Purpose: Exit the GMI.
Calling this function will exit the customized
application remodeled on the phone by th
e GMI and will release the
resources.
Parameter and Return
Value:Parameter:
None
Return Value:
None
Additional Description: This API function can be used to implement the “Exit”
softkey for
the application implemented using GMI.

Grandstream Networks, Inc. GMI HTML SDK and API Guide Page 12 of 43
www.grandstream.com Last Updated: 09/2010
4.11 GMIEngine.backspace()
Function: GMIEngine.backspace()
Purpose: Simulates the backspace function for a keyboard.
Parameter and Return
Value:Parameter:
None
Return Value:
None
Additional Description: This API function is used to delete the characters in the input box.
4.12 GMIEngine.mapleftright2tab ()
Function: GMIEngine.mapleftright2tab ()
Purpose:
Map the left/right button functions to tab. Pressing the Left button
will be equivalent of pressing the alt+tab button; the previous
control component will be highlighted.
Pressing the Right button will
be equivalent of pressing the tab button;
the next control
component will be highlighted.
Parameter and Return
Value: Parameter:
None
Return Value:
None
Additional Description: This API function is used to change the
functions of the left/right
button,
so that the different control components can be selected
using the left/right button.
4.13 GMIEngine.mapupdown2tab()
Function: GMIEngine.mapupdown2tab()

Grandstream Networks, Inc. GMI HTML SDK and API Guide Page 13 of 43
www.grandstream.com Last Updated: 09/2010
Purpose: Map the up/down button functions to tab. Pressing the Up bu
tton
will be equivalent of pressing the alt+tab button; the previous
control component will be highlighted. Pressing the Down button
will be equivalent of pressing the tab button;
the next control
component will be highlighted.
Parameter and Return
Value:Parameter:
None
Return Value:
None
Additional Description: This API function
is used to change the functions of the up/down
button
, so that the different control components can be selected
using the up/down button.
4.14 GMIEngine.revokemap()
Function: GMIEngine.revokemap()
Purpose:
Revoke the mapping between the up/down or left/right button with
the tab button.
Parameter and Return
Value:Parameter:
None
Return Value:
None
Additional Description: None
4.15 GMIEngine. play ()
Purpose: Play the designated audio/video file from the URL
Parameter and Return
Value: Parameter:
url –
Specifies the URL of the audio/video file. If there are several
files, use “;” to separate them.
mode – Play Mode. Currently there are two modes，0：Play once
；
1：Repeat.
Callback function for the GMIEngine.play function. The function

Grandstream Networks, Inc. GMI HTML SDK and API Guide Page 14 of 43
www.grandstream.com Last Updated: 09/2010
prototype is function cb_play(result), the parameter “result” is the
response to the GMIEngine.play request.
result is a text string in json format. For example, {"Response":"
Success", ","Me
ssage": " Play Originate" }; “Response” returns the
result. There are two possibilities-
“Success” or “ERROR”,
“Message” returns the response message.
Return Value:
None
Additional Description: None
4.16 GMIEngine. udp ()
Function: GMIEngine.udp (host, port, data, timeout, cb_udp)
Purpose: Send packets to the specified UDP port of the host/server
Parameter and Return
Value: Parameter:
host -- Destination server URL or IP address
port -- Destination UDP port
data -- Data to be sent (String)
timeout –
The timeout time for waiting for the reponse from the
server. The unit is in seconds.
cb_udp –
Callback function for the UDP function. The function
prototype is function cb_udp(result), the parameter “result” is the
response to the send UDP request.
result is a text string in json format. For example, {"Response":"
Success", "," Message": "Light Off
"}; “Response” returns the result.
There are two possibilities-
“Success” or “ERROR”, “Message”
returns the response message returned by the destination server.
Return Value:
None
Additional Description: None
4.17 GMIEngine.transfer()
Function: GMIEngine.transfer ()

Grandstream Networks, Inc. GMI HTML SDK and API Guide Page 15 of 43
www.grandstream.com Last Updated: 09/2010
Purpose: Activate transfer mode
Note：Activate transfer mode. This will only work when current line
is connected (You can use the function GMIEngine.getstate() to
get
the current state of the lines). Additionally, the transfer mode will
also be activated when the “Transfer” button on the phone is
pressed when the phone is running the GMI application.
Parameter and Return
Value:
Parameter:
None
Return Value:
None
Additional Description: None
4.18 GMIEngine. transfer2num()
Function: GMIEngine. transfer2num (destnum)
Purpose: Transfer the cal
l to the destination number (when transfer mode is
activated)
Note：Transfer current line to destnum. Need to call transfer()
function to active transfer mode first
. If the user wishes to implement
a one-button transfer, they can implement a textbox to enter the
number and call the two functions GMIEngine.transfer () and
GMIEngine. transfer2num (destnum) consecutively when the user
presses the button to submit.
Parameter and Return
Value:
Parameter:
destnum –The number to transfer to
Return Value:
None
Additional Description: None

Grandstream Networks, Inc. GMI HTML SDK and API Guide Page 16 of 43
www.grandstream.com Last Updated: 09/2010
4.19 GMIEngine. change_ime ()
Function: GMIEngine. change_ime(id, cb_input_changed)
Purpose: Change the current input method.
Parameter and Return
Value:Parameter:
id—id value for the display text type,
used to display the current
input method.
cb_input_changed— Callback function for the chan
ge input
method function. The function prototype is
function
cb_input_changed(result), the parameter “result”
is the response to
the change input method request.
result is a text string in json format. For example,{"Response":"
Success", ","InputMethod": "abc" };
“Response” returns the result. There are two possibilities-
“Success” or “ERROR”, “InputMethod”
returns the current input
method.
Return Value:
None
Additional Description: None
5GMI Applet Application
The GMI Applet is closely related to the GMI application, but there are some small differences.
The similarities between GMI Appler and GMI include:
Both will model the application interface based on the obtained html page.
Both supports cross-domain interaction (between the user-defined webserver and
the built-in GMI server on the phone) and supports the same GMI API functions.
The differences are:
GMI Applet is a desktop plugin application while GMI application will need to
launch a separate application.
Since GMI Appletis a desktop plugin application and the softkeys/navigation
buttons are being used by the desktop application; therefore, the Backspace and the
Shift keys are used to replace the F3 and F4 keys. When writing the GMI Applet
Application source code, the Backspace key event should be mapped to the F4 key
event and the Shift key event should be mapped to the F3 event.

Grandstream Networks, Inc. GMI HTML SDK and API Guide Page 17 of 43
www.grandstream.com Last Updated: 09/2010
Also，no modification in the menu.xml file is necessary for the GMI Applet. By default, the user
can locate the GMI applet under the phone menu->Personalize->Screen Layout and configure the
URL for the phone to obtain the page.
For more details and examples, please refer to the two source files in the applet folder (ajax.html
and timer.html)
File：applet/ajax.html
function softkey_process(keyCode)
{
document.title = "Applet-Ajax: in softkey_process, keyCode = " + keyCode;
switch (keyCode)
{
case 8:
//Process F3 event in Backspace keyevent
//Backspace
GMIEngine.refresh();
break;
case 16:
//Process F4 event in Shift keyevent
//Shift
var orig = document.location;
var dst = orig.href.replace(/ajax/i, "timer");
GMIEngine.gotourl(dst);
break;
case 112:
//F1 process here;
break;
case 13:
//Enter process here
break;
case 113:
//F2 process here;
break;
case 114:
//F3 process here;
break;
case 115:

Grandstream Networks, Inc. GMI HTML SDK and API Guide Page 18 of 43
www.grandstream.com Last Updated: 09/2010
//F4 process here
break;
case 37:
//Left process here
break;
case 38:
//Up process here
case 40:
//Down process here
break;
case 39:
//Right process here
break;
default:
break;
}
}
6 GMI Demo Program
6.1 Menu Example
Figure 2: Menu Example illustration

Grandstream Networks, Inc. GMI HTML SDK and API Guide Page 19 of 43
www.grandstream.com Last Updated: 09/2010
Refer to the code and the comments below for the implementation of the Menu Example:
File：index.html
/******************************************************************************
* After the page loads, the first item will be highlighted. At the same time, all the
keypad events are handled by softkey_process(keyCode).
。softkey_process has mapped F1/Enter button to “Select” to load the url of the
selected item. F2 is mapped to the API function call GMIEngine.refresh() to refresh
the current page, F4 is mapped to the API function call GMIEngine.exit() to exit the
application.
* The GMI App will process the up/down button keystroke and locate the item
selected.（Here, up/down/left/right button is not mapped to tab, the items are located
through an array ）
******************************************************************************/
<body onload="init();" onkeydown="softkey_process(event.keyCode);" id="body">
<table id="main">
<tr width="100%">
<td width="20%">
/******************************************************************************
* Defines a menu item and change the button background when
mouseover/hover/focus.
******************************************************************************/
<button class="menu" id="b_call_0" onmouseover="chang_to_gif(document.
getElementById('i_call_1'));" onfocus="chang_to_gif(document.getElementById('i_
call_1'));" onmouseout="chang_to_png(document.getElementById('i_call_1'))"onb
lur="chang_to_png(document.getElementById('i_call_1'));">
<table class="item_tab">
<tr class="item_tr">
<td align="center"><img id="i_call_1" src="img/call.png"/></td>
</tr>
<tr><td align="center"><font class="item_label">Call</font></td></tr>
</table>
</button>
</td>
<td width="20%">
<button class="menu" id="b_call_1" onmouseover="chang_to_gif(document.
getElementById('i_ticket_1'));" onfocus="chang_to_gif(document.getElementById('
i_ticket_1'));" onmouseout="chang_to_png(document.getElementById('i_ticket_1'))

Grandstream Networks, Inc. GMI HTML SDK and API Guide Page 20 of 43
www.grandstream.com Last Updated: 09/2010
"onblur="chang_to_png(document.getElementById('i_ticket_1'))">
<table class="item_tab">
<tr class="item_tr">
<td align="center"><img id="i_ticket_1" src="img/vote.png"/></td>
</tr>
<tr><td align="center"><font class="item_label">Vote</font></td></tr>
</table>
</button>
</td>
<td width="20%">
<button class="menu" id="b_call_2" onmouseover="chang_to_gif(document.
getElementById('i_ticket_2'));" onfocus="chang_to_gif(document.getElementById('
i_ticket_2'));" onmouseout="chang_to_png(document.getElementById('i_ticket_2'))
"onblur="chang_to_png(document.getElementById('i_ticket_2'))">
<table class="item_tab">
<tr class="item_tr">
<td align="center"><img id="i_ticket_2" src="img/messages.png"/></td
>
</tr>
<tr><td align="center"><font class="item_label">Message</font></td></tr
>
</table>
</button>
</td>
…… //Omit the code for the other menu items
</tr>
</table>
/******************************************************************************
* Draw/Simulate the softkey using HTML. Softkey should also support mouse click
events, therefore the API functions GMIEngine.refresh();GMIEngine.exit() are also
mapped in onclick.
******************************************************************************/
<table id="softkey">
<tr width="100%">
<td width="40px">
</td>