Cisco Systems OL-20949-01 User Manual

Cisco Unified IP Phone Services Application Development Notes

Supporting XML Applications

Release 7.1(3)

Americas Headquarters

Cisco Systems, Inc. 170 West Tasman Drive San Jose, CA 95134-1706 USA http://www.cisco.com Tel: 408 526-4000

800 553-NETS (6387)

Fax: 408 527-0883

Text Part Number: OL-20949-01

THE SPECIFICATIONS AND INFORMATION REGARDING THE PRODUCTS IN THIS MANUAL ARE SUBJECT TO CHANGE WITHOUT NOTICE. ALL STATEMENTS, INFORMATION, AND RECOMMENDATIONS IN THIS MANUAL ARE BELIEVED TO BE ACCURATE BUT ARE PRESENTED WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. USERS MUST TAKE FULL RESPON SIBILITY FOR THEIR APPLICA TION OF ANY PRODUCT S.

THE SOFTWARE LICENSE AND LIMITED WARRANTY FOR THE ACCOMPANYING PRODUCT ARE SET FORTH IN THE INFORM ATION PACKET THAT S

HIPPED WITH THE PRODUCT AND ARE INCORPORATED HEREIN BY THIS REFERENCE. IF YOU ARE UNABLE TO LOCAT E THE SOFTWARE LICENSE

OR LIMITED WARRANTY, CONTACT YOUR CISCO REPRESENTATIVE FOR A COPY. The Cisco implementation of TCP head er compressi on is an adap tation of a program developed by the Universi ty of Ca lifornia, Berk

domain version of the UNIX operatin g system. All rights reserved . Copyri ght © 1981 , Rege nts of the Uni versity of Califor nia. NOTWITHSTANDING ANY OTHER WARRANTY HEREIN, ALL DOCUMENT FILES AN D SOFTWARE OF THESE SUPP LIERS ARE PROVIDED “AS IS” WITH

L FAULTS. CISCO AND THE ABOVE-NAMED SUPPLIERS DISCLAIM ALL WARRANTIES, EX PRESSED OR IMPLIED, INCLUDING, WITHOUT

IMITATION, THOSE OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONIN FRINGEMENT OR ARIS ING FROM A COURSE OF

DEALING, USAGE, OR TRADE PRACTICE. IN NO EVENT SHALL CISCO OR ITS SUP PLIERS BE LIABLE FOR ANY INDIRECT, SPECIAL, CONSEQUENTIAL, OR INCIDENTAL DAMAGE S, INCL UDI NG,

THOUT LIMITATION, LOST PROFITS OR LOSS OR DAMAGE TO DATA ARISING OUT OF THE USE OR INABILITY TO USE THIS MANUAL, EVEN IF CISCO

OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES . CCDE, CCENT, CCSI, Cisco Eos, Cisco HealthPresence, Cisco IronPort, the Cisco logo, Cisco Nurse Connect, Cisco Pulse, Cisco SensorBase, Cisco StackPower,

sco StadiumVision , Cisc o TelePresence, Cisco Unified Computing System, Cisco W ebEx , DCE, Fl ip Chann els , Flip fo r Good , Flip Mino, Flip shar e (Des ign), Flip Ultr a,

lip Video, Flip Video (Design), Instant Broadband, and Welcome to the Human Network are trademarks; Changing the Way We Work, Live, Play, and Learn, Cisco Capital,

sco Capital (Design), Ci s co:Financed (Stylized), Cisco Store, Flip Gift Card, and One Million Acts of Green are service marks; and Access Registrar, Aironet , All Touch,

Asy

ncOS, Bringing the Meeting To You, Catalyst, CCDA, CCDP, CCIE, CCIP, CCNA, CCNP, CCSP, CCVP, Cisco, the Cisco Certified Internetwork Expert logo,

sco IOS, Cisco Lumin, Cisco Nexus, Cisco Press, Cisco Systems, Cisco Systems Capital, the Cisco Systems logo, Cisco Unity, Collabo rat ion Wi thout L imita tion ,

ontinuum, EtherFast, EtherSwi tch, E vent Center, Explorer, Follow Me Br ows in g, GainM aker, iLYNX, IOS, iPhone, Iron Por t, the IronPort logo, Laser L ink, LightStream, Linksys, MeetingPlace, MeetingPlace Chime Sound, MGX, Networkers, Networking Academy, PCNow, PIX, PowerKEY, PowerP anels, Pow erTV, Pow erTV (Design) , PowerVu, Prisma, ProConnect, ROSA, SenderBase, SMARTnet, Spectrum Expert, StackWise, WebEx, and the WebEx logo are registered trademarks of Cisco Systems, Inc. and/or its affiliates in the United States and certain other countri es.

All other trademarks mentioned in this document or website are the property of their respective owners. The use of the word partn between Cisco and any other company. (0910 R)

Any Internet Protocol (IP) addresses used in this document are not intended to be actual addresses. Any examples, command display ou document are shown for illustrative pur poses onl y. Any use of act ual IP addr ess es in ill ustr ativ e conte nt is uninte ntio nal and coincident al.

Cisco Unified IP Phone Ser vices Application Development N o tes

eley (UCB) as part of UCB’s public

er does not imply a partnership relationship

tput, and figures included in the

Preface vii

Overview vii

Revision History vii

Audience vii

Cisco Developer Support Program vii

Organization viii

Overview

Preface

Use this document with Cisco Unified Communications Manager, Release 7.1(3) to develop and deploy customized client services for the Cisco Unified IP Phones that su ppo rt C isco Uni fied Phone se rvice s.

Because of the complexity of a Unified Communications network, this guide does not provide complete

