Cisco IP Phone Services Application Development Notes for Release 3.3.3

Table Of Contents

Cisco IP Phone Services Application Development Notes

Contents

Introduction

CiscoIPPhone XML Objects

CiscoIPPhoneMenu

CiscoIPPhoneText

CiscoIPPhoneInput

CiscoIPPhoneDirectory

CiscoIPPhoneImage

CiscoIPPhoneGraphicMenu

CiscoIPPhoneIconMenu

CiscoIPPhoneExecute

CiscoIPPhoneResponse

CiscoIPPhoneError

CiscoIPPhone XML Object Quick Reference

XML Considerations

Mandatory Escape Sequences

Custom Soft Keys

XML Objects Used With Nonstreaming URIs

URIs for Pressing Buttons on the Phone

URIs for Invoking SoftKey Functionality

URIs to Control RTP Streaming

Miscellaneous URIs

Cisco IP Services Software Development Kit (SDK)

Sample Services Requirements

HTTP Client Requests

HTTP Header Settings

HTTP Refresh Setting

MIME Type and Other HTTP Headers

Content Expiration Header Setting

IP Phone Service Administration and Subscription

Adding a Phone Service

Defining IP Phone Service Parameters in Cisco CallManager Administration

User Service Subscription

Troubleshooting Cisco IP Phone Service Applications

XML Parsing Errors

Error Messages

DeviceListX Report

Benefits

Restrictions

Integration Considerations and Interoperability

Performance and Scalability

Security

Related Features and Technologies

Supported Platforms

Prerequisites

Message and Interface Definitions

DeviceList XML Object

Troubleshooting DeviceListX Reports

Related Documentation

Obtaining Documentation

Cisco.com

Documentation CD-ROM

Ordering Documentation

Documentation Feedback

Obtaining Technical Assistance

Cisco.com

Developer Support

Technical Assistance Center

Obtaining Additional Publications and Information

Cisco IP Phone Services Application Development Notes

Use this document with Cisco CallManager 3.3(3) to develop and deploy customized client services for the Cisco IP Phone 7960 and 7940 models, which support Cisco IP Phone services.

Note Developers using this guide should join the Cisco Developer Support Program because standard Cisco TAC support is limited to the Cisco AVVID installation, configuration, and Cisco-developed applications. This program provides a consistent level of dependable support while leveraging Cisco interfaces in your development projects. For more information about the program and how to join, contact us at developer-support@cisco.com.

Contents

This document covers the following topics:

• Introduction

• CiscoIPPhone XML Objects

• CiscoIPPhone XML Object Quick Reference

• XML Considerations

• Custom Soft Keys

• Cisco IP Services Software Development Kit (SDK)

• HTTP Client Requests

• HTTP Header Settings

• IP Phone Service Administration and Subscription

• User Service Subscription

• Troubleshooting Cisco IP Phone Service Applications

• DeviceListX Report

• Related Documentation

• Obtaining Technical Assistance

Introduction

You can use Cisco IP Phones, such as the Cisco IP Phone 7960 and 7940, to deploy customized client services with which users can interact via the keypad and display. Services deploy using the HTTP protocol from standard web servers, such as Microsoft IIS. This document provides the information needed for eXtensible Markup Language (XML) and X/Open System Interface (XSI) programmers and system administrators to develop and deploy new services.

Note Currently, only Cisco IP Phone 7960 and 7940 models support Cisco IP Phone services. Throughout this document, the term "Cisco IP Phone" applies only to the Cisco IP Phone 7960 and 7940.

Cisco IP Phones have buttons labeled services and directories. When a user presses the services button, a menu of services that are configured for the phone displays. The user then chooses a service from the listing, and the phone display updates.

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

•Weather

•Stock information

•Contact information

•Company news

•To-do lists

•Daily schedule

Figure 1 shows a sample text menu created during development.

Figure 1 Cisco IP Phone Text Menu Sample

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

Figure 2 Graphic Menu on a Cisco IP Phone Sample

The way that a service is configured determines whether a graphic or text menu displays.

A phone user can navigate a text menu using the up/down rocker switch followed by the Select soft key, or by using the DTMF keypad to enter a selection directly. Graphic menus do not currently support any type of cursor-based navigation; users simply enter a numeric item selection using the DTMF keypad.

When a menu selection is made, the Cisco IP Phone acts on it by using its HTTP client to load a specific URL. The return type from this URL can be plain text or one of the CiscoIPPhone XML objects. The object loads and then interacts with the user in an appropriate manner for the object.

Figure 3 and Figure 4 show typical displays that result from selecting a service. Figure 3 shows a stock quote that was generated using plain text.

Figure 3 Plan Text Display Example

Figure 4 displays a graphic image.

Figure 4 Graphic Image Display Example

Cisco CallManager limits Cisco IP Phone service activity to a specific Services pane in the Cisco IP Phone display. A service cannot modify the top line of the phone display, which contains the time, date, and primary extension. A service cannot overwrite the bottom line of the display, which contains soft key definitions. The pane that displays the service sits 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 status of phone lines.

Note HTML Disclaimer: Phone service developers must take into consideration that the phone is not a web browser and cannot parse HTML. Although 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 either as plain text or packaged in proprietary XML wrappers.

CiscoIPPhone XML Objects

Creating interactive service applications proves relatively easy once you understand the XML objects that are defined for Cisco IP Phones and the behavior that each object generates.

Regarding services, understand that the phone does not have any concept of a state when it loads an XML page. Cisco IP Phones can use HTTP to load a page of content in many different places, starting when the services button is pressed. Regardless of what causes the phone to load a page, the phone always behaves appropriately once it loads a page.

Appropriate behavior depends solely on the type of data that has been delivered in the page. This section of the document discusses the supported XML display types and how they work with Cisco IP Phones.

The web server must deliver the XML pages with a MIME type of text/xml. The exact mechanism required varies according to the type of web server that you are using and the server side mechanism that you are using to create your pages; for example, static files, JavaScript, CGI, and so on.

See "MIME Type and Other HTTP Headers" for more information.

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

• CiscoIPPhoneMenu

• CiscoIPPhoneText

• CiscoIPPhoneInput

• CiscoIPPhoneDirectory

• CiscoIPPhoneImage

• CiscoIPPhoneGraphicMenu

• CiscoIPPhoneIconMenu

• CiscoIPPhoneExecute

• CiscoIPPhoneResponse

• CiscoIPPhoneError

CiscoIPPhoneMenu

A menu on the phone comprises a list of text items, one per line. Users choose individual menu items using the exact same mechanisms that is used for built-in menus in the phone, such as those seen in the Cisco IP Phone settings pages.

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>
<SoftKeyItem>
<Name>Name of soft key</Name>
<URL>URL or URI of soft key</URL>
<Position>Position information of the soft key</Position>
</SoftKeyItem>
</CiscoIPPhoneMenu>

Note The Name field under the <MenuItem> now supports 64 characters. This field can also accept two carriage returns to allow the MenuItem name to span three lines on the display.

The XML format allows you to specify a title and prompt that are used for the entire menu, followed by a sequence of MenuItem objects. Cisco IP Phones allow a maximum of 100 MenuItems. Each MenuItem includes a Name and an associated URL.

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

After the user chooses a menu option, the phone generates an HTTP request for the page with the URL or executes the uniform resource identifiers (URIs) 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 contain any control characters, except for carriage returns, line feeds, and tabs. The Cisco IP Phone firmware controls all other pagination and wordwrap issues.

Note The Cisco IP Phone now supports the full ISO 8859-1 (Latin 1) character set.

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>
<SoftKeyItem>
<Name>Name of soft key</Name>
<URL>URL or URI of soft key</URL>
<Position>Position information of the soft key</Position>
<SoftKeyItem>
</CiscoIPPhoneText>

Two optional fields can appear in the XML message:

•The first optional field, Title, defines text that displays at the top of the display page. If a Title is not specified, the Name field of the last chosen MenuItem displays in the Title field.

•The second optional field, Prompt, defines text that displays at the bottom of the display page. If a Prompt is not specified, Cisco CallManager clears the prompt area of the 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.

The display shown in Figure 3 provides an example of a text display. The title appears at the top above the text.

Note Non-XML Text: This document only describes the supported CiscoIPPhone XML objects. You can also deliver plain text via HTTP. Pages delivered as MIME type text/html behave exactly the same as XML pages of type CiscoIPPhoneText. The only important difference is that you cannot include a title or prompt.

Note Keypad navigation: Cisco IP Phones allow navigation to a specific line in a menu by pressing numeric DTMF keys. When a menu is on the display, the actual number to be pressed displays on the left side of the screen.

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.

CiscoIPPhoneInput

When a Cisco IP Phone receives an XML object of type CiscoIPPhoneInput, it constructs an input form and displays it. The user then enters data into each input item and sends the parameters to the target URL. Figure 5 shows a sample display that is receiving input from a user.

