Grandstream GXP2200GMI User Manual

Grandstream Networks, Inc.

GXP2200 GMI Web Service Guide V1.0

Grandstream Networks, Inc.

www.grandstream.com

Index

OVERVIEW ................................................................................................ 3

GMI WEB SERVICE INTERFACE .............................................................. 4

1. webServiceLogin(ip, username, password, callbackFunction) ......................................................... 4

2. getUptime(callbackFunction) ............................................................................................................. 5

3. getPN(callbackFunction) ................................................................................................................... 5

4. getHardware(callbackFunction) ......................................................................................................... 6

5. getVendor(callbackFunction) ............................................................................................................. 7

6. getProduct(callbackFunction) ............................................................................................................ 7

7. getProductInfo(callbackFunction) ...................................................................................................... 8

8. originateCall(account, isvideo isdialplan, destnum, headerstring, callbackFunction) ....................... 8

9. getNetworkInfo(callbackFunction) ..................................................................................................... 9

10. getAccountInfo(callbackFunction) ................................................................................................. 10

11. getGroup(gpID, callbackFunction) ................................................................................................. 10

12. getContact(ctID, gpID, ctName, callbackFunction) ....................................................................... 11

13. getGroupCount(callbackFunction) ................................................................................................. 12

14. getContactCount(callbackFunction) .............................................................................................. 13

15. setGroup(phbkGroup, callbackFunction)....................................................................................... 13

16. setContact(phbkContact, callbackFunction) .................................................................................. 14

17. removeContact(ctID, callbackFunction) ........................................................................................ 16

18. clearGroup(gpID, callbackFunction) .............................................................................................. 16

19. removeGroup(gpID, callbackFunction) .......................................................................................... 17

20. moveToDefault(ctID, callbackFunction) ......................................................................................... 18

21. downloadPhonebook(phbkConfigure, flag, callbackFunction) ...................................................... 19

22. setPhonebook(phbkConfigure, flag, callbackFunction) ................................................................. 21

23. getMessage(id, callFunction) ........................................................................................................ 23

24. setNewMessage(num, account, text, flag, callbackFunction) ....................................................... 24

25. sendDraftMessage(id, callbackFunction) ...................................................................................... 24

26. removeMessage(id, flag, callbackFunction) .................................................................................. 25

27. saveMessage(callbackFunction) ................................................................................................... 26

28. getLastCall(type, callbackFunction) .............................................................................................. 26

29. removeCall(id, flag, callbackFunction) .......................................................................................... 27

30. saveCallHistory(callbackFunction) ................................................................................................ 28

31. setUpgrade(upgradeConf, reboot, callbackFunction) ................................................................... 28

32. setParameter(confItem[ ], callbackFunction) ................................................................................. 31

33. getParameter(confItem[ ], callbackFunction)................................................................................. 32

GXP2200 GMI WEB SERVICE GUIDE V1.0 Page 1 of 38

34. launchService(name, arg, callbackFunction) ................................................................................ 33

35. getGMIVersion ............................................................................................................................... 33

36. getPhoneStatus ............................................................................................................................. 34

37. getPhoneMem ............................................................................................................................... 35

38. getLineStatus ................................................................................................................................. 35

GMISer vice EX AMP L E ............................................................................ 37

USING JAVASCRIPT........................................................................................................................... 37

USING MFC ........................................................................................................................................ 38

GXP2200 GMI WEB SERVICE GUIDE V1.0 Page 2 of 38

OVERVIEW

GMI (Grandstream Manager Interface) is a m anagement API developed by Grandstream Networks, Inc. Designed for our IP Multimedia phones, it allows partners to develop customized applications on the phone. GMI supports standard HTML/CSS/Javascript, users can use these dynamic web page development languages f or the cus tomized application s and GMI w ill display the application on t he p hon e based on the web pages generated.

The number of GMI web service interfaces is growing with increasing customer demands. Some interfaces in this guide are newly introduced after certain GMI version. To avoid compatibilit y issue, we added getGMIVersion interface [35. getG MIVersion] for user s to retrieve current GMI i nterface version. For interfaces that require s pec if ic G MI vers i on, p lease use getGMIVersion to mat ch the r etur n ed ver s ion number. For interfaces that do no t h ave GMI version requ ir ement, they exist in a ll G MI vers i ons and there is no need to identify GMI version.