d detailed inform at ion f or pro ce du res t hat y ou need to pe rf orm i n Cisc o Unified Communications

anager or other ne twor k d evices. See the “R ela ted D oc umen tat ion” sec tio n on pa ge ix for a list of

M related documentat ion.

Revision History

Date Updates

September 29, 2009 Initial release. November 23, 20 09 Upd ate d the do cume nt w it h in for mat ion o n the Ci sco U nified I P Pho ne s 99 71,

951, and 8961 m ode ls. See , New Informa tion for Cisco Un ified

Communications Ma nager 7.1 (3), page 1.

December 10, 2009 Corrected the Cisco Unified IP Phone 7925G resolution from 176 x 220 to 176

140. See, Table 3-2 on page 9

Audience

This document p rovides t he i nf orm ati on nee de d for e Xte nsib le Ma rk up Lang uag e (XM L) a nd X /Op en System Interface (XSI) pro gramme rs and system administr ators to develop and deploy new services.

Cisco Developer Support Program

The Cisco Developer Network (CDN) portal provides access to multiple Cisco technology d eveloper interfaces and collaborative support communities. CDN also provides formalized support services for these interfaces to enable developers, customers, and partners to accelerate their development. The

OL-20949-01

Cisco Unified IP Phone Services Application Development Notes

vii

Preface

formalized process provides acce ss to CDN Engin eers who are a n extension of the prod uct techn ology engineering team s. CDN En gine ers have access to t he resou rc es nec essar y to provide expert supp ort in a timely manner.

The Cisco Developer Network Program is designed for businesses (IHV's and ISV's) interested in going

market with Cisco. The CDN Program enables members to develop compelling solutions that unify

to data, voice, video, an d m obile com mun icat ions on Cisc o's powerful com muni cati ons plat form. T he program also all ows membe rs t o ta ke advantage of Cisco' s br an d, m arket leade rs hip p osi tion, a nd installed base to help drive positive business results for themselves and their customers.

For additional information about the CDN Program and CDN support services go to

http://develop er.cisco.com/web/devserv i ces

Note The Cisco TAC does NOT provide support fo r th is AP I/i nte rface un der s ta nd ard h ar dware o r s oftwa re

support agreements. All technical support for this API/interface, from initial development assistance through API troubleshooting/bugs in final production apps, is provided by Cisco Developer Support and requires a separate Developer Support contra ct. Whe n opening case s, a Developer Support contrac t number must be provided to rece ive support.

Organization

This docu me n t c om p ri se s th e fo ll owin g se c ti on s:

Chapter Description

Chapter 1, “Overview” Provi des an ove r v i ew o f t he Ci sc o Unified IP Phone

Chapter 2, “New and Changed Informat ion” Provides details on the new and changed information in

Chapter 3, “CiscoIPPhone XML Objects” Describes the general behavior and usage of each XML

Chapter 4, “Component APIs” Describes additional APIs available to the

Chapter 5, “Inter nal UR I Fe atur es ” Describes how to implement embe dded feat ures on

Chapter 6, “HTTP Requests and Header Settings”

Chapter 7, “Troubleshooting Cisco Unified IP Phon e Serv ice Applications”

Chapter 8, “Cisco IP Phone Services Software Development Kit (SDK)”

ervices for developers.

e XML service interface for the latest release of Cisco

th Unified Communicatio n Ma nage r.

ject.

sco Unified IP Phones.

Ci Provides a p rocedure on handling HTTP client r equests,

efinitions for HTTP header elements, identifies the

d capabilities of the requesting IP phone client, and defines the Accept header.

Provides troubleshooting tips, XML par sing erro rs, and

rror messages.

Provides a list of the components used in the Ci

sco Unified IP Services Software Development Kit

SDK) and the sample services requirements.

(

viii

Cisco Unified IP Phone Services Application Development Notes

OL-20949-01

Preface

Chapter Description

Chapter 9, “IP Phone Service Administration and Subscription”

Chapter 10, “DeviceListX Report” Describes how the report provides a list of the

Appendix A, “Ci scoI PPhon e XML Obje ct Quick Reference”

Appendix B, “Cisco Unified IP Phone Services XML Schema File”

Cisco Product Security Overview

This product co nt ain s c ryp togr ap hic fe atu res a nd is subj ect to Un ite d Sta tes an d loca l c ou ntry laws governing import, export, tran sfer a nd use. De livery of Cisc o crypt o graph ic pro duc ts d oes no t i mp ly third-party author ity to impo rt, export, dis tribute or use encry ption. Importer s, exporters , distributors and users are responsible fo r compl ianc e with U.S. and l ocal co untry laws. By us ing this produ ct you agree to comply with applicab le laws and regulat ions. If you a re unable to comply with U.S. and l ocal laws, return this product immediately.

Further information regarding U.S. export regulations may be found at

http://www.access.gpo.gov/bis/ear/ear_data.html

Document Conventions

This document uses the following conventions:

Convention Indication

bold fo

italic f

[ ] Elements in square brackets are optional. {x | y | z } Required alternative keywords are grouped in braces and separated by

[ x | y | z ] Optional al ternat ive keywords are grouped in brackets an d separ ated by

string A nonquoted set of char acte rs. Do not use qu otat ion mar ks around the string or

courier font Terminal sessions and information the system displays appear in cour ier fo nt .

< > Nonprinting characters such as passwords are in angle brackets. [ ] Default responses to sy stem pr om pts are in sq uare br ackets . !, # An exclamation poi nt (!) o r a pou nd si gn (#) a t t he b eginni ng of a li ne o f cod e

nt Commands and keywords and use r-enter ed text a ppea r in bold fon t.

ont Document titles, new or emphasized terms, and ar guments for which you su pply

values are in italic font.

ertical bars.

e string will include the quotation marks.

dicates a comment line.

Preface

Note Means reader take note.

Tip Means the following information will help you solve a problem.

Caution Means rea de r be care ful. In this situation, you might perform an action that could result in equipment

damage or loss of data.

Cisco Unified IP Phone Services Application Development Notes

OL-20949-01

Preface

Obtaining Documentation and Submitting a Service Request

Timesaver Means the described action saves time. You can save time by performing the action described in

the paragraph.

Warning

Means reader be warned. In this situation, you might perform an action that could result in bodily injury.

OL-20949-01

Cisco Unified IP Phone Services Application Development Notes

Obtaining Documentation and Submitting a Service Request

Preface

xii

Cisco Unified IP Phone Services Application Development Notes

OL-20949-01

CHA PTER

Overview

You can use Cisco Unified IP Phones to deploy customi zed c lient servi ces with w hich u sers can inter act via the keypad and display. Services deploy using the HTTP protocol from stan dard web servers.

Users acces s t h ese fe at ur es usi ng th e s varies by phone model). When a user presses the services button (or chooses the serv ic e s menu item), a menu of configured services displays. The user then chooses a service from the list, and the phone displays the service.