Figure 5 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>
<SoftKeyItem>
<Name>Name of soft key</Name>
<URL>URL or URI of soft key</URL>
<Position>Position information of the soft key</Position>
<SoftKeyItem>
</CiscoIPPhoneInput>
The Title and Prompt tags in the object delimit text that is used in the same way as the identical fields in the other CiscoIPPhone XML objects.

The URL tag delimits the URL to which the input results are sent. The actual HTTP request sent to this server specifies the URL with a list of parameters appended to it as a query string. The parameters include Name/Value pairs, one for each input item.

Note Cisco IP Phones 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 has a DisplayName, which is the prompt written to the display for that particular item. Each item also has a QueryStringParam, which is the name of the parameter appended to the URL when it is sent out after input is complete. Each input item can also use the DefaultValue tag to set the default value to be displayed.

The final item for each input item comprises a set of InputFlags. The following table describes the input types that are currently defined.

InputFlag

Description

A

Plain ASCII text. Use the DTMF keypad to enter text consisting of uppercase and lowercase letters, numbers, and special characters.

T

Telephone number. Enter only DTMF digits for this field. The acceptable input includes numbers, #, and *.

N

Numeric. Enter only numbers as the only acceptable input.

E

Equation. The acceptable input includes numbers and special math symbols.

U

Uppercase. Enter only uppercase letters as the only acceptable input.

L

Lowercase. Enter only lowercase letters as the only acceptable input.

P

Password field. Individual characters display as they are entered using the standard keypad-repeat entry mode. As soon as each character is accepted, the system converts it to an asterisk, allowing for privacy of the entered value.

Note P specifies the only InputFlag that works as a modifier. For example, specify a value of "AP" in the InputFlag field to use plain ASCII as the input type and to mask the input as a password using an asterisk (*).

Soft Keys

During text entry, Cisco IP Phones display soft keys to assist users with text entry. The soft key names are as follows:

Soft Key Name

Description

Select

Initiates an action on a marked item from a menu, directory, or form. (The action can be checking or unchecking the item, or presenting a new page.) Marked items are highlighted on the IP Phone.

OK

Commits any value changes and presents a new page to users. (The new page is often the page users used to access the current page.)

Also used to show agreement to information contained in a message.

Cancel

Skips committing value changes and presents a new page to users. (The new page is often the page that allows users to access the current page.)

Exit

Exits out of a menu on your phone LCD screen

Next

Presents the next item in a sequence of items, which can be pages, directory entries, form entries, and so on.

Back

Goes back to a parent page of a lower level page. (Backs up in a service menu hierarchy.)

Back can also be used to present the previous item in a sequence of items. Items can be pages, directory entries, form entries, and so on.

Update

Reloads and updates the current page

Dial

Dials the phone number of a selected entry

EditDial

Allows users to insert access codes or other necessary items before dialing.

Submit

Indicates that the form is complete and that the resulting URL should be requested via HTTP

<<

Backspaces within a field

Users can navigate between fields with the vertical scroll button that is used to navigate menus, and so on.

CiscoIPPhoneDirectory

The phone actually incorporated the CiscoIPPhoneDirectory XML object to support the Directory operation of Cisco IP Phones. Because the functionality already exists in the phone, phone service application developers have it available as well. Figure 6 shows how an XML CiscoIPPhoneDirectory object displays on the phone.

Figure 6 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>
</DirectoryEntry>
<SoftKeyItem>
<Name>Name of soft key</Name>
<URL>URL or URI of soft key</URL>
<Position>Position information of the soft key</Position>
<SoftKeyItem>
</CiscoIPPhoneDirectory>

Note For the directory listing, the Cisco IP Phone displays the appropriate soft keys that are needed to dial the numbers listed on the display. The soft keys include the Edit Dial soft key, which allows users to insert access codes or other necessary items before dialing.

The Title and Prompt tags in the XML object have the usual semantics. A single CiscoIPPhoneDirectory object can contain a maximum of 32 DirectoryEntry objects. If more than 32 entries must be returned, use multiple CiscoIPPhoneDirectory objects in subsequent HTTP requests.

Custom Directories

You can use the "URL Directories" enterprise parameter and CiscoIPPhone XML objects to display custom directories.

The Cisco CallManager enterprise parameter "URL Directories" points to a URL that returns a CiscoIPPhoneMenu object that extends the directories menu. The request for "URL Directories" must return a valid CiscoIPPhoneMenu object, even if has no DirectoryEntry objects.

You must use the following optional objects, if used, in the order in which they are listed:

•Use the CiscoIPPhoneInput XML object to collect search criteria.

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

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

You can omit the CiscoIPPhoneInput or CiscoIPPhoneText objects. You can display multiple CiscoIPPhoneDirectory objects by specifying an HTTP refresh header that points to the URL of the next individual directory object, which the user accesses by pressing the Next soft key on the phone.

CiscoIPPhoneImage

Cisco IP Phones include a bitmap display with a 133 x 65 pixel pane that is available to access services. Each pixel includes four greyscale settings. A value of three (3) displays as black, and a value of zero (0) displays as white.

Note The phone uses an LCD display, which explains why the palette is inverted.

The CiscoIPPhoneImage XML type lets you use the Cisco IP Phone display to present graphics to the user. Figure 4 shows an example of how this looks on the current release of the Cisco IP Phone.

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>
<Depth>Number of bits per pixel</Depth>
<Data>Packed Pixel Data</Data>
<SoftKeyItem>
<Name>Name of the soft key</Name>
<URL>URL of soft key</Name>
<Position>Numerical position of the soft key</Position>
<SoftKeyItem>
</CiscoIPPhoneImage>

The CiscoIPPhoneImage object definition includes two familiar elements: Title and Prompt. These elements serve the same purpose as they do in the other CiscoIPPhone XML objects. The Title displays at the top of the page, and the Prompt displays at the bottom.

Use LocationX and LocationY to position the graphic on the phone display. Position the upper, left corner 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.

Self-explanatory values include Width and Height. If the values specified do not match up properly with the pixel stream specified in the Data field, unpredictable and generally incorrect results occur.

Depth specifies the number of bits per pixel. Cisco IP Phones support a maximum value of 2. A bit depth of 1 is black and white.

The Data tag delimits a string of hexadecimal digits that contain the packed value of the pixels in the display. In the Cisco IP Phone, each pixel comprises only four possible values, which means that you can pack four pixels into a single byte. A pair of hexadecimal digits represents each byte.

Figure 7 provides an example of the mechanics of pixel packing. Scanning from left to right in the display, the illustration shows the process for packing consecutive pixel values of 1, 3, 2, and 0. First, the pixels get converted to 2-bit binary numbers. Then, the binary pairs get re-ordered in sets of four to create a single re-ordered byte, which two hexadecimal digits represent.

Figure 7 Packed Pixel Translation Example

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

<CiscoIPPhoneImage>
<Title/>
<LocationX>-1</LocationX>
<LocationY>-1</LocationY>
<Width>4</Width>
<Height>1</Height>
<Depth>2</Depth>
<Data>2D</Data>
<Prompt/>
</CiscoIPPhoneImage>

The graphic display comprises a contiguous stream of hexadecimal digits, with no spaces or other separators. If the number of pixels to be displayed does not represent 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 When graphics display on a Cisco IP Phone, the software clears the pane dedicated to services before a graphic image displays. If a service has text or other information that must be preserved, the information must get redrawn as part of the graphic.

This includes the title area. If the title is to be hidden, the graphic must be large enough to cover it.

CiscoIPPhoneGraphicMenu

Graphic menus serve the same purpose 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 Kanji or Arabic. Figure 2 shows a graphic menu on a Cisco IP Phone.

In these cases, the system presents the information as a bitmap graphic. The user then enters a menu selection by using the DTMF keypad to enter a number.

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>
<SoftKeyItem>
<Name>Name of soft key</Name>
<URL>URL of soft key</URL>
<Position>Numerical position of the soft key</Position>
<SoftKeyItem>
</CiscoIPPhoneGraphicMenu>
Menu items in the graphic menu have a name, just 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 used when the 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 semantics of the tags are identical, you can have only 12 MenuItem objects in a CiscoIPPhoneGraphicMenu object. See "CiscoIPPhoneMenu" and "CiscoIPPhoneImage" for detailed descriptions.

CiscoIPPhoneIconMenu

Icon menus serve the same purpose as text menus: they allow a user to select 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. Having a read and unread icon in a mail viewer serves as an example. The icons can convey the message state with the icon. Icons in the CiscoIPPhoneMenu object have a maximum width of 16 pixels and a maximum height of 10 pixels.

Figure 8 shows an IconMenu on a Cisco IP Phone.

Figure 8 IconMenu on a Cisco IP Phone Sample

In these cases, the system presents the information as a bitmap graphic to the left of the menu item text. The user selects menu items that are the same as a CiscoIPPhoneMenu object.