Note: Before starting the GMI Web Ser vice developm ent, pleas e upgrade your GXP2200 to th e latest firm ware version. The firmware release information can be found in the following link:

http://www.grandstream.com/support/firmware

GXP2200 GMI WEB SERVICE GUIDE V1.0 Page 3 of 38

GMI WEB SERVICE INTERFACE

GXP2200 GMI W eb Service provides basic API to facilitate users calling the existing app lication on the GXP2200 or to retrieve the phone's status. Usually JavaScript and Windows MFC can be used for development. However, no matter what programming language is used, the functions in the interface have the same nam e and parameters, which ar e included in GMIService class. Users cou ld define the interface according to the parameters and HTTP request. This section describes details for each interface.

Note:

• Parameter account in each interface represents the account index. This is the index number retrieved from getAccountInfo [10. getAccountInfo(callbackFunction)] interface. The valid index number is from 0 to 5 for account 1 to account 6.

• For the HTTP requests in each interfac e introduc ed be low, if the action data is empt y or incorr ect, th e following message will be returned: "{"res": "error", "msg": "command not found"}"

• For the interfaces introduc ed belo w, if the HTTP requests' interval is m ore tha n 900s, t he request will be disconnected. The following message will be returned and users will need login again. "{"res": "error", "msg": "authentication required"}"

1. webServiceLogin(ip, username, password, callbackFunction)

Description

Parameters

HTTP Request

to be executed first bef ore using other interfac es (except getVendor, getProduct and getProductInfo interfaces)

• ip: Phone's IP address

• username: Web GUI login username

• password: Web GUI login password

• callbackFunction: Call back function

• url: "http://"+ ip + "/manager?"

• action: "login"

• username: "admin"

• secret: "123"

• format: "json"

GXP2200 GMI WEB SERVICE GUIDE V1.0 Page 4 of 38

• jsoncallback: "?" (This is the HTTP request for the call back function, usually used in AJAX and JQuery)

• For example: http://192.168.121.230/manager?action=login&username=admin&secret=123&form at=json&jsoncallback=?

1. HTTP request return:

• Login successful

Return

"{"res": "success", "msg" : "authentication accepted"}"

• Login failed if username or password is missing or incorrect "{"res": "error", "msg" : "authentication failed"}"

2. callbackFunction(data) will process the data returned from HTTP request

2. getUptime(callbackFunction)

Description

Parameters

HTTP Request

Return

Retrieve current system up time

callbackFunction: Call back function

• url: "http://"+ ip + "/manager?"

• action: "uptime"

• format: "json"

• jsoncallback: "?" (This is the HTTP request for the call back function, usually used in

AJAX and JQuery)

• For example: http://192.168.121.230/manager?action=uptime&format=json&jsoncallback=?

1. HTTP request return:

• Return successful "{"res": "success", "day": "1", "hour" : "12", "min" : "23", "sec" : "45"}"

• Return failed "{"res": "error", "msg": "can't get uptime"}"

2. callbackFunction(data) will process the data returned from HTTP request

3. getPN(callbackFunction)

Description

Parameters

Retrieve GXP2200 P/N number

callbackFunction: Call back function

GXP2200 GMI WEB SERVICE GUIDE V1.0 Page 5 of 38

• url: "http://"+ ip + "/manager?"

• action: "pn"

• format: "json"

HTTP Request

Return

• jsoncallback: "?" (This is the HTTP request for the call back function, usually used in AJAX and JQuery)

• For example: http://192.168.121.230/manager?action=pn&format=json&jsoncallback=?

1. HTTP request return:

• Return successful "{"res": "success", "pn": "9620001902A"}"

• Return failed "{"res": "error", "msg" : "can't get pn version"}"

2. callbackFunction(data) will process the data returned from HTTP request

4. getHardware(callbackFunction)

Description

Parameters

HTTP Request