The following list gives ty pical services that might be supplied to a phone:

• Weather

• Stock information

• Contact information

• Company news

• To-do list s

• Daily schedule

ervices and directories buttons or menu options (availability

Figure 1-1 sh

Figure 1-1 Cisc o Unified IP Phone Text Menu Sample

Cisco Unified IP Phones can also display graphic menus, as shown in Figure 1-2.

ows a sample text menu.

OL-20949-01

Cisco Unified IP Phone Services Application Development Notes

1-1

Chapter 1 Overview

Figure 1-2 Graphic Menu on a Cisco Unified IP Phone Sample

Phone users can navigate a text menu by using the Navigation button followed by the Select softkey, or by using the numeric keypad to e nter a se le ction di rec tly. Graphic menus c urren t ly do n ot su ppo rt cursor-based navigation; users simply enter a numb er usi ng the DTMF keypad.

When a menu selection is made, the Cisco Unified IP Phone acts on it by using its HTTP client to load

specific URL. The return type from this URL can be plain text or one of the CiscoIPPhone XML

a objects. The object loads and the user interacts with the object.

Figure 1-3 a

stock quote that was gene rated usi ng pl ai n text, and Figure 1-4 displays a gr ap hic i mage .

nd Figure 1-4 show typical displays that result from selecting a serv ice . Figure 1-3 shows a

Figure 1-3 Plain Text Display Example

Figure 1-4 Graphic Image Display Example

Cisco Unified Communications M anage r li mits Cisc o Unified IP Phone service activity to a specific Services pane in the Cisco Unified IP Phone display. A service cannot modify the top line of the phone

isplay , which contains the time, date , and primary extens ion. A service cannot ov erwrite the bottom line

d of the display, which contains softkey definitions. The pane tha t dis play s th e ser vice sit s flush with the left side of the display, and enough of the right side of the display remains intact to ensure that users can see the statu s of phone l ines.

1-2

Cisco Unified IP Phone Services Application Development Notes

OL-20949-01

Chapter 1 Overview

Note HTML Disclaimer: Phone service developers must take int o con si der ation t hat th e p hone i s no t a web

browser and cannot pars e H TML . Alt ho ugh c onte nt is de livered to th e phone thr oug h HT TP messa ges by using a web serv e r, keep in mind that the content is not HTML. Al l conte nt comes eithe r as plain tex t or packaged in propr i etary X ML w r ap pers .

OL-20949-01

Cisco Unified IP Phone Services Application Development Notes

1-3

Chapter 1 Overview

1-4

Cisco Unified IP Phone Services Application Development Notes

OL-20949-01

CHA PTER

New and Changed Information

This chapter gi ves details on t he new and changed informat ion in the XML servic e interface fo r the latest releases of Cisco Unified Communication Manager.

New Information for Cisco Unified Communications Manager

7.1(3)

The following are the updates made in the XML service interface for Cisco Unified Communication manager 7.1(3):

• Support for t he late st 99 71, 9951, a nd 89 61 seri es Cisc o IP p hon es. For more infor mat ion see

Table 3-1 on page 3-2

• The 9971, 99 51, 8 961 seri es I P ph one s doe s n ot su ppo rt t he C isco IPPho neSta tus an d

CiscoIPPhoneStatusFile XM L objects . For m ore in forma tion see , Table 3-1 on page 3-2.

• Key URIs supported in 9971, 9951, and 8961 series IP phones and alternate options for unsupported

Key URIs. For more informat ion see, “Key” section on page 5-2.

OL-20949-01

• Changes in softkey position, behavior, and design. For more information see, “SoftKey” section on

page 5-6.

Cisco Unified IP Phone Services Application Development Notes

2-1

New Information for Cisco Unified Communications Manager 7.1(3)

Chapter 2 New and Changed Information

2-2

Cisco Unified IP Phone Services Application Development Notes

OL-20949-01

CiscoIPPhone XML Objects

The following sections descri be the ge neral behavior an d use of XML obj ects:

• Understandin g Obj ec t Behavio r

• XML Object Definitions

• Custom Softkeys

• XML Considerat ions

• Application Event Handlers

Understanding Object Behavior

Creating interactive service applications is relatively easy when you understand the XML objects that are defined for Cisc o Unified IP Phones and the behavior that e ach objec t ge nerat es.

CHA PTER

Regarding services, the phone doe s not have any concept of a state when it loads an XM L page.

o Unified IP Phones can use HTTP to loa d a page of content in many dif ferent pla ces, st arting whe n

Cisc

e services button is pressed. Regardless of w ha t c ause s the p hon e t o lo ad a page , the phon e always

th behaves appropriately after it loads a page.

Appropriate behavior depe nds solely o n the type of d ata tha t h as been d elivered in the pag e. T he we b

ver must deliver the XML pages with a MIME type of text/xml. However, the exact mechanism

ser required v ari es accord ing to th e type of web serve r that y ou are u sing an d the ser ver side mechanis m that you are using to create your pages (for example, static files, JavaScript, CGI, and so on). See Chapter 6,

“HTTP Reques ts a nd H ead er S et tin gs” for mor e info rmati on.

OL-20949-01

Cisco Unified IP Phone Services Application Development Notes

3-1

Chapter 3 CiscoIPPhone XML Objects

Understanding Object Behavior

Table 3-1 shows the supported XML objects for this release.

Ta b l e 3-1 XML Objects Supported for Release 7.1(3) Cisco Unified IP Phone Services SDK

Phone Model XML Object

7905G 7906G 7911G 7912G 7931G 7920G

7921G 7925G

7940G 7960G

7941G/7941G-GE, 7942G,

945G, 7961G/7961G-GE,

7 7962G, 7965G, 7970G/ 7971G-GE, 7975G, IP Communicator

6921, 6941,

9971, 9951, 8961

CiscoIPPhoneMenu X X X X X X X CiscoIPPhoneText X X X X X X X CiscoIPPhoneInput X X X X X X X CiscoIPPhoneDirect ory X X X X X X X

CiscoIPPhoneImage — X

X X X —

CiscoIPPhoneImageFi le — — X — X —

CiscoIPPhoneGraphi cMenu — X

X X X —

CiscoIPPhoneGraphicFil eMenu — — X — X —

CiscoIPPhoneIco nMen u X CiscoIPPhoneIconFi leMe nu — — X — X

X X X X X

X CiscoIPPhoneStatus — — — X X — — CiscoIPPhoneStatusFile — — — — X

CiscoIPPhoneExecute X X

X X X X X

— —

CiscoIPPhoneResponse X X X X X X X CiscoIPPhoneError X X X X X X X

1. The C i s c o Unified IP Phone 7920G has only a 128-by-59 display with 2 grayscale images clipping the graphic equally on both sides and providing

vertical scrolling. When an image with 4 grayscale settings occurs (<Depth>2</Depth>), the phone equally splits them into 2 grayscale settings (0-1 get treated as 0 and 2-3 get treated as 1).

2. The C i s c o Unified IP Phones 6921, 6941, and 6961 do not support CiscoIPPhoneGraphicFileMenu, CiscoIPPhoneGraphicMenu,

CiscoIPPhoneImageFile, and CiscoIPPhoneImage

3. The C i s c o Unified IP Phones 7905G and 7912G do not support CIP images; therefore, all icons get ignored and does not display.

4. The C i s c o Unified IP Phones 6921, 6941, and 6961 do not support icons; therefore, all icons are ignored and does not display.

5. The C i s c o Unified IP Phones 7970G and 7971G-GE require firmware version 7.1(2) or higher to support this object, and Cisco IP Communicator

requires software version 2.01 or higher.

6. The Cisco Unified IP Phone 7920G does not support Priority 1 when on a call.

because these phones use monochrome LCD.

3-2

Cisco Unified IP Phone Services Application Development Notes

OL-20949-01

Chapter 3 CiscoIPPhone XML Objects

XML Object Definitions

The following sections provide definitions and descriptions of each CiscoIPPhone XML object:

• CiscoIPPhoneMenu

• CiscoIPPhoneText

• CiscoIPPhoneInput

• CiscoIPPhoneDirector y

• CiscoIPPhoneIm age

• CiscoIPPhoneIm ageFil e

• CiscoIPPhoneGraphic Menu

• CiscoIPPhoneGraphi cFileM enu

• CiscoIPPhoneIconM enu

• CiscoIPPhoneIconFil eMenu

• CiscoIPPhoneStatus

XML Object Definitions

• CiscoIPPhoneStatusFil e

• CiscoIPPhoneExecute

• CiscoIPPhoneRespon se

• CiscoIPPhoneError

CiscoIPPhoneMenu

A menu on the phone comprises a list of text items, one per line. Users choose individual menu items by using the same mechanisms that are used for built-in menus in th e phone as described in Chapter 1,

“Overview”.

Definition

<CiscoIPPhoneMenu> <Title>Title text goes here</Title> <Prompt>Prompt text goes here</Prompt> <MenuItem> <Name>The name of each menu item</Name> <URL>The URL associated with the menu item</URL> </MenuItem> </CiscoIPPhoneMenu>

Note • Th e Name field un der th e <MenuI tem > suppo rts a maximu m of 64 chara cters. Thi s field can also

accept two carriage returns to allow the MenuItem name to span three lines on the display.

• The 6900 series IP phones does not displa y the Title and Prompt menu fields at the same time. If

both Title and Prompt fields are defined at the same time, then these phones display only the Prompt field.

OL-20949-01

The XML format allo ws you to specif y a t itle a nd p rompt th at are use d fo r the entire menu, followed b y a sequence of

MenuItem includes a Name and an associated URL.

MenuItem objects. Cisco Unified IP Ph ones allow a maximu m of 100 MenuItems. Each

Cisco Unified IP Phone Services Application Development Notes

3-3

XML Object Definitions

When a menu is loaded, th e phone behaves the same as for built-in phone menus. The user navigates through the list of menu items and eventually chooses one by using either the Select softkey or the DTMF keys.

After the user chooses a me nu optio n, the phone ge ne rat es an HT TP requ est for the pa ge with th e URL

r executes the uniform resource identifiers (URIs) that are associated with the menu item.

CiscoIPPhoneText

The CiscoIPPhoneText XML object displays ordinary 8-bit ASCII text on the phone display. The <Text> message must not c onta in any c ontr ol cha ract ers, excep t fo r ca rri age re turn s, lin e fe ed s, an d t abs. T he Cisco Unified IP Phone firmware controls all othe r pagina tion and wordw rap issues.

Note Cisco Unified IP Phones support the full ISO 8859-1 (Latin 1) and Shift_JIS character sets.

Definition

<CiscoIPPhoneText> <Title>Title text goes here</Title> <Prompt>The prompt text goes here</Prompt> <Text>The text to be displayed as the message body goes here</Text> </CiscoIPPhoneText>

Chapter 3 CiscoIPPhone XML Objects

Note The 6900 series IP phones does not displa y the Title and Prompt menu fields at the same time.

If both Title and Prompt fields are defined at the same time, then t hes e phon es d isp lay only the Prompt field.

Two optional fields can appear in the XML message:

• The first optional field, Title, defines text that displays at th e top of the displ ay page . If a Title is

not specified, the

• The second opt ional field, Prompt, defines text th at di spla ys at the bot tom of the displa y p age. If a

Prompt is not specified, Cisco Unified Communications Manager c lea rs the prom pt are a of the

Name field of the last chosen MenuItem displays in the Title fiel d .

display pane.

Many XML objects that are described in this document also have

Title and Prompt fields. These fields

normally behave identically to behavior described in this section.

Note Non-XML Text: This document only describes the supported CiscoIPPhone XML objects. Y ou can also

deliver plain text via HTTP . P ages that are delivered as MIME type text/html behave exactly the same as XML pages of type

CiscoIPPhoneText. One important difference is that you cannot include a title or

prompt.

Note Keypad navigation: Cisco Unified IP Phones allow navigation to a specific line in a menu by pressing

numeric DTMF key s. When a menu is on the display, the number for selecting the menu is on the left.

When normal text displays, the numbers do not display on the left side of the screen, but the navigation capability still exists. So, a carefully written text service display can take advantage of this capability.

3-4

Cisco Unified IP Phone Services Application Development Notes

OL-20949-01

Chapter 3 CiscoIPPhone XML Objects

CiscoIPPhoneInput

When a Cisco Unified IP Phone receives an XML object of type CiscoIPPhoneInput, it constructs an input form and display s it. T he user then enters data in to each input item an d send s the parameter s to t he target URL. Figure 3-1 shows a sample display that is receiving input fro m a user.

Figure 3-1 Sample User Input Display

Definition

<CiscoIPPhoneInput> <Title>Directory title goes here</Title> <Prompt>Prompt text goes here</Prompt> <URL>The target URL for the completed input goes here</URL> <InputItem> <DisplayName>Name of the input field to display</DisplayName> <QueryStringParam>The parameter to be added to the target URL</QueryStringParam> <DefaultValue>The default display name</DefaultValue> <InputFlags>The flag specifying the type of allowable input</InputFlags> </InputItem> </CiscoIPPhoneInput>

XML Object Definitions

Note The 6900 series IP phones does not displa y the Title and Prompt menu fields at the same time.

If both Title and Prompt fields are defined at the same time, then the se p hon es d ispl ay onl y the Prompt field.

The Title and Prompt tags in the object delimit text are used in the sam e way as the identical fields in the other CiscoIPPhone XML obj ects.

URL tag delimits the URL to which the input results are sent. The actual HTTP request sent to this

The server specifies the URL with a list of parameters that are appended to it as a query string. The parameters includ e Name/Value pairs, one for each input item.

Note CiscoIPPhoneInput objects do not use the HTTP POST method.

The

InputItem tag delimits each item in the list. The number of InputItems must not exceed five. Each

input item includes a item. Each item als o has a

DisplayName, which is the prompt that is written to the display for that particular

QueryStringParam, which is the name of the parameter that is append ed to the

URL when it is sent out after input is co mplete. Each input ite m can al so use t he the default value to be displayed.

The final attribute for each input item comprises a set o f

InputFlags. The following table describes the

input types that are cu rrentl y defined .

DefaultValue tag to set

OL-20949-01

Cisco Unified IP Phone Services Application Development Notes

3-5

XML Object Definitions

Chapter 3 CiscoIPPhone XML Objects

InputFlag Description

A Plain ASCII text—use the DTMF keypad to enter text that consists

uppercase and l owe rcase l etters, numbe rs, and sp ecial c haracters .

T Telephone number—enter o nly DTMF digits for this field. The

cceptable input inc lude s numbe rs, #, a nd *.

a N Numeric—enter numbers as the only acceptable input. E Equation—enter numbers and special math symbols. U Uppercase—enter uppercase letters as the only acceptable input. L Lowercase—enter lowercase letters as the only acceptable input. P Password field—enter individual characters using the standard

eypad-repeat entry mode. The system automatically converts

accepted characters into an asterisk, keeping the entered value

private.

Note P specifies the only InputFlag that works as a modifier. For

example, specify a value of “AP” in the use plain ASCII as the input type and to mask the input as a password by using an asterisk (* ).

InputFlag field t o

During text entry, Cisco Unified IP Phones display softkeys to assist users with text entry. Users can navigate between fields with the vertical scroll button that is used to navigate men us, and so on.

CiscoIPPhoneDirectory

The phone ori gina lly i ncor por at ed th e CiscoIPPhoneDirectory X ML obj ect to su pport the Dir ectory operation of Cisco Unified IP Phones, but it is a v ailable for y our development purposes also. Figure 3-2 shows how an XML

Figure 3-2 CiscoIPPhoneDirectory Object Display Sample

Definition

<CiscoIPPhoneDirectory> <Title>Directory title goes here</Title> <Prompt>Prompt text goes here</Prompt> <DirectoryEntry> <Name>The name of the directory entry</Name> <Telephone>The telephone number for the entry</Telephone>

CiscoIPPhoneDirectory object displays on the phone.

3-6

Cisco Unified IP Phone Services Application Development Notes

OL-20949-01

Chapter 3 CiscoIPPhone XML Objects

</DirectoryEntry> </CiscoIPPhoneDirectory>

Note For the directory listing, the Cisco Unified IP Phone displays th e approp riate sof tke ys that ar e needed to

dial the numbers that are listed on the display. The softkeys include the Edit Dial softkey, which allows users to insert access codes or other nece ssary item s before dial ing.

The Title and Prompt tags in t he XML ob ject have the usu al sem antic s. A sing le

CiscoIPPhoneDirectory object can conta in a m aximu m o f 32 DirectoryEntry ob jects. If mo re than 32

entries must be returned, use multiple

Note The 6900 series IP phones do es not display th e Title and Prompt menu fields at the same time. If both

Title and Prompt fields are defined at th e sam e t ime , t he n the se phon es displ ay onl y t he P rompt fie l d .

Custom Directories

You can use the Cisco Unified Communications Manager enterprise parameter, “URL Directories” a nd CiscoIPPhone XML objects t o display custom directories. The “URL Directories” poi nts to a URL that returns a must return a valid

XML Object Definitions

CiscoIPPhoneDirectory objects in subsequent HTTP requests.

CiscoIPPhoneMenu object that extends the directories menu. The request fo r “URL Directori es”

CiscoIPPhoneMenu object, even if has n o DirectoryEntry objects.

To create a custom directory, use the following optional objects in the order in which they are listed:

1. Use the CiscoIPPhoneInput XML object to collect search criteria.

2. Use the CiscoIPPhoneText XML object to display status messages or errors.

3. Use the CiscoIPPhoneDirectory XML object to return a list of directory entries that can be dialed.

You can omit th e

CiscoIPPhoneDirectory objects by specifying an HTTP r efresh header that points to the URL of the n ext

individual directory object, which t he user accesses by pressing the Next softkey on the pho ne.

CiscoIPPhoneImage

The CiscoIPPhoneImage provides a bitmap display with a 133 x 65 pixel pane that is available to access services. Each pixel includes four grayscale settings. A value of three (3) displays as black, and a value of zero (0) displays as white.

Note The phone uses an LC D d ispl ay, which inverts the palette.

The

CiscoIPPhoneImage XML type lets you use the Cisco Unified IP Phone display to pres ent graphics

to the user.

Definition

<CiscoIPPhoneImage> <Title>Image title goes here</Title> <Prompt>Prompt text goes here</Prompt> <LocationX>Position information of graphic</LocationX> <LocationY>Position information of graphic</LocationY> <Width>Size information for the graphic</Width> <Height>Size information for the graphic</Height>

CiscoIPPhoneInput or CiscoIPPhoneText objects. You can display multiple

OL-20949-01

Cisco Unified IP Phone Services Application Development Notes

3-7

XML Object Definitions

Pixel values original sequence 1320

Pixel values converted to 2-bit binary pairs

01 001011

Re-ordered binary pairs

1-byte packed hexadecimal value

00 0110 11

Chapter 3 CiscoIPPhone XML Objects

<Depth>Number of bits per pixel</Depth> <Data>Packed Pixel Data</Data> <SoftKeyItem> <Name>Name of the softkey</Name> <URL>URL of softkey</URL> <Position>Numerical position of the softkey</Position> </SoftKeyItem> </CiscoIPPhoneImage>

Note The 6900 series IP phones does not displa y the Title and Prompt menu fields at the same time.

If both Title and Prompt fields are defined at the same time, then t hes e phon es d isp lay only the Prompt field.

The CiscoIPPhoneImage object definition includes two familiar elements: Title and Prompt. These elements serve the same purp ose as the y do in the other CiscoI PPhone XML objects. Th e at the top of the page, and the

LocationX and LocationY to position the graphic on the phone display. Position the upper, left corner

Use

Prompt displays at the bottom.

of the graphic at the pixel defined by these two parameters. Setting the X and Y location values to (0, 0) positions the graphic at the upper, left corner of the display. Setting the X and Y location values to (-1,

-1) centers the graphic in the services pane of the phone display.

Title displays

Width and Height to size the graphic. If the values do not match with the pixel stream specified in

Use

Data field, results will be unpredictable incorrect.

the

Depth specifies the number of bits per pixel. Cisco Unified IP Phones support a maximum value of 2. A

bit depth of 1 is blac k an d wh ite .

Data tag delimits a string of hexadecimal digits that contain the packed value of the pixels in the

The display. In the Cisco Unified IP Phone, each pixel has only four po ssibl e values, whi ch me ans tha t yo u

n pack four pixels into a single byte. A pa ir of hexadeci mal digi ts represe nts eac h byte.

Figure 3-3 p

rovides an example o f t h e me ch an ics of pixel pa c king. Sca nning f rom le ft to r ight in the

display, the illustration shows the process for packing consecutive pixel values of 1, 3, 2, and 0. First,

e pixels get converted to 2-bit binary numbers. Then, the binary pairs get re-ordered in sets of four to

th create a single re-orde red byte, wh ich two hexadecima l digits re presen t.

Figure 3-3 Packed Pixel Translation Example

3-8

Cisco Unified IP Phone Services Application Development Notes

OL-20949-01

Chapter 3 CiscoIPPhone XML Objects

Example

The following XML code defines a CiscoIPPhoneImage object that displays the sequence of pixels shown in Figure 3-3 as a graphic positioned at the center of the phone display:

The graphic display com pris es a contiguo us stream of hexadecima l digits, w ith no spac es or other separators. If the numbe r of pixels to be displaye d does not re present an even multiple of four, pad the end of the pixel data with blank (zero value) pixels, so the data is packed correctly. The phone ignores the padded data .

Tip Before displaying a graphic im age on a Cisc o Unified IP Phone, the software clears the pane dedicated

to services. If a service has te xt or other informa tion that must be preser ved (inc luding the title area), the information must get redra wn as p art of th e grap hic. If th e title is to be hidde n, the gr aphic m ust be la r ge enough to cover it.

XML Object Definitions

CiscoIPPhoneImageFile

The latest generation of Cisco Unified IP Phones have higher-resolution displays with more color depth. The Cisco Unified IP Phone 7970G, for example, has a disp lay area of 298 x168 pi xels available to the

vices pane and renders im ages in 12-b it col or.

Ser To s upport these m ore ad vanced di sp lays, a new XML o bj ect al lows the u se of c olor PNG ima ge s in

ddition to the grayscale

CiscoIPPhoneImage object, except for the image data. In stead of using the <Data> tag to embed the

the image data, the

<URL> tag points to the PNG image file.

The web server must del iver the PNG imag e to the pho ne wi th an ap propria te M IME Con tent- Type

ader, such as image/png, so the phone recognizes the content as a compressed, binary PNG image. The

he PNG image can be either palettized or RGB, and the maximum image size and color depth are model dependent (see Table 3-2).

Ta b l e 3-2 Cisco Unified IP Phones Display Image Sizes and Color Depths

Model

Cisco Unified IP Phones 7905G, 7906G,

7911G, 7912G

, 7931G Cisco Unified IP Phone 7920 128 x 59 Grayscale 1 Cisco Unified IP Phone 7921G, 7925G 176 x 140 Color 16 Cisco Unified IP Phones 7940G/60G 133 x 65 Grayscale 2 Cisco Unified IP Phones 7941G, 7941G-GE ,

942G, 7961G, 7961 G-GE, 7 962G

CiscoIPPhoneImage objects. The CiscoIPPhoneIm age Fil e object behave s li k e

Resolution (width x height)

Color/Grayscale /

Monochrome Color Depth (bits)

N/A Grayscale 1

298 x 144 Grayscale 4

OL-20949-01

Cisco Unified IP Phone Services Application Development Notes

3-9

XML Object Definitions

Table 3-2 Cisco Unified IP Phones Display Image Sizes and Color Depths (continued)

Chapter 3 CiscoIPPhone XML Objects

Color/Grayscale /Monochrome Color Depth (bits)

Model

Resolution (width x height)

Cisco Unified IP Phones 7945G, 7965G 298 x 156 Color 16 Cisco Unified IP Phone 7970G/797 1G 298 x 168 Color 12 Cisco Unified IP Phone 7975G 298 x 168 Color 16 Cisco IP Communicator 298 x 168 Color 24 Cisco Unified IP Phones 6921, 69 61 396 x 81 Monochrome — Cisco Unified IP Phone 6941 396 x162 Monochrome — Cisco Unified IP Phones 9971, 99 51, 8 961 498x289 Color 24

1. Represents the size of the display that is accessible by Services—not the full resolution of the physical display.

2. The C i s c o Unified IP Phones 7905 and 7912 have pixel-based displays, but they do not support XML images.

If the number of colors in the image is not reduced to match the phone capabilities, the image will be dithered by the phone and yield less than desirable results in most cases. To reduce the number of colors in a graphics editing program, such as Adobe Photoshop, use the “Posterize” command. The “Posterize” command takes one value as input for the number of color tones per color channel. For example, using the value of 16 (4-bits per channel = 16 tones per channel) will correctly dither the color palette of the image for the best display resu lts on the Cisc o Unified IP Phone 7970 G.

Figure 3-4

shows a CiscoIPPhoneImageFile object on a Cisco Unified IP Phone 7970G display.

Figure 3-4 Cisco Unified IP Phone 7970G Image File Display

Definition

<CiscoIPPhoneImageFile> <Title>Image Title goes here</Title> <Prompt>Prompt text goes here</Prompt> <LocationX>Horizontal position of graphic</LocationX> <LocationY>Vertical position of graphic</LocationY> <URL>Points to the PNG image</URL> </CiscoIPPhoneImageFile>

Note The 6900 series IP phones does not displa y the Title and Prompt menu fields at the same time.

If both Title and Prompt fields are defined at the same time, then t hes e phon es d isp lay only the Prompt field.

3-10

Cisco Unified IP Phone Services Application Development Notes

OL-20949-01

Chapter 3 CiscoIPPhone XML Objects

CiscoIPPhoneGraphicMenu

Graphic menus serve the sa me purpo se as text menus: they allow a user to select a URL from a list. Use graphic menus in situations when the items may not be easy to display in a text list.

For example, users might prefer to have their choices presented in a non-ASCII character set such as

nji or Arabic. W hen us ing n on- ASC II character sets, the system presents th e in f orm atio n as a bitmap

Ka graphic. To select a menu, the user enters a number from 1 to 12 usi ng the numeric keypad (* and # are not active).

Definition

<CiscoIPPhoneGraphicMenu> <Title>Menu title goes here</Title> <Prompt>Prompt text goes here</Prompt> <LocationX>Position information of graphic</LocationX> <LocationY>Position information of graphic</LocationY> <Width>Size information for the graphic</Width> <Height>Size information for the graphic</Height> <Depth>Number of bits per pixel</Depth> <Data>Packed Pixel Data</Data> <MenuItem> <Name>The name of each menu item</Name> <URL>The URL associated with the menu item</URL> </MenuItem> </CiscoIPPhoneGraphicMenu>

XML Object Definitions

Note The 6900 series IP phones does not displa y the Title and Prompt menu fields at the same time.

If both Title and Prompt fields are defined at the same time, then the se p hon es d ispl ay onl y the Prompt field.

Menu items in the graphic menu have a name, like the text menu counterparts. Although the name does not display to the user, it still performs a function. The name of the menu item provides the default title that is used when th e URL for the chosen item is loaded. If the loaded page has a title of its own, the phone uses that title instead.

The XML tags in

GraphicMenu use the tag definitions for CiscoIPPhoneImage and CiscoIPPhoneMenu.

Although the semantic s of the tags are identic al, you ca n have only 12

CiscoIPPhoneGraphicMenu object. See “CiscoIPPhoneMenu” and “CiscoIPPhoneImage ” for detailed

descriptions.

CiscoIPPhoneGraphicFileMenu

Some of the Cisco Unified IP Phone models, such as the Cisco Unified IP Phon e 7970G and Cisco IP Communicato r, have pointer devices. The Cisco Unified IP Phone 7970G us es a t ou chs cree n

verlay on the display, and the PC-based Cisco IP Communi cator u ses the st anda rd Windows mouse

nter.

poi Because these devices can receive and process “pointer” events, a

object exposes the capability to application developers. The CiscoIPPhoneGraphicFileMenu behaves similar to the CiscoIPPhoneGra phicM enu, in that a gr oup of opti ons are prese nted by an image. Whe n one of those objects is selected, a UR L action ini tiates. However, the new FileMenu does not use the keypad, but uses rectangular touch areas. This rectangular touch area, coordinates relative to the upper-left corner of the Services display. The (X1,Y1) points specify the upper-left co rner of the

<TouchArea>, and (X2,Y2) specify the lower-right corner of the <TouchArea>.

MenuItem objects in a

CiscoIPPhoneGraph icFile Menu

<TouchArea>, is defined by

OL-20949-01

Cisco Unified IP Phone Services Application Development Notes

3-11

XML Object Definitions

Chapter 3 CiscoIPPhone XML Objects

Figure 3-5 shows the display of the CiscoIPPhoneGraphicFileMenu.

Figure 3-5 CiscoIPPhoneGraphicFileMenu

If the coordinates that are supplied in <TouchArea> tag exceed the dimensions of the phone display, the

<TouchArea> rectangle will be “cli pped” t o f it. See Table 3-2 , “Cisco Unified IP Phones Display Image

Sizes and Color Depths” for a listing of u sab le displa y r esolut ions for ea ch ph one mod el.

<TouchArea> rectangles are allowed to overlap, and the first match is always taken. This allows a

The sense of Z-order for images w here smal ler touc hable obj ects c an be overlaid on top of larger ones. In this case, the smaller object

<CiscoIPPhoneGraphi cFileM enu > object.

The requiremen ts f or th e P NG ima ge r e fere nc ed by the

<MenuItem> must appear before the larger one in the

<URL> tag match t hose t h at the

CiscoIPPhoneImageFile ob ject uses.

Definition

<CiscoIPPhoneGraphicFileMenu> <Title>Image Title goes here</Title> <Prompt>Prompt text goes here</Prompt> <LocationX>Horizontal position of graphic</LocationX> <LocationY>Vertical position of graphic</LocationY> <URL>Points to the PNG background image</URL> <MenuItem> <Name>Same as CiscoIPPhoneGraphicMenu</Name> <URL>Invoked when the TouchArea is touched</URL> <TouchArea X1="left edge" Y1="top edge" X2="right edge" Y2="bottom edge"/> </MenuItem> </CiscoIPPhoneGraphicFileMenu>

Note The 6900 series IP phones does not displa y the Title and Prompt menu fields at the same time.

If both Title and Prompt fields are defined at the same time, then t hes e phon es d isp lay only the Prompt field.

CiscoIPPhoneIconMenu

Icon menus serve the same p urpose as tex t menus: the y allo w a user to selec t a URL from a list. Use icon menus in situations when you want to provide additional visual information to the user to show the state or category of an item. For example, y ou inclu de a read an d unread icon in a mail viewer. You can use the icons can to convey the message sta te.

Cisco Unified IP Phone Services Application Development Notes

3-12

OL-20949-01

+ 86 hidden pages

Cisco Systems OL-20949-01 User Manual

CONTENTS

Overview

Preface

Revision History

Audience

Cisco Developer Support Program

Organization

Related Documentation

Cisco Product Security Overview

Document Conventions

Overview

New and Changed Information

CiscoIPPhone XML Objects

Understanding Object Behavior

XML Object Definitions

CiscoIPPhoneMenu

CiscoIPPhoneText

CiscoIPPhoneInput

CiscoIPPhoneDirectory

Custom Directories

CiscoIPPhoneImage

CiscoIPPhoneImageFile

CiscoIPPhoneGraphicMenu

CiscoIPPhoneGraphicFileMenu

CiscoIPPhoneIconMenu