Definition

<CiscoIPPhoneIconMenu>
<Title>Title text goes here</Title>
<Prompt>Prompt text goes here</Prompt>
<MenuItem>
<IconIndex>Indicates what IconItem to display</IconIndex>
<Name>The name of each menu item</Name>
<URL>The URL associated with the menu item</URL>
</MenuItem>
<SoftKeyItem>
<Name>Name of soft key</Name>
<URL>URL or URI of soft key</URL>
<Position>Position information of the soft key</Position>
</SoftKeyItem>
<IconItem>
<Index>A unique index from 0 to 9</Index>
<Height>Size information for the icon</Height>
<Width>Size information for the icon</Width>
<Depth>Number of bits per pixel</Depth>
<Data>Packed Pixel Data</Data>
</IconItem>
</CiscoIPPhoneIconMenu>
The XML tags in IconMenu use the tag definitions for CiscoIPPhoneImage and CiscoIPPhoneMenu. Although the semantics of the tags are identical, you can only have 32 MenuItem objects in a CiscoIPPhoneIconMenu object. See "CiscoIPPhoneMenu" and "CiscoIPPhoneImage" for detailed descriptions.

CiscoIPPhoneExecute

The CiscoIPPhoneExecute object differs from the other CiscoIPPhone objects. You use this object to push a request to the phone via its web server. You must use the HTTP POST method to submit the object to the phone.

You post the CiscoIPPhoneExecute object to a case-sensitive URL. The URL http://x.x.x.x/CGI/Execute, replaces the x.x.x.x with the IP address of the destination Cisco IP Phone. The form that you post should have a case-sensitive form field name called "XML" that contains the XML object that you are posting. You can post multiple requests in a single object and receive a ResponseItem for each ExecuteItem.

When posting a CiscoIPPhoneExecute object to a phone you must provide basic HTTP authentication information with the POST. The credentials that you provide must be that of a user in the global directory with a device association with the target phone. If the credentials are invalid, or the Authentication URL is not set properly in the Cisco CallManager administration, the phone will return a CiscoIPPhoneError with a value of 4 (Authentication Error).

Note Limit the requests to three ExecuteItems: only one can be a URL and two URIs per CiscoIPPhoneExecute object. Or you can send three URIs with no URL.

Definition

<CiscoIPPhoneExecute>
<ExecuteItem URL="the URL or URI to be executed"/>
<CiscoIPPhoneExecute>
CiscoIPPhoneResponse

ResponseItems exist for all ExecuteItems that you send. The order differs according to completion time and the execution order is not guaranteed. The URL attribute specifies the URL or URI that was sent with the request. The Data attribute contains any special data for the item. The Status attribute specifies a status code. Zero indicates that no error occurred during processing of the ExecuteItem. If an error occurred, the phone returns a CiscoIPPhoneError object.

Definition

<CiscoIPPhoneResponse>
<ResponseItem Status="the success or failure of the action" Data="the information returned with the response" URL="the URL or URI specified in the Execute object"/>
<CiscoIPPhoneResponse>
CiscoIPPhoneError

The following list gives possible CiscoIPPhoneError codes:

•Error 1 = Error parsing CiscoIPPhoneExecute object

•Error 2 = Error framing CiscoIPPhoneResponse object

•Error 3 = Internal file error

•Error 4 = Authentication error

Definition

<CiscoIPPhoneError Number="x"/>

CiscoIPPhone XML Object Quick Reference

Table 1 provides a quick reference of the CiscoIPPhone XML objects and the definitions associated with each.

Table 1 CiscoIPPhone XML Object Quick Reference

Object

Definition

CiscoIPPhoneMenu

<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>
<SoftKeyItem>
<Name>Name of soft key</Name>
<URL>URL or URI of soft key</URL>
<Position>Position information of the soft key</Position>
</SoftKeyItem>
</CiscoIPPhoneMenu>

CiscoIPPhoneText

<CiscoIPPhoneText>
<Title>Title text goes here</Title>
<Prompt>The prompt text goes here</Prompt>
<Text>Text to display as the message body goes here</Text>
<SoftKeyItem>
<Name>Name of soft key</Name>
<URL>URL or URI of soft key</URL>
<Position>Position information of the soft key</Position>
<SoftKeyItem>
</CiscoIPPhoneText>

CiscoIPPhoneInput

<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 input field to display</DisplayName>
<QueryStringParam>The parameter to be added to the target URL</QueryStringParam>
<DefaultValue>Value</DefaultValue>
<InputFlags>The flag specifying the type of allowable input</InputFlags>
</InputItem>
<SoftKeyItem>
<Name>Name of soft key</Name>
<URL>URL or URI of soft key</URL>
<Position>Position of information of the soft key</Position>
</SoftKeyItem>
</CiscoIPPhoneInput>

CiscoIPPhoneDirectory

<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>
</DirectoryEntry>
<SoftKeyItem>
<Name>Name of soft key</Name>
<URL>URL or URI of soft key</URL>
<Position>Position information of the soft key</Position>
</SoftKeyItem>
</CiscoIPPhoneDirectory>

CiscoIPPhoneImage

<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>
<Depth>Number of bits per pixel</Depth>
<Data>Packed Pixel Data</Data>
<SoftKeyItem>
<Name>Name of soft key</Name>
<URL>URL of soft key</URL>
<Position>Numerical position of the soft key</Position>
</SoftKeyItem>
</CiscoIPPhoneImage>

CiscoIPPhoneGraphicMenu

<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>
<SoftKeyItem>
<Name>Name of soft key</Name>
<URL>URL of soft key</URL>
<Position>Numerical position of the soft key</Position>
</SoftKeyItem>
</CiscoIPPhoneGraphicMenu>

CiscoIPPhoneIconMenu

<CiscoIPPhoneIconMenu>
<Title>Title text goes here</Title>
<Prompt>Prompt text goes here</Prompt>
<MenuItem>
<IconIndex>Indicates what IconItem to display</IconIndex>
<Name>The name of each menu item</Name>
<URL>The URL associated with the menu item</URL>
</MenuItem>
<SoftKeyItem>
<Name>Name of soft key</Name>
<URL>URL or URI of soft key</URL>
<Position>Position information of the soft key</Position>
</SoftKeyItem>
<IconItem>
<Index>A unique index from 0 to 9</Index>
<Height>Size information for the icon</Height>
<Width>Size information for the icon</Width>
<Depth>Number of bits per pixel</Depth>
<Data>Packed Pixel Data</Data>
</IconItem>
</CiscoIPPhoneIconMenu>

CiscoIPPhoneExecute

<CiscoIPPhoneExecute>
<ExecuteItem URL="The URL or URI to be executed"/>
<CiscoIPPhoneExecute>

CiscoIPPhoneError

<CiscoIPPhoneError Number="x"/>

CiscoIPPhoneResponse

<CiscoIPPhoneResponse>
<ResponseItem Status"the success or failure of the action"Data="the information associated with the request" URL="the URL or URI specified in the Execute object"/>
<CiscoIPPhoneResponse>

XML Considerations

The XML parser in Cisco IP Phones does not function as a fully capable XML parser. Do not include any tags other than those defined in your XML display definitions.

Note All CiscoIPPhone element names and attribute names are case sensitive.

Mandatory Escape Sequences

By XML convention, the XML parser also requires that you escape a few special characters. Table 2 lists characters and their escape values.

.

Table 2 Escape Sequences for Special Characters

Character

Name

Escape Sequence

&

Ampersand

&

"

Quote

"

'

Apostrophe

'

<

Left angle bracket

<

>

Right angle bracket

>

Escaping text can be tedious, but some authoring tools or scripting languages can automate this task.

Custom Soft Keys

Cisco IP Phones now have the ability to receive custom soft keys with the CiscoIPPhone objects. Soft keys can have URLs or URIs associated with them. Newly created URIs allow you to call the native softkey event with a custom soft key.

XML Objects Used With Nonstreaming URIs

This section describes objects that you use in what context with nonstreaming URIs and what, if any, comprise the object order requirements.

The following list contains the XML objects that can be used:

•CiscoIPPhoneMenu

•CiscoIPPhoneIconMenu

•CiscoIPPhoneText

•CiscoIPPhoneImage

•CiscoIPPhoneGraphicMenu

•CiscoIPPhoneInput

•CiscoIPPhoneDirectory

URIs for Pressing Buttons on the Phone

The Key URI allows a programmer to send an event that a key has been pressed. The same event is fired as when the physical buttons are pressed. The phone hook switch is not exposed since this would cause the hardware to be out of sync with the software.

Note While pressing buttons with this method, the button may not be available when the URI is processed and the event is thrown away as a result.

Example 1 Key:Soft1

If the soft key set is changing and disabled while the event is being processed, the request is discarded.

Verification of available soft keys is achieved with the QA web pages provided by the phones web server that indicate the active soft key set.

