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)