Return

Retrieve GXP2200 Hardware version

callbackFunction: Call back function

• url: "http://"+ ip + "/manager?"

• action: "hardware"

• format: "json"

• jsoncallback: "?" (This is the HTTP request for the call back function, usually used

in AJAX and JQuery)

• For example: http://192.168.121.230/manager?action=hardware&format=json&jsoncallback=?

1. HTTP request return:

• Return successful "{"res": "suc c es s ", "hardware": "V 2 .0A"}"

• Return failed "{"res": "error", "msg" : "can't get hardware version"}"

2. callbackFunction(data) will process the data returned from HTTP request

GXP2200 GMI WEB SERVICE GUIDE V1.0 Page 6 of 38

5. getVendor(callbackFunction)

Description

Parameters

HTTP Request

Return

Retrieve GXP2200 vendor information (login is not required)

callbackFunction: Call back function

• url: "http://"+ ip + "/manager?"

• action: "vendor"

• format: "json"

• jsoncallback: "?" (This is the HTTP request for the call back function, usually used in

AJAX and JQuery)

• For example: http://192.168.121.230/manager?action=vendor&format=json&jsoncallback=?

1. HTTP request return:

• Return successful "{"res": "success", "vendor": "Grandstream Networks, Inc."}"

• Return failed "{"res": "error", "msg" : "can't get vendor"}"

2. callbackFunction(data) will process the data returned from HTTP request

6. getProduct(callbackFunction)

Description

Parameters

HTTP Request

Return

Retrieve GXP2200 product information (login is not required) callbackFunction: Call back function

• url: "http://"+ ip + "/manager?"

• action: "vendor"

• format: "json"

• jsoncallback: "?" (This is the HTTP request for the call back function, usually used in

AJAX and JQuery)

• For example: http://192.168.121.230/manager?action=product&format=json&jsoncallback=?

1. HTTP request return:

• Return successful "{"res": "success", "product": "GXP2200"}"

• Return failed "{"res": "error", "msg" : "can't get product model"}"

2. callbackFunction(data) will process the data returned from HTTP request

GXP2200 GMI WEB SERVICE GUIDE V1.0 Page 7 of 38

7. get ProductInfo(callbackFunction)

(int type, the index value can be retrieved from

Description

Parameters

HTTP Request

Return

Retrieve GXP2200 vendor and produc t inf ormation (login is not required) callbackFunction: Call back function

• url: "http://"+ ip + "/manager?"

• action: "productinfo"

• format: "json"

• jsoncallback: "?" (This is the HTTP request for the call back function, usually used in

AJAX and JQuery)

• For example: http://192.168.121.230/manager?action=productinfo&format=json&jsoncallback=?

1. HTTP request return:

• Return successful "{"res": "success", "product": "GXP2200","vendor": "Grandstream Networks, Inc."}"

• Return failed "{"res": "error", "msg" : "can't get product inf ormation"}"

2. callbackFunction(data) will process the data returned from HTTP request

8. originateCall(account, isvideo isdialplan, destnum, headerstring, callbackFunction)

Description

Parameters

HTTP Request

Make calls

• account: account index

getAccountInfo interface)

• isvideo: audio call or video call. 0 - audio; 1 - video

• isdialplan: 0 or 1

• destnum: the number to be dialed

• headerstring: SIP request header

• callbackFunction: Call back function

• url: "http://"+ ip + "/manager?"

• action: "originatecall"

• destnum: "8108819"

• account: 0

• isvideo: 0

• isdialplan: 0

• headerstring: ""

• format: "json"

GXP2200 GMI WEB SERVICE GUIDE V1.0 Page 8 of 38

• jsoncallback: "?" (This is the HTTP request for the call back function, usually used in AJAX and JQuery)

• For example: http://192.168.121.230/manager?action=originatecall&destnum=8108819&account= 0&isvideo=0&isdialplan=0&headerstring=&format=json&jsoncallback=?

HTTP request return:

• Call originated "{"res": "success", "msg": "call originated"}"

Return

• Destination number is empty "{"res": "error", "msg" : "destnum can't be null"}"