Key

URI Format:

Key:n

Where

n is a Key name. The following is a complete listing of the Key URIs:

•Key:Line1 to Key:Line34

•Key:KeyPad0 to Key:KeyPad9

•Key:Soft1 to Key:Soft4

•Key:KeyPadStar

•Key:KeyPadPound

•Key:VolDwn

•Key:VolUp

•Key:Headset

•Key:Speaker

•Key:Mute

•Key:Info

•Key:Messages

•Key:Services

•Key:Directories

•Key:Settings

•Key:NavUp

•Key:NavDwn

URIs for Invoking SoftKey Functionality

An XSI developer can execute native soft key functionality when the phone executes a SoftKey URI. The primary purpose for the SoftKey URI is to allow developers the ability to customize soft key names and layout in the Services and Directories windows while retaining the functionality that the soft keys provide.

SoftKey URIs work in menu items, soft key items, and execute items that are pushed to the phone. The SoftKey URIs use is limited to the objects on which they natively occur on the phone.

SoftKey

URI Format:

SoftKey:n

Where

n is one of the following soft key names:

•Back

•Cancel

•Exit

•Next

•Search

•Select

•Submit

•Update

•Dial

•EditDial

•<<

Valid soft key actions for each XSI object type follow. The URI invokes the native functionality that each key possesses in the given object context.

•CiscoIPPhoneMenu

–SoftKey:Select

–SoftKey:Exit

•CiscoIPPhoneIconMenu

–SoftKey:Select

–SoftKey:Exit

•CiscoIPPhoneText

–SoftKey:Update

–SoftKey:Exit

•CiscoIPPhoneImage

–SoftKey:Update

–SoftKey:Exit

•CiscoIPPhoneGraphicMenu

–SoftKey:Update

–SoftKey:Exit

•CiscoIPPhoneInput

–SoftKey:Submit

–SoftKey:Search—only when used under the Directories button

–SoftKey:<<

–SoftKey:Cancel

•CiscoIPPhoneDirectory

–SoftKey:Dial

–SoftKey:EditDial

–SoftKey:Cancel

–SoftKey:Next—only when used under the Directories button

Generic URIs that can be used in place of URLs follow:

•Dial:2000 (where 2000 represents the number to be dialed)

•EditDial:2000 (where 2000 represents the number to load into the edit dial context)

QueryStringParam URI

The QueryStringParam URI allows an application developer to collect more information from the user with less interaction. When the user performs an action with a soft key, you can either append a query string parameter to the URL of the highlighted MenuItem or append the query string parameter from the MenuItem to the URL of the soft key.

URI Format:

QueryStringParam:d

Where

d = the data to be appended to a corresponding URL.

Example 2 QueryStringParam URI in a CiscoIPPhoneMenu object

<CiscoIPPhoneMenu>
<Title>Message List</Title>
<Prompt>Two Messages</Prompt>
<MenuItem>
<Name>Message One</Name>
<URL>QueryStringParam:message=1</URL>
</MenuItem>
<MenuItem>
Name>Message Two</Name>
<URL>queryStringParam:message=2</URL>
</MenuItem>
<SoftKeyItem>
<Name>Read</Name>
<URL>http://server/read.asp</URL>
</SoftkeyItem>
<SoftKeyItem>
<Name>Delete</Name>
<URL>http://server/delete.asp</URL>
</SoftkeyItem>
</CiscoIPPhoneMenu>

Example 2 shows how to use the QueryStringParam URI in a CiscoIPPhoneMenu object. The CiscoIPPhoneMenu object has two MenuItems with QueryStringParam URIs. If the user selects the MenuItem(s) with the numeric keypad, the cursor moves to that entry but nothing executes because the values are QueryStringParam URIs.

If the user presses either of the custom soft keys, the currently highlighted MenuItem URI value is appended to the soft key URL that was pressed and requested from the web server.

If you highlight the first MenuItem and press the Read soft key, the phone generates the following URL:

http://server//read.asp?message=1

Example 3 Selecting an Item with Numeric Keypad calls the URL

<CiscoIPPhoneMenu>
<Title>Message List</Title>
<Prompt>Two Messages</Prompt>
<MenuItem>
<Name>Messae One</Name>
<URL>http://server/messages.asp?message=1</URL>
</MenuItem>
<MenuItem>
<Name>Messae Two</Name>
<URL>http://server/messages.asp?message=2</URL>
</MenuItem>
<SoftKeyItem>
<Name>Read</Name>
<URL>QueryStringParam:action=read</URL>
</SoftKeyItem>
<SoftKeyItem>
<Name>Delete</Name>
<URL>QueryStringParam:action=delete</URL>
</SoftKeyItem>
</CiscoIPPhoneMenu>

The Cisco IP Phones allow you to implement the QueryStringParam URI in either manner. However, Example 3 is not as efficient as Example 2. Choose the best way to perform the action based on your applications needs.

Example 3 does have a slight advantage in that if the user selects an item with the numeric keypad, the URL is called. This would allow you to invoke some default behavior such as to read the message in the example. By highlighting the first message and pressing the Read soft key, the phone creates the following URL:

http://server/messages.asp?message=1&action=read

Using the QueryStringParam URI reduces the size of the XML objects that you generate by not having to repeat redundant portions of a URL in every MenuItem.

URIs to Control RTP Streaming

It is possible to invoke RTP streaming via URIs in services. You can instruct the phone to transmit or receive an RTP stream with the following specifications.

• RTPRx

• RTPTx

• RTPMRx

• RTPMTx

The supported format of the RTP stream follows:

•The codec is G.711 mu-Law.

•The packet size is 20 ms.

RTPRx

The RTPRx URI instructs the phone to receive a Unicast RTP stream or to stop receiving Unicast or Multicast RTP streams.

URI Formats:

RTPRx:i:p
RTPRx:Stop

Where

i is the IP Address from which the stream is coming

p is the TCP port on which to receive the RTP stream. This must be an even port number within the decimal range of 20480 to 32768. If no port is specified, the phone chooses a port and returns it when initiated by a push request.

Stop is the parameter that will stop any active RTP stream from being received on channel one.

RTPTx

The RTPTx URI is used to instruct the phone to transmit a Unicast RTP stream or to stop transmitting Unicast or Multicast RTP streams.

URI Formats:

RTPTx:i:p
RTPTx:Stop

Where

i is the IP Address to transmit an RTP stream to.

p is the TCP port on which to transmit the RTP stream. This must be an even port number within the decimal range of 20480 to 32768.

Stop is the parameter that will stop any active RTP stream from being transmitted on channel one.

RTPMRx

The RTPMRx URI instructs the phone to receive a Multicast RTP

URI Format:

RTPMRx:i:p

Where

i is the Multicast IP Address from which to receive an RTP stream.

p is the Multicast TCP port from which to receive the RTP stream. This must be an even port number within the decimal range of 20480 to 32768.

RTPMTx

The RTPMTx URI instructs the phone to transmit a Multicast RTP stream.

URI Formats:

RTPTx:i:p

Where

i is the Multicast IP Address to transmit an RTP stream to.

p is the Multicast TCP port on which to transmit the RTP stream. This must be an even port number within the decimal range of 20480 to 32768.

Miscellaneous URIs

This section describes the following miscellaneous URIs:

• Init

• Dial

• EditDial

• Play

Init

The Init URI allows an application to initialize a feature or data with the argument that is passed with the URI.

URI Format:

Init:o

Where

o is the Object name.

Valid object name:

CallHistory—When the phone encounters an Init:CallHistory URI, it clears the internal call history logs that are stored in the phone. This initializes Missed Calls, Received Calls, and Placed Calls.

Dial

The Dial URI initiates a new call to a specified number. The Dial URI invokes when it is contained in a menu item, the menu item is highlighted, and the device is taken off hook.

Activate the Dial URI by one of the following:

•Line button

•Speaker button

•Headset button

•Handset hook switch

•Normal menu item

•Soft key item selection

URI Format:

Dial:n

Where

n is the number dialed (such as Dial:1000).

EditDial

The EditDial URI initiates a new call to a specified number. The EditDial URI invokes when it is contained in a menu item, the menu item is highlighted, and the device is taken off hook.

Activate the EditDial URI by one of the following:

•Line button

•Speaker button

•Headset button

•Handset hook switch

•Normal menu item

•Soft key item selection

URI Format:

EditDial:n

Where

n is the number dialed (such as EditDial:1000).

Play

The Play URI downloads an audio file from the TFTP server and plays through the phone speaker. This is the same mechanism that is used to play ring files. The format of the files is the same. You could use the Play URI to play files that are in the Ringlist.xml or those that are not.

If you want to achieve a unique audible notification, use a file that is not available from the Ringlist.xml.

URI Format:

Play:f

Where

f is the filename of a raw audio file in the TFTP path (such as Play:Classic2.raw).

Cisco IP Services Software Development Kit (SDK)

