Yealink DECT Phones
XML Browser Developer's Guide V1.3
About This Guide........................................................................................ |
3 |
Who should use this guide?............................................................................................................... |
3 |
XML and Yealink DECT Phones................................................................. |
3 |
What is XML?...................................................................................................................................... |
4 |
XML Format......................................................................................................................................... |
4 |
Functionality......................................................................................................................................... |
5 |
How does it work?.............................................................................................................................. |
6 |
Phone-initiated Application....................................................................................................... |
6 |
Yealink DECT Phone XML Objects............................................................ |
6 |
XML Object Definitions........................................................................................................................ |
7 |
TextMenu Object....................................................................................................................... |
7 |
TextScreen Object................................................................................................................... |
11 |
InputScreen Object................................................................................................................. |
13 |
Customizable Soft Keys.................................................................................................................... |
20 |
Some Development Guidelines......................................................................................................... |
22 |
Configuring the HTTP Server................................................................... |
23 |
Configuring an XML Browser Key........................................................... |
24 |
Troubleshooting......................................................................................... |
26 |
Troubleshooting Tools........................................................................................................................ |
26 |
Parsing Error Debug Example.......................................................................................................... |
26 |
| About This Guide | 3
XML browser is a simple browser based on XML language and http / https service. You can dynamically generate XML files that meet your requirements for the phone functions on the server side according to the established syntax,and then download them to the DECT phones.
This guide shows you how to use XML API to control the LCD screen display of DECT phones as well as its configuration.
This guide applies to the following Yealink devices:
Product |
Device |
Firmware Version |
|
|
|
|
|
|
W80DM/W80B |
103.83.0.70 or later |
|
|
|
|
|
W80 DECT IP Multi-Cell System |
W56H |
61.83.0.90 or later |
|
|
|
||
W53H |
88.83.0.90 or later |
||
|
|||
|
|
|
|
|
W59R |
115.83.0.10 or later |
|
|
|
|
• Who should use this guide?
This guide is designed specifically to provide development engineers,system administrators,or network engineers with information for developing and deploying customized client services on DECT phones using the XML browser feature.
This guide is not intended for end users and does not provide user-level information on how to use any specific XML applications.
Before reading this guide,you should be familiar with the following:
•Basic text editors,or full IDE-like Eclipse or Microsoft Visual Studio for creating or writing code.
•General application and software development.
•Adequate planning,creating,and testing resources needed to produce a fully deployable web-based application.
•DECT IP multi-cell system and provisioning methods.
•How to use an XML editor.
•The XML-based schema and syntax.
•What is XML?
•XML Format
•Functionality
•How does it work?
| XML and Yealink DECT Phones | 4
XML stands for Extensible Markup Language. It is a markup language much like HTML. HTML is designed to display data and to focus on how data looks,while XML is designed to describe data and focus on what data is.
XML enables DECT phones to serve as output devices for many exciting applications. The XML infrastructure allows the phones to interact with external applications in a flexible and programmable manner.
The following are characteristics of XML:
•XML tags are not predefined. You must define your own tags.
•XML uses an XML schema to describe the data.
•XML with an XML schema is designed to be self-descriptive.
•XML is a W3C Standard Recommendation.
Sample of Basic XML document:
XML is written in the form of XML elements consisting of tags enclosed in angle brackets (for example,<YealinkDECTTextMenu>). XML contains 3 kinds of tags: the start tag,the end tag and the empty-element tag. The empty-element tag has two kinds of form: in pairs (for example,<MenuItem> </MenuItem>) and not in pairs (for example,<MenuItem/>). With the
| XML and Yealink DECT Phones | 5
exception of the empty-element tag not in pairs,XML tags most commonly come in pairs like <YealinkDECTTextMenu> and </YealinkDECTTextMenu>. The first tag in a pair is the start tag (for example,<YealinkDECTTextMenu>),and the second tag is the end tag (for example,</YealinkDECTTextMenu>).
XML mainly follows rules as below:
•XML must have root element.
•The end tag must have the character “/”.
•XML tags are case-sensitive.
•Each attribute value should be within double quotations.
•The texts within <!-- --> are considered as comments.
XML provides escape facilities for including characters which are problematic to include directly. For example,the characters "<" and "&" are key syntax markers and may never appear in the content. XML has five predefined entities.
The XML conversion table is shown as below:
Character |
Name |
Escape Sequence |
|
|
|
& |
Ampersand |
& |
|
|
|
“ |
Quote |
" |
|
|
|
‘ |
Apostrophe |
' |
|
|
|
< |
Left angle bracket |
< |
|
|
|
> |
Right angle bracket |
> |
|
|
|
To respect XML recommendations,the following header can be set at the beginning of the XML document,
<?xml version="1.0" encoding="ISO-8859-1"?>
Or
<?xml version="1.0" encoding="UTF-8"?>
Yealink provides XML object files beginning with the XML declaration “<?xml version="1.0" encoding="ISO-8859-1"?>”.
For more information on XML,refer to http://www.xml.com/.
The XML browser allows users to develop and deploy custom services which to meet the user requirements of phone functions on the server.
Phone service developers should take it into consideration that the phone is not a web browser so it cannot parse HTML. Although the content is delivered to the phone through HTTP messages using a web server,keep in mind that the content is not HTML. All content comes to the phone either as plain text or text packaged in XML objects.
DECT phones support 3 proprietary XML objects,which allow the creation of powerful XML applications.
The supported objects are:
•TextMenu object
•TextScreen object
•InputScreen object
| Yealink DECT Phone XML Objects | 6
Depending on the IP infrastructure,Yealink is capable of developing the XML browser of the phones using HTTP. DECT phones support phone-initiated mode for XML browser applications.
•Phone-initiated Application
You can press the predefined XML Browser key to trigger the phone-initiated application of XML browser. After you press the key,the DECT phone issues an HTTP(s) GET request message to the server,waits for the answer,decodes and displays this response message like any web browser,such as Microsoft Internet Explorer or Firefox,and would do as a web client.
Figure1 DECT phone acting as a client
Creating interactive service applications is relatively easy when you understand the XML objects that are defined for DECT phones and the behavior that each XML object generates.
Regardless of what causes the phone to load an XML page,the phone always behaves appropriately after it loads a page. Appropriate behavior depends only on the type of data delivered on the page.
•XML Object Definitions
•Customizable Soft Keys
•Some Development Guidelines
| Yealink DECT Phone XML Objects | 7
This section details each proprietary XML object supported by DECT phones.
You can ask the distributor or Yealink FAE for XML object files or obtain XML object files online: http:// support.yealink.com/documentFront/forwardToDocumentFrontDisplayPage.
Note: XML objects do not support Chinese characters.
•TextMenu Object
•TextScreen Object
•InputScreen Object
The TextMenu object allows users to create a list of menu items on the DECT phones. You can browse the menu items by linking HTTP requests.
XML description of the TextMenu object:
<?xml version="1.0" encoding="ISO-8859-1"?> <**TextMenu
defaultIndex = "integer" style = "numbered/none" Beep = "yes/no" Timeout = "integer"
refresh=“refresh time“ url=“URI“ cancelAction = "URI"
>
<Title >Menu Title</Title> <MenuItem> <Prompt>Prompt</Prompt> <URI>URI</URI> <Dial>Number to dial</Dial >
<Selection>Selection</Selection>
</MenuItem>
<!--Additional menu items may be added (up to 30) --> <!--Additional Softkey items may be added (up to 6) --> </**TextMenu>
The parameters of the TextMenu object are listed in the following table:
Parameter |
Position |
Type |
Value |
Description |
|
|
|
|
|
**TextMenu |
Root tag |
mandatory |
none |
The root element of the TextMenu object. |
|
|
|
|
Note: "**" in the "**TextMenu" can be any |
|
|
|
|
string or an empty string. |
|
|
|
|
|
| Yealink DECT Phone XML Objects | 8
Parameter |
Position |
Type |
Value |
Description |
|
|
|
|
|
defaultIndex |
Root tag |
optional |
Integer |
Position of the cursor. |
|
|
|
|
|
|
|
|
|
If the value is not specified or exceeds the |
|
|
|
|
number of menu items, the cursor will be |
|
|
|
|
positioned on the first menu item. |
|
|
|
|
The default value is 1. |
|
|
|
|
|
style |
Root tag |
optional |
“numbered” |
numbered (default): Add a digit before |
|
|
|
“none” |
each menu item for index. |
|
|
|
|
|
|
|
|
|
none: No sign before each menu item. |
|
|
|
|
|
Beep |
Root tag |
optional |
“yes” |
Whether to play a tone when the XML |
|
|
|
||
|
|
|
“no” |
object is opened. |
|
|
|
|
|
|
|
|
|
The default value is “yes”. |
|
|
|
|
|
Timeout |
Root tag |
optional |
integer |
If there is no operation at a fixed interval |
|
|
|
|
|
|
|
|
|
(in seconds) on the phone,the phone |
|
|
|
|
will automatically exit from the TextMenu |
|
|
|
|
screen. |
|
|
|
|
If it is set to 0,the phone will not |
|
|
|
|
automatically exit from the TextMenu |
|
|
|
|
screen until pressing the “Back” soft key/ |
|
|
|
|
On-hook key,or long pressing the On-hook |
|
|
|
|
key. |
|
|
|
|
The default value is 45. |
|
|
|
|
|
refresh |
Root tag |
optional |
integer |
Define the time interval (in seconds) to |
|
|
|
|
automatically refresh the text menu by |
|
|
|
|
calling the URI defined by “url”. |
|
|
|
|
If it is set to 0,the phone will not |
|
|
|
|
automatically refresh the text menu. |
|
|
|
|
|
url |
Root tag |
optional |
URI |
Define the URI to be called to refresh the |
|
|
|
|
text menu. |
|
|
|
|
|
cancelAction |
Root tag |
optional |
URI |
Define the URI to be called when the user |
|
|
|
|
cancels the XML object by pressing the On- |
|
|
|
|
hook key. |
|
|
|
|
|
Title |
Body |
mandatory |
string |
The title of the text menu. |
|
|
|
|
|
MenuItem |
Body |
mandatory |
none |
The element of the menu item. |
|
|
|
|
|
|
|
|
|
(Up to 30 instances,the minimum is 1) |
|
|
|
|
|
Prompt |
MenuItem |
mandatory |
string |
The label of the menu item. |
|
body |
|
|
Note: Only one line can be displayed. |
|
|
|
|
|
|
|
|
|
|
URI |
MenuItem |
mandatory |
URI |
URI is used if the user presses the “Select” |
|
body |
|
|
|
|
|
|
soft key,“OK” key, or Right navigation key (if |
|
|
|
|
|
|
|
|
|
|
it is not customized) with the cursor on this |
|
|
|
|
menu item. |
|
|
|
|
|
| Yealink DECT Phone XML Objects | 9
Parameter |
Position |
Type |
Value |
Description |
|
|
|
|
|
Dial |
MenuItem |
optional |
Phone |
Define what number will be dialed when the |
|
body |
|
number |
|
|
|
user presses the Speakerphone key or the |
||
|
|
|
|
|
|
|
|
|
Off-hook key. |
|
|
|
|
|
Selection |
MenuItem |
optional |
string |
If “URI” is set to an HTTP URL,the “? |
|
body |
|
|
|
|
|
|
selection= xxx (defined by the Selection |
|
|
|
|
|
|
|
|
|
|
parameter)" will be appended to the URI |
|
|
|
|
when the user presses the “Select” soft key |
|
|
|
|
or the “OK” key. |
|
|
|
|
Example: |
|
|
|
|
http://10.1.0.105/menu1.xml? |
|
|
|
|
selection=0&menu_pos=1 |
|
|
|
|
|
SoftKey |
Body |
optional |
string |
Refer to Customizable Soft Keys for more |
|
|
|
|
information. |
|
|
|
|
|
If there is no soft key defined in the TextMenu object,the LCD screen displays the following default soft keys:
SoftKey Index |
Label |
URI |
|
|
|
1 |
Back |
SoftKey:Back |
|
|
|
2 |
Select |
SoftKey:Select |
|
|
|
The function keys and soft keys are listed in the following table: |
|
|
|
|
|
Key Name |
Operation |
Function |
|
|
|
Up/Down Key |
Pressing the up/down key |
Browse the menu item up and |
|
|
|
|
|
down. |
|
|
|
Select |
Pressing the "Select” soft key |
Execute the content of the URI |
|
|
field assigned to the selected |
|
|
menu item. |
|
|
|
Back/Exit |
Pressing the “Back”/"Exit" soft key |
Return to the idle screen. |
|
|
|
Off-hook Key/ Speakerphone Key |
Pressing the Speakerphone Key/ |
If there is a number contained in |
|
Off-hook key |
the "Dial" tag,the phone will dial |
|
|
out the number. |
|
|
If there is no number contained in |
|
|
the "Dial" tag,the phone will not |
|
|
response to any operation. |
|
|
|