• Timeout "{"res": "error", "msg" : "timeout"}"

• callbackFunction(data) will process the data returned from HTTP request

9. getNetworkInfo(callbackFunction)

Description

Parameters

HTTP Request

Return

Retrieve GXP2200 network status

callbackFunction: Call back function

• url: "http://"+ ip + "/manager?"

• action: "network"

• format: "json"

• jsoncallback: "?" (This is the HTTP request for the call back function, usually used in

AJAX and JQuery)

• For example: http://192.168.121.230/manager?action=network&format=json&jsoncallback=?

1. HTTP request return:

"{"res" : "success", "mac" : "00-0b-82-29-5c-a7", "ip" : "192.168.121.230", "mask" : "255.255.255.0", "gateway" : "192.168.121.1", "dns" : "192.168.121.253", "type" : "dhcp"}"

2. callbackFunction(data) will process the data returned from HTTP request

GXP2200 GMI WEB SERVICE GUIDE V1.0 Page 9 of 38

10. getAccountInfo(callbackFunction)

Retrieve phonebook group information for group gpID. If gpID is empty, return

Description

Parameters callbackFunction: Call back function

HTTP Request

Return

Retrieve GXP2200 account information

• url: "http://"+ ip + "/manager?"

• action: "accountStatus"

• format: "json"

• jsoncallback: "?" (This is the HTTP request for the call back function, usually used in

AJAX and JQuery)

• For example: http://192.168.121.230/manager?action=status&format=json&jsoncallback=?

1. HTTP request return:

{"Response":"Success","Data":[{"Index":"1","Server":"192.168.120.254","Number":"3882 ","Status":"1","Activate":"1"}, {"Index":"0","Server":"sip.ipvideotalk.com:48879","Number":"8118263","Status":"1","Activ ate":"1"}, {"Index":"2","Server":"192.168.121.22","Number":"1001","Status":"1","Activate":"1"}]}

2. String definition:

• Index: The account index. From 0 to 5 for account 1 to account 6. This is the account index used in originateCall function.

• Server: The SIP server address for the account.

• Number: The account number.

• Status: account status. 0 - unregistered; 1 and 2 - registered; 3 and 5 - dialing; 4 -

ringing; 6 - talking

• Activate: account activated/deactivated. 1 - activated; 0 - deactivated

11. getGroup(gpID, callbackFunction)

Description

Parameters

information for all groups

• gpID: phonebook group ID

• callbackFunction: Call back function

GXP2200 GMI WEB SERVICE GUIDE V1.0 Page 10 of 38

HTTP Request

Return

• url: "http://"+ ip + "/manager?"

• action: "getgroup"

• groupID: ""

• format: "json"

• jsoncallback: "?" (This is the HTTP request for the call back function, usually used in

AJAX and JQuery)

• For example: http://192.168.121.230/manager?action=getgroup&groupID=&format=json&jsoncall back=?

1. HTTP request return:

• Return successful "{"res": "success", "msg": [{"groupID":"0","groupName":"default"}, {"groupID":"100","groupName":"blacklist"}]}"

• No groups "{"res": "error", "msg" : "0"}"

• Return failed "{"res": "error", "msg" : "can't get groups information"}"

• Parameters in wrong format (GMI version 9 or newer)

"{"res": "error", "msg" : "wrong format"}"

2. callbackFunction(data) will process the data returned from HTTP request

12. getContact(ctID, gpID, ctName, callbackFunction)

1. Retrieve contact information

• If ctID is specified but ctName is empty, return the contact ctID

• If ctName is specified, return the contacts which has string ctName in its name field

• If ctID and ctName are em pty but gpID is specif ied, return a ll the contacts in group

Description

Parameters

gpID

• If ctID, ctName and gpID are empty, return all contacts

2. Before using getContact interface, users could get the number of contacts by

getContactCount interface first. If the number of contacts is more than 20, it is recommended to use setPhonebook interface instead of getContact interface

callbackFunction: Call back function

GXP2200 GMI WEB SERVICE GUIDE V1.0 Page 11 of 38

+ 27 hidden pages