The Cisco IP Services Software Development Kit (SDK) contains everything that is needed to create XML applications, including necessary documentation and sample applications.

The following list contains the components included in the SDK:

•Documentation

–Cisco IP Phone Services Application Development Notes (this document) in Adobe .pdf format

–Cisco URL Proxy Guide in rich text format

–Cisco LDAP Programming Guide in Microsoft Word format

–Cisco CIP Image Release Notes in Microsoft Word format

•Development Tools

–Cip.8bi—Photoshop plug-in that allows .cip extensions to be viewed and saved.

–Cip2Gif.exe—DOS-based program that converts .cip files to .gif.

–Gif2Cip.exe—DOS-based program that converts .gif files to .cip.

–ImageViewer.exe—Windows application that displays .cip graphic files.

–Cisco URL Proxy—Proxy server that is needed to use the sample services (automatically installed).

–Cisco LDAP Search—Service that is installed to do LDAP searches (automatically installed).

•Sample Services

–IIS

•Calendar—A graphical calendar

•LDAP—www interface for Cisco LDAP Search

•Speed Dials

•Real-time Stock Ticker—Stock quote

•Stock Chart—Stock graphic that charts a stock symbol

•Yellow pages

•Measurement conversions

•Weather forecast

•Airline flight information

•Postal information

•Foreign currency exchange

•World Clock

–Windows Scripting (WSH)

•Cip—A command line windows scripting graphic conversion example using ActiveX.

Sample Services Requirements

The following list contains the items that are required for the sample services to work properly:

•Cisco IP 7940/7960 IP Phone

•Cisco CallManager

•Microsoft IIS 4.0 or higher (for sample services)

•Windows Scripting (for WSH example code)

The setup program installs a CiscoServices web project to c:\CiscoIpServices directory. The sample services get copied to the c:\CiscoIpServices\Services subdirectory, and IIS and WSH example codes are provided. The web server already senses these services; you need no further administration. You can view or edit all the source code with any text editor. The c:\CiscoIpServices\Documentation directory provides further documentation. Find tools to help develop services in c:\CiscoIpServices\Tools.

HTTP Client Requests

The following procedure designates how HTTP client requests are handled:

•The Cisco IP Phone HTTP client performs an HTTP GET for a specified URL.

•The HTPP server processes request and returns an XML object or plain text.

•The phone processes the supported HTTP headers.

•The phone parses the XML object if ContentType is text/xml.

•The phone presents data and options to the user per the server response.

HTTP Header Settings

The following list provides definitions for HTTP header elements for Cisco IP Phone services:

•"Refresh" (Time in Seconds, URL)

–If no time is set or it is zero, the refresh gets set to manual.

–If no URL is set, the current URL gets used.

See "HTTP Refresh Setting" for details.

•"ContentType" — The ContentType notifies the phone of the MIME type that was sent. See "MIME Type and Other HTTP Headers".

•"Expires" — Expires sets the Date/Time in GMT when the page is to expire.

Pages that have expired before being loaded do not get added to the URL stack in the phone. The phone does not cache content. See "Content Expiration Header Setting" for more information.

HTTP Refresh Setting

The HTTP headers that are sent with any page from an HTTP server can include a Refresh setting. This setting comprises two parameters: a time in seconds and a URL. These two parameters direct the recipient to wait the time given in the seconds parameter and then get the data to which the URL points.

The Cisco IP Phone HTTP client properly supports this setting, which gives a great deal of power to service developers. It means that a new page can replace any XML object that displays after a fixed time.

Figure 9 shows a good example of how to use the refresh setting. This sample page shows the current value of Cisco stock to the user.

1. A splash screen that displays the Yahoo logo.

2. After a very short time, it displays the numeric Cisco stock parameters.

3. Finally, it shows a graph of Cisco intraday stock performance. The display then repeatedly cycles between the final two views.

Figure 9 Refresh Display Sample

Refreshing the display can occur without user intervention, as the display automatically cycles if a timer parameter is specified. However, on any given screen, the user can force an immediate reload by pressing the Update soft key. Also, if a timer parameter of 0 was sent in the header, the page never automatically reloads. In this case, the display will move to the next page only when the Update soft key is pressed. If no refresh URL is specified, the current page gets reloaded.

MIME Type and Other HTTP Headers

Although delivering pages with the proper MIME type and other formatting items is not difficult, it requires moderately indepth knowledge of your web server. The following code excerpt, written in JavaScript and used with Microsoft IIS and ASP, sets these values in a few lines:

<%@ Language=JavaScript %>
<%
Response.AddHeader( "Refresh",
"3; url=http://services.cisco.com/s/q.asp");
Response.ContentType = "text/xml";
//
// Additional page content here
//
%>

Usually, you can set the MIME type for pages in any web server by simply performing an association to the .xml file extension. Your web server documentation should explain how to accomplish this. This action allows you to serve static pages without the need for writing script.

If you want to deliver dynamic content using the other supported HTTP headers, you will need to understand how to generate the HTTP headers using the desired programming language and have common gateway interface (CGI) or script access on the target web server.

Audio Clips

It is possible to serve audio clips to the phone from a web server using the "audio/basic" MIME type setting. When this MIME type is used, the body of the response should contain raw audio data in the same format that is used for custom Cisco IP Phone rings. Refer to the chapter on "Custom Phone Rings" in the Cisco CallManager System Guide (also available in the online help).

Note The audio file should not be longer than 5 seconds in length.

Use the following ASP sample script to set the MIME type and to serve the file that is specified in the #include command:

<%@ Language=JavaScript%>
<%
Response.ContentType = "audio/basic";
%><% Response.End();%>

The advantage of using script to generate the MIME header when playing a sound is that you may also include a refresh header to take the phone to a subsequent URL. Usually, you can set the MIME type for pages in any web server by simply performing an association to the .xml or .raw file extension. Your web server documentation should explain how to accomplish this. This action allows you to serve static pages without the need for writing script.

Content Expiration Header Setting

The expiration header can control what URLs are added to the phone URL history. This behavior differs slightly from traditional web browsers but is implemented to perform the same function. Disable the back button functionality to avoid calling a URL twice.

This functionality allows you to make the content of any page that is sent to the phone expire. When a user presses the Exit soft key, the user goes back to the last URL that did not expire when it was loaded. This differs from traditional browsers by not considering the current freshness of the data but the freshness of the data when the URL was requested. This requires you to have a page expire when it is first loaded and to not set a time and date in the future.

The following example shows how to have content on IIS expire using Active Server Page (ASP):

<%@ Language=JavaScript %>
<%
Response.ContentType = "text/xml";
Response.Expires = -1;
%>

The "Expires" property specifies the number of minutes to wait for the content to expire. Setting this value to -1 subtracts 1 minute from the request time and returns a date and time that have already passed.

IP Phone Service Administration and Subscription

Cisco CallManager administrators maintain the list of services to which users can subscribe. Add and administer Cisco IP Phone services through Cisco CallManager Administration:

•To access phone service administration, open Cisco CallManager Administration and choose Feature > Cisco IP Phone Services.

•Phone services can have any number of parameters associated with them.

•You can specify phone service parameters as optional or required, depending on how the phone service application defines them.

•Users can subscribe to any service configured in their cluster.

•Service subscriptions currently occur on a device basis.

A URL constitutes the core of each service. When a service is chosen from the menu, the URL is requested via HTTP, and a server somewhere provides the content. The Service URL field shows this URL entry. For the services to be available, the phones in the Cisco CallManager cluster must have network connectivity to the server.

For example:

http://<servername>/ccmuser/sample/sample.asp

Where

<servername> designates a fully qualified domain name or an IP address.

Adding a Phone Service

Figure 10 shows the pane that the administrator uses to add new services to the system:

•To access this pane in Cisco CallManager Administration, choose Feature > Cisco IP Phone Services.

•You can insert, update, or delete a service definition.

•After a service is inserted, you can insert, update, or delete service parameter definitions.

•When you delete a Cisco IP Phone subscription, Cisco CallManager removes all service information, user subscriptions, and user subscription data from the database.

•The Update Subscriptions button rebuilds all user subscriptions if the service has been modified after subscriptions exist.

Caution Do not put Cisco IP Phone services on any Cisco CallManager server at your site or any server associated with Cisco CallManager, such as the TFTP server or directory database publisher server. This precaution eliminates the possibility of errors in a Cisco IP Phone Service application having an impact on Cisco CallManager performance or interrupting call-processing services.

Figure 10 Adding a New Service in Cisco CallManager Administration

Defining IP Phone Service Parameters in Cisco CallManager Administration

Each service can have a list of parameters. You can use these parameters, which are appended to the URL when they are sent to the server, to personalize a service for an individual user. Examples of parameters include stock ticker symbols, city names, or user IDs. The service provider defines the semantics of a parameter. The Cisco IP Phone Service Parameter Configuration pane in Cisco CallManager Administration contains the following fields:

Field

Description

Parameter Name

This field provides the exact query string parameter to use when the subscription URL is built.

Parameter Display Name

This field designates the descriptive parameter name to display to the user on the user preferences page.

Default Value

This field designates the default value for the parameter. This value displays to the user when user is being subscribed to a service for the first time.

Parameter is Required

Check the Parameter is Required check box if the user must enter data for this parameter before the subscription can be saved.

Parameter is a Password (mask contents)

Check this check box if the parameter is a password. The system will mask the contents.

Parameter Description

While subscribing to the service, the user can click on a link to view the text that is entered here. The parameter description should provide information or examples to help users input the correct value for the parameter.

Tip If you change the service URL, remove a Cisco IP Phone service parameter, or change the Parameter Name of a phone service parameter for a phone service to which users are already subscribed, be sure to click Update Subscriptions to update all currently subscribed users with the changes. If you do not do so, users must resubscribe to the service to rebuild the URL correctly.

Figure 11 displays an example Cisco IP Phone Service Parameter Configuration pane in Cisco CallManager Administration.

Figure 11 Defining Service Parameters in Cisco CallManager Administration

User Service Subscription

User service subscriptions get configured with the CCMUser web site after the user has logged in and chosen a device.

The end user has a single list of services that are attached to an individual phone. The user configures this list of services via the user pages, which are also used to set speed-dial numbers and call-forwarding options. These password-protected pages get authenticated via the LDAP directory.

Figures 12, 13, and 14 show user subscription panes for administering personal services. Users can insert or remove services.

Users use these user configuration panes to assign values to the service parameters, allowing for personalization:

•The user can customize the name of the service when it displays on the services list.

•The user can enter any service parameters that are available for the chosen service.

•The user can review the description of each parameter.

•After all the required fields are set, the user can click Subscribe.

•A custom URL gets built and stored in the database for this subscription.

•The service then appears on the device services list.

Figure 12 Cisco CallManager User Subscription Screen

Figure 13 Personalizing a User Subscription

Figure 14 Personalizing a User Subscription Completed

Troubleshooting Cisco IP Phone Service Applications

The following tips apply to troubleshooting Cisco IP Phone service applications:

•Microsoft Internet Explorer 5 or higher can display the XML source with its default style sheet.

•Understand that standard IP troubleshooting techniques are important for HTTP errors.

•Externally verify name resolution (Phone has DNS set).

•If DNS is suspected, use IP addresses in URLs.

•Browse the URL in question with IE5 or download and verify with Netscape.

Use a logged telnet session to verify that the desired HTTP headers are returned (Telnet to the server on port 80; then, enter get /path/page).

XML Parsing Errors

The following tips apply to troubleshooting XML parsing errors in Cisco IP Phone services applications:

•Verify the object tags (the object tags are case-sensitive).

•Verify that "&" and the other four special characters are used per the restrictions while inside the XML objects. See "Mandatory Escape Sequences" for more information.

Error Messages

The following error messages may appear on the prompt line of the Cisco IP Phone display.

•XML Error[4] = XML Parser error (Invalid Object)

•HTTP Error[8] = Unknown HTTP Error

•HTTP Error[10] = HTTP Connection Failed

Refer to the Cisco IP Phone Administration Guide for Cisco CallManager for more information.

DeviceListX Report

The DeviceListX Report provides a list of the services-capable devices along with basic information about the device to identify or classify the devices based on specific criteria. The report also includes the current device status and the IP address information that is obtained from the Real-time Information Service.

When a third-party developer initiates an HTTP GET request for the DeviceListX.asp report page, the system retrieves the following information about phones that are registered to a Cisco CallManager server from the database.

•Device Type

•Device Name

•Device Description

•Calling Search Space

•Device Pool

•IP Address

•Real-Time Information

The completed list of data gets formatted into a simple XML object and gets returned in the HTTP Response to the developer.

Benefits

DeviceListX provides access to critical real-time data that was previously unavailable to third-party developers. In particular, the ability to list currently registered devices along with their IP address allows developers to easily build push, broadcast, and CTI-type applications.

Restrictions

Only users with administrative privileges to the Cisco CallManager Administration program can access the report.

Note To minimize processing overhead on the Cisco CallManager server, access to the DeviceListX report gets rate-limited to once per minute. Any attempt to pull the report more frequently will fail. In practice, the developer application should pull and cache the DeviceListX report, refreshing only as often as required, typically every few hours or daily.

Integration Considerations and Interoperability

The interface allows HTTP 1.1 or HTTP 1.0 GET requests for the report. The report returns data that is encapsulated by using XML version 1.0.

Performance and Scalability

You can run this report on the largest supported Cisco CallManager cluster size for the targeted release without impacting core features, such as delaying dial tone. On multi-server Cisco CallManager clusters, the report can access only from the publisher server. In large clusters where the publisher is not a Cisco CallManager server, no possibility exists of impacting the system performance as perceived by a user.

Because this report is not intended for use during real time, this interface should provide a mechanism for developers to poll for the data on a daily or hourly basis. Give consideration to the frequency of polling and the time of day to prevent unnecessary burden on the system during peak usage times.

Security

This report, which is within the Cisco CallManager Administration program, inherits its security from that web site. Therefore, no security issues directly relate to this report. If the Cisco CallManager Administration web changes how it implements security with additions, such as SSL, this report benefits from that enhancement.

Related Features and Technologies

DeviceListX acts as an independent interface, which is a real-time complement to the AVVID XML-Layer Database API (AXL), where AXL provides access to static, persisted data, and DeviceListX provides access to dynamic, volatile information.

Supported Platforms

For the DeviceListX.asp page to function requires Cisco CallManager Administration reporting infrastructure. The following releases support DeviceListX.asp:

•Cisco CallManager Release 3.2(3)SPB

•Cisco CallManager Release 3.3(3)

Prerequisites

You can access this feature when devicelistX.asp resides in the C:\ciscoWebs\Admin\reports directory of the Cisco CallManager publisher server.

Message and Interface Definitions

Use the following URL to access the report via HTTP:

http://x.x.x.x/CCMAdmin/reports/devicelistx.asp

where

x.x.x.x can either be the IP address or hostname of the Cisco CallManager system that contains the report.

DeviceList XML Object

Third-party applications that reside elsewhere on the network commonly use the interface. The application makes an HTTP request for the report and gets a response that contains a DeviceList XML object. The XML object follows:

<?xml version="1.0" encoding="iso-8859-1"?>

<DeviceList>

<Device t="" n="" d="" c="" p="" i="" s="" />

</DeviceList>

Attributes

Attribute Name

Field Name

Description

t

Device Type

Numeric enumeration value that is specified in the database.

n

Device Name

String value that specifies the device name.

d

Device Description

String value that is specified in the database.

c

Device Calling Search Space

String value that is specified in the database.

p

Device Pool

String value that is specified in the database.

i

Device IP Address

Last known IP address as reported by the Real-time Information Service

"" = No known IP address

"x.x.x.x" = Last known IP address

s

Device Status

Numeric enumeration for the current device status as reported by the Real-time Information Service

"" = Device not found

"1" = Device registered

"2" = Device found but not currently registered

Example 4 DeviceList Object with Data

<?xml version="1" encoding="iso-8859-1"?>
<DeviceList>
<Device t="35" n="SEP000123456789" d="Auto 2010" c="" p="Default" i="10.1.1.1" s="1"/>
</DeviceList>
Troubleshooting DeviceListX Reports

Error Codes

The error codes that are specific to this report interface follow.
Error Message    1001 Too many simultaneous requests for Device List. Please wait at least 60 seconds and try again.
Explanation    When two or more clients attempt to get the list at the same time, or if the list is long, overlapping requests can result (first request is processing when the second request attempts processing).
Recommended Action    Request information only as often as necessary.

Note Cisco recommends that you wait longer than 60 seconds between requests.

Error Message    1002 Too many consecutive requests for Device List. Please wait at least 60 seconds and try again.
Explanation    Because the system is busy, it cannot process a Device List.
Recommended Action    Request information only as often as necessary. Because the real-time status of every device gets checked, Device List represents a CPU-intensive process.

Note Cisco recommends that you wait longer than 60 seconds between requests.

Determining Problems With the Interface

Use the following procedure to determine whether a problem exists with the interface and determine the root cause of the problem.

Step 1 Check the Windows NT Event Logs for error messages pertaining to the IIS server and the SQL server.

Start > Programs > Administrative Tools > Event Viewer

Step 2 Check for error messages or successful completion of a request in the IIS log files, which are typically located in

C:\WINNT\System32\LogFiles\W3SVC1

The date of the log provides part of the log name. All times in the log files specify GMT for noted events. The IIS logs appear in chronological order and can easily be searched by specific query event.

Step 3 Use a web browser, such as IE, to request the URL of the devicelistx.asp web page. A successful request yields a well-formed XML object of all the device information.

Step 4 Use a Sniffer trace to view the HTTP GET request and response transaction between the third-party application and the report.

Step 5 If you need further assistance, see "Obtaining Technical Assistance" for more information.

Related Documentation

The following documents provide further information:

•Cisco CallManager Administration Guide (also available in the online help). Refer to the chapter on configuring Cisco IP Phone services.

•Cisco CallManager System Guide (also available in the online help).

•Cisco IP Phone 7960/7940 Quick Start Guide
Provides instructions for users on subscribing to phone services.

•Cisco IP Phone Administration Guide for Cisco CallManager
Provides administration information for Cisco IP Phones.

•CiscoURLProxy ActiveX Component
Provided with the Cisco IP Services SDK.

•LDAP Search COM Server Programming Guide
Provided with the Cisco IP Services SDK.

•CipImage Release Notes
Provided with the Cisco IP Services SDK.

Obtaining Documentation

Cisco provides several ways to obtain documentation, technical assistance, and other technical resources. These sections explain how to obtain technical information from Cisco Systems.

Cisco.com

You can access the most current Cisco documentation on the World Wide Web at this URL:

http://www.cisco.com/univercd/home/home.htm

You can access the Cisco website at this URL:

http://www.cisco.com

International Cisco websites can be accessed from this URL:

http://www.cisco.com/public/countries_languages.shtml

Documentation CD-ROM

Cisco documentation and additional literature are available in a Cisco Documentation CD-ROM package, which may have shipped with your product. The Documentation CD-ROM is updated regularly and may be more current than printed documentation. The CD-ROM package is available as a single unit or through an annual or quarterly subscription.

Registered Cisco.com users can order a single Documentation CD-ROM (product number DOC-CONDOCCD=) through the Cisco Ordering tool:

http://www.cisco.com/en/US/partner/ordering/ordering_place_order_ordering_tool_launch.html

All users can order monthly or quarterly subscriptions through the online Subscription Store:

http://www.cisco.com/go/subscription

Ordering Documentation

You can find instructions for ordering documentation at this URL:

http://www.cisco.com/univercd/cc/td/doc/es_inpck/pdi.htm

You can order Cisco documentation in these ways:

•Registered Cisco.com users (Cisco direct customers) can order Cisco product documentation from the Networking Products MarketPlace:

http://www.cisco.com/en/US/partner/ordering/index.shtml

•Nonregistered Cisco.com users can order documentation through a local account representative by calling Cisco Systems Corporate Headquarters (California, U.S.A.) at 408 526-7208 or, elsewhere in North America, by calling 800 553-NETS (6387).

Documentation Feedback

You can submit comments electronically on Cisco.com. On the Cisco Documentation home page, click Feedback at the top of the page.

You can e-mail your comments to bug-doc@cisco.com.

You can submit comments by using the response card (if present) behind the front cover of your document or by writing to the following address:

Cisco Systems
Attn: Customer Document Ordering
170 West Tasman Drive
San Jose, CA 95134-9883

We appreciate your comments.

Obtaining Technical Assistance

Cisco provides Cisco.com, which includes the Cisco Technical Assistance Center (TAC) website, as a starting point for all technical assistance. Customers and partners can obtain online documentation, troubleshooting tips, and sample configurations from the Cisco TAC website. Cisco.com registered users have complete access to the technical support resources on the Cisco TAC website, including TAC tools and utilities.

Cisco.com

Cisco.com offers a suite of interactive, networked services that let you access Cisco information, networking solutions, services, programs, and resources at any time, from anywhere in the world.

Cisco.com provides a broad range of features and services to help you with these tasks:

•Streamline business processes and improve productivity

•Resolve technical issues with online support

•Download and test software packages

•Order Cisco learning materials and merchandise

•Register for online skill assessment, training, and certification programs

To obtain customized information and service, you can self-register on Cisco.com at this URL:

http://tools.cisco.com/RPF/register/register.do

Developer Support

The Developer Support Program provides formalized support for Cisco Systems interfaces to enable developers, customers, and partners in the Cisco Service Provider solutions Ecosystem and Cisco AVVID Partner programs to accelerate their delivery of compatible solutions.

The Developer Support Engineers are an extension of the product technology engineering teams. They have direct access to the resources necessary to provide expert support in a timely manner.

For additional information on this program, refer to the Developer Support Program Web Site at
www.cisco.com/go/developer support/.

Developers using the Cisco IP Phones Services Application Development are encouraged to join the Cisco Developer Support Program. This new program provides a consistent level of support while leveraging Cisco interfaces in development projects.

Note Cisco Technical Assistance Center (TAC) support does not include Cisco IP Phones Services Application Development support and is limited to Cisco AVVID installation/configuration and Cisco-developed applications. For more information about the Developer Support Program, please contact Cisco at developer-support@cisco.com.

Technical Assistance Center

The Cisco TAC is available to all customers who need technical assistance with a Cisco product, technology, or solution. Two types of support are available: the Cisco TAC website and the Cisco TAC Escalation Center. The type of support that you choose depends on the priority of the problem and the conditions stated in service contracts, when applicable.

We categorize Cisco TAC inquiries according to urgency:

•Priority level 4 (P4)—You need information or assistance concerning Cisco product capabilities, product installation, or basic product configuration. There is little or no impact to your business operations.

•Priority level 3 (P3)—Operational performance of the network is impaired, but most business operations remain functional. You and Cisco are willing to commit resources during normal business hours to restore service to satisfactory levels.

•Priority level 2 (P2)—Operation of an existing network is severely degraded, or significant aspects of your business operations are negatively impacted by inadequate performance of Cisco products. You and Cisco will commit full-time resources during normal business hours to resolve the situation.

•Priority level 1 (P1)—An existing network is "down," or there is a critical impact to your business operations. You and Cisco will commit all necessary resources around the clock to resolve the situation.

Cisco TAC Website

The Cisco TAC website provides online documents and tools to help troubleshoot and resolve technical issues with Cisco products and technologies. To access the Cisco TAC website, go to this URL:

http://www.cisco.com/tac

All customers, partners, and resellers who have a valid Cisco service contract have complete access to the technical support resources on the Cisco TAC website. Some services on the Cisco TAC website require a Cisco.com login ID and password. If you have a valid service contract but do not have a login ID or password, go to this URL to register:

http://tools.cisco.com/RPF/register/register.do

If you are a Cisco.com registered user, and you cannot resolve your technical issues by using the Cisco TAC website, you can open a case online at this URL:

http://www.cisco.com/tac/caseopen

If you have Internet access, we recommend that you open P3 and P4 cases online so that you can fully describe the situation and attach any necessary files.

Cisco TAC Escalation Center

The Cisco TAC Escalation Center addresses priority level 1 or priority level 2 issues. These classifications are assigned when severe network degradation significantly impacts business operations. When you contact the TAC Escalation Center with a P1 or P2 problem, a Cisco TAC engineer automatically opens a case.

To obtain a directory of toll-free Cisco TAC telephone numbers for your country, go to this URL:

http://www.cisco.com/warp/public/687/Directory/DirTAC.shtml

Before calling, please check with your network operations center to determine the Cisco support services to which your company is entitled: for example, SMARTnet, SMARTnet Onsite, or Network Supported Accounts (NSA). When you call the center, please have available your service agreement number and your product serial number.

Obtaining Additional Publications and Information

Information about Cisco products, technologies, and network solutions is available from various online and printed sources.

•The Cisco Product Catalog describes the networking products offered by Cisco Systems, as well as ordering and customer support services. Access the Cisco Product Catalog at this URL:

http://www.cisco.com/en/US/products/products_catalog_links_launch.html

•Cisco Press publishes a wide range of networking publications. Cisco suggests these titles for new and experienced users: Internetworking Terms and Acronyms Dictionary, Internetworking Technology Handbook, Internetworking Troubleshooting Guide, and the Internetworking Design Guide. For current Cisco Press titles and other information, go to Cisco Press online at this URL:

http://www.ciscopress.com

•Packet magazine is the Cisco quarterly publication that provides the latest networking trends, technology breakthroughs, and Cisco products and solutions to help industry professionals get the most from their networking investment. Included are networking deployment and troubleshooting tips, configuration examples, customer case studies, tutorials and training, certification information, and links to numerous in-depth online resources. You can access Packet magazine at this URL:

http://www.cisco.com/go/packet

•iQ Magazine is the Cisco bimonthly publication that delivers the latest information about Internet business strategies for executives. You can access iQ Magazine at this URL:

http://www.cisco.com/go/iqmagazine

•Internet Protocol Journal is a quarterly journal published by Cisco Systems for engineering professionals involved in designing, developing, and operating public and private internets and intranets. You can access the Internet Protocol Journal at this URL:

http://www.cisco.com/en/US/about/ac123/ac147/about_cisco_the_internet_protocol_journal.html

•Training—Cisco offers world-class networking training. Current offerings in network training are listed at this URL:

http://www.cisco.com/en/US/learning/le31/learning_recommended_training_list.html

This document is to be used in conjunction with the documents listed in the "Related Documentation" section.
CCIP, CCSP, the Cisco Arrow logo, the Cisco Powered Network mark, Cisco Unity, Follow Me Browsing, FormShare, and StackWise are trademarks of Cisco Systems, Inc.; Changing the Way We Work, Live, Play, and Learn, and iQuick Study are service marks of Cisco Systems, Inc.; and Aironet, ASIST, BPX, Catalyst, CCDA, CCDP, CCIE, CCNA, CCNP, Cisco, the Cisco Certified Internetwork Expert logo, Cisco IOS, the Cisco IOS logo, Cisco Press, Cisco Systems, Cisco Systems Capital, the Cisco Systems logo, Empowering the Internet Generation, Enterprise/Solver, EtherChannel, EtherSwitch, Fast Step, GigaStack, Internet Quotient, IOS, IP/TV, iQ Expertise, the iQ logo, iQ Net Readiness Scorecard, LightStream, MGX, MICA, the Networkers logo, Networking Academy, Network Registrar, Packet, PIX, Post-Routing, Pre-Routing, RateMUX, Registrar, ScriptShare, SlideCast, SMARTnet, StrataView Plus, Stratm, SwitchProbe, TeleRouter, The Fastest Way to Increase Your Internet Quotient, TransPath, and VCO are registered trademarks of Cisco Systems, Inc. and/or its affiliates in the U.S. and certain other countries.
All other trademarks mentioned in this document or Web site are the property of their respective owners. The use of the word partner does not imply a partnership relationship between Cisco and any other company. (0304R)
Copyright � 2003, Cisco Systems, Inc.
All rights reserved.

InputFlag	Description
A	Plain ASCII text. Use the DTMF keypad to enter text consisting of uppercase and lowercase letters, numbers, and special characters.
T	Telephone number. Enter only DTMF digits for this field. The acceptable input includes numbers, #, and *.
N	Numeric. Enter only numbers as the only acceptable input.
E	Equation. The acceptable input includes numbers and special math symbols.
U	Uppercase. Enter only uppercase letters as the only acceptable input.
L	Lowercase. Enter only lowercase letters as the only acceptable input.
P	Password field. Individual characters display as they are entered using the standard keypad-repeat entry mode. As soon as each character is accepted, the system converts it to an asterisk, allowing for privacy of the entered value. Note P specifies the only `InputFlag` that works as a modifier. For example, specify a value of "AP" in the `InputFlag` field to use plain ASCII as the input type and to mask the input as a password using an asterisk (*).

Soft Key Name	Description
Select	Initiates an action on a marked item from a menu, directory, or form. (The action can be checking or unchecking the item, or presenting a new page.) Marked items are highlighted on the IP Phone.
OK	Commits any value changes and presents a new page to users. (The new page is often the page users used to access the current page.) Also used to show agreement to information contained in a message.
Cancel	Skips committing value changes and presents a new page to users. (The new page is often the page that allows users to access the current page.)
Exit	Exits out of a menu on your phone LCD screen
Next	Presents the next item in a sequence of items, which can be pages, directory entries, form entries, and so on.
Back	Goes back to a parent page of a lower level page. (Backs up in a service menu hierarchy.) Back can also be used to present the previous item in a sequence of items. Items can be pages, directory entries, form entries, and so on.
Update	Reloads and updates the current page
Dial	Dials the phone number of a selected entry
EditDial	Allows users to insert access codes or other necessary items before dialing.
Submit	Indicates that the form is complete and that the resulting URL should be requested via HTTP
<<	Backspaces within a field

Object	Definition
`CiscoIPPhoneMenu`	`<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>` `<SoftKeyItem>` `<Name>Name of soft key</Name>` `<URL>URL or URI of soft key</URL>` `<Position>Position information of the soft key</Position>` `</SoftKeyItem>` `</CiscoIPPhoneMenu>`
`CiscoIPPhoneText`	`<CiscoIPPhoneText>` `<Title>Title text goes here</Title>` `<Prompt>The prompt text goes here</Prompt>` `<Text>Text to display as the message body goes here</Text>` `<SoftKeyItem>` `<Name>Name of soft key</Name>` `<URL>URL or URI of soft key</URL>` `<Position>Position information of the soft key</Position>` `<SoftKeyItem>` `</CiscoIPPhoneText>`
`CiscoIPPhoneInput`	`<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 input field to display</DisplayName>` `<QueryStringParam>The parameter to be added to the target URL</QueryStringParam>` `<DefaultValue>Value</DefaultValue>` `<InputFlags>The flag specifying the type of allowable input</InputFlags>` `</InputItem>` `<SoftKeyItem>` `<Name>Name of soft key</Name>` `<URL>URL or URI of soft key</URL>` `<Position>Position of information of the soft key</Position>` `</SoftKeyItem>` `</CiscoIPPhoneInput>`
`CiscoIPPhoneDirectory`	`<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>` `</DirectoryEntry>` `<SoftKeyItem>` `<Name>Name of soft key</Name>` `<URL>URL or URI of soft key</URL>` `<Position>Position information of the soft key</Position>` `</SoftKeyItem>` `</CiscoIPPhoneDirectory>`
`CiscoIPPhoneImage`	`<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>` `<Depth>Number of bits per pixel</Depth>` `<Data>Packed Pixel Data</Data>` `<SoftKeyItem>` `<Name>Name of soft key</Name>` `<URL>URL of soft key</URL>` `<Position>Numerical position of the soft key</Position>` `</SoftKeyItem>` `</CiscoIPPhoneImage>`
`CiscoIPPhoneGraphicMenu`	`<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>` `<SoftKeyItem>` `<Name>Name of soft key</Name>` `<URL>URL of soft key</URL>` `<Position>Numerical position of the soft key</Position>` `</SoftKeyItem>` `</CiscoIPPhoneGraphicMenu>`
`CiscoIPPhoneIconMenu`	`<CiscoIPPhoneIconMenu>` `<Title>Title text goes here</Title>` `<Prompt>Prompt text goes here</Prompt>` `<MenuItem>` `<IconIndex>Indicates what IconItem to display</IconIndex>` `<Name>The name of each menu item</Name>` `<URL>The URL associated with the menu item</URL>` `</MenuItem>` `<SoftKeyItem>` `<Name>Name of soft key</Name>` `<URL>URL or URI of soft key</URL>` `<Position>Position information of the soft key</Position>` `</SoftKeyItem>` `<IconItem>` `<Index>A unique index from 0 to 9</Index>` `<Height>Size information for the icon</Height>` `<Width>Size information for the icon</Width>` `<Depth>Number of bits per pixel</Depth>` `<Data>Packed Pixel Data</Data>` `</IconItem>` `</CiscoIPPhoneIconMenu>`
`CiscoIPPhoneExecute`	`<CiscoIPPhoneExecute>` `<ExecuteItem URL="The URL or URI to be executed"/>` `<CiscoIPPhoneExecute>`
`CiscoIPPhoneError`	`<CiscoIPPhoneError Number="x"/>`
`CiscoIPPhoneResponse`	`<CiscoIPPhoneResponse>` `<ResponseItem Status"the success or failure of the action"Data="the information associated with the request" URL="the URL or URI specified in the Execute object"/>` `<CiscoIPPhoneResponse>`

Character	Name	Escape Sequence
`&`	Ampersand	&
`"`	Quote	"
`'`	Apostrophe	'
`<`	Left angle bracket	<
`>`	Right angle bracket	>

Field	Description
Parameter Name	This field provides the exact query string parameter to use when the subscription URL is built.
Parameter Display Name	This field designates the descriptive parameter name to display to the user on the user preferences page.
Default Value	This field designates the default value for the parameter. This value displays to the user when user is being subscribed to a service for the first time.
Parameter is Required	Check the Parameter is Required check box if the user must enter data for this parameter before the subscription can be saved.
Parameter is a Password (mask contents)	Check this check box if the parameter is a password. The system will mask the contents.
Parameter Description	While subscribing to the service, the user can click on a link to view the text that is entered here. The parameter description should provide information or examples to help users input the correct value for the parameter.

Attribute Name	Field Name	Description
t	Device Type	Numeric enumeration value that is specified in the database.
n	Device Name	String value that specifies the device name.
d	Device Description	String value that is specified in the database.
c	Device Calling Search Space	String value that is specified in the database.
p	Device Pool	String value that is specified in the database.
i	Device IP Address	Last known IP address as reported by the Real-time Information Service "" = No known IP address "x.x.x.x" = Last known IP address
s	Device Status	Numeric enumeration for the current device status as reported by the Real-time Information Service "" = Device not found "1" = Device registered "2" = Device found but not currently registered