Cisco Unified IP Phone Services Application Development Notes Release 9.1(1) and Later
CiscoIPPhone XML Objects
Downloads: This chapterpdf (PDF - 1.89MB) The complete bookPDF (PDF - 3.55MB) | The complete bookePub (ePub - 834.0KB) | The complete bookMobi (Mobi - 1.53MB) | Feedback

CiscoIPPhone XML Objects

Contents

CiscoIPPhone XML Objects

Object Behavior

You can create interactive service applications when you understand the XML objects that are defined for Cisco Unified IP Phones and the behavior that each object generates.

When a phone loads an XML page, the phone does not have any concept of a service state. IP phones can use HTTP to load a page of content in many different places, starting when the user presses the Services button. Regardless of what causes the phone to load a page, the phone always behaves appropriately after it loads a page.

Appropriate behavior depends solely on the type of data that has been delivered in the page. The web server must deliver the XML pages with a MIME type of text/xml. However, the exact mechanism required varies according to the type of web server that you use and the server-side mechanism that you use to create your pages (for example, if you use static files, JavaScript, or CGI).

XML Object Support

The following sections describe the supported XML objects by phone model families. Before creating a service for a particular phone model, check to make sure that the XML object you want to use is supported.

Cisco Unified IP Phone 6900 Series XML Object Support

The following table shows the supported XML objects for the Cisco Unified IP Phone 6900 Series.


Note


Cisco Unified IP Phones 6901 and 6911 do not support XML objects.


Table 1 XML Objects Supported by Cisco Unified IP Phone Services SDK for Cisco Unified IP Phone 6900 Series

XML object

6901, 6911

6921, 6941, 6945, 6961

CiscoIPPhoneMenu

Not supported

Supported

CiscoIPPhoneText

Not supported

Supported

CiscoIPPhoneInput

Not supported

Supported

CiscoIPPhoneDirectory

Not supported

Supported

CiscoIPPhoneImage

Not supported

Not supported

(see note 1)

CiscoIPPhoneImageFile

Not supported

Not supported

(see note 1)

CiscoIPPhoneGraphicMenu

Not supported

Not supported

(see note 1)

CiscoIPPhoneGraphicFileMenu

Not supported

Not supported

(see note 1)

CiscoIPPhoneIconMenu

Not supported

Supported

(see note 2)

CiscoIPPhoneIconFileMenu

Not supported

Supported

CiscoIPPhoneStatus

Not supported

Not supported

CiscoIPPhoneStatusFile

Not supported

Not supported

CiscoIPPhoneExecute

Not supported

Supported

CiscoIPPhoneResponse

Not supported

Supported

CiscoIPPhoneError

Not supported

Supported


Note


  1. The Cisco Unified IP Phones 6921, 6941, 6945, and 6961 do not support CiscoIPPhoneGraphicFileMenu, CiscoIPPhoneGraphicMenu, CiscoIPPhoneImageFile, and CiscoIPPhoneImage because these phones use a monochrome LCD.
  2. The Cisco Unified IP Phones 6921, 6941, 6945, and 6961 do not support icons; therefore, all icons are ignored and do not display.

Cisco IP Phone 7800 Series XML Object Support

The following table shows the supported XML objects for the Cisco IP Phone 7800 Series.

Table 2 XML Objects Supported by Cisco Unified IP Phone Services SDK for Cisco IP Phone 7800 Series

XML object

7821, 7841, and 7861

CiscoIPPhoneMenu

Supported

CiscoIPPhoneText

Supported

CiscoIPPhoneInput

Supported

CiscoIPPhoneDirectory

Supported

CiscoIPPhoneImage

Not supported

CiscoIPPhoneImageFile

Not supported

CiscoIPPhoneGraphicMenu

Not supported

CiscoIPPhoneGraphicFileMenu

Not supported

CiscoIPPhoneIconMenu

Supported

CiscoIPPhoneIconFileMenu

Supported

CiscoIPPhoneStatus

Not supported

CiscoIPPhoneStatusFile

Not supported

CiscoIPPhoneExecute

Supported

CiscoIPPhoneResponse

Supported

CiscoIPPhoneError

Supported

Cisco Unified IP Phone 7900 Series, Cisco Unified Wireless IP Phone 7900 Series, and Cisco IP Communicator XML Object Support

The following table shows the supported XML objects for the Cisco Unified IP Phone 7900 Series, Cisco Unified Wireless IP Phone 7900 Series, and the Cisco IP Communicator.

Table 3 XML Objects Supported by Cisco Unified IP Phone Services SDK for Cisco Unified IP Phone 7900 Series, Cisco Unified Wireless IP Phone 7900 Series, and Cisco IP Communicator

XML object

7905G, 7906G, 7911G, 7912G, 7931G

7920

7921G, 7925G, 7925G-EX, 7926G

7937G

7940G, 7960G

7941G, 7941G-GE, 7942G, 7945G, 7961G, 7961G-GE, 7962G, 7965G, 7970G, 7971G-GE, 7975G, IP Communicator

CiscoIPPhoneMenu

Supported

Supported

Supported

Supported

Supported

Supported

CiscoIPPhoneText

Supported

Supported

Supported

Supported

Supported

Supported

CiscoIPPhoneInput

Supported

Supported

Supported

Supported

Supported

Supported

CiscoIPPhoneDirectory

Supported

Supported

Supported

Supported

Supported

Supported

CiscoIPPhoneImage

Not supported

Supported

(see note 1)

Supported

Supported

Supported

Supported

CiscoIPPhoneImageFile

Not supported

Not supported

Supported

Not supported

Not supported

Supported

CiscoIPPhoneGraphicMenu

Not supported

Supported

(see note 1)

Supported

Supported

Not supported

Supported

CiscoIPPhoneGraphicFileMenu

Not supported

Not supported

Supported

Not supported

Not supported

Supported

CiscoIPPhoneIconMenu

Supported

(see note 2)

Supported

Supported

Supported

Supported

Supported

CiscoIPPhoneIconFileMenu

Not supported

Not supported

Supported

Not supported

Not supported

Supported

(see note 3)

CiscoIPPhoneStatus

Not supported

Not supported

Not supported

Not supported

Supported

Supported

CiscoIPPhoneStatusFile

Not supported

Not supported

Not supported

Not supported

Not supported

Supported

(see note 3)

CiscoIPPhoneExecute

Supported

Supported

(see note 4)

Supported

Supported

Supported

Supported

CiscoIPPhoneResponse

Supported

Supported

Supported

Supported

Supported

Supported

CiscoIPPhoneError

Supported

Supported

Supported

Supported

Supported

Supported


Note


  1. The Cisco Unified IP Phone 7920 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 Cisco Unified IP Phones 7905G and 7912G do not support CIP images; therefore, all icons get ignored and do not display.
  3. The Cisco 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.
  4. The Cisco Unified IP Phone 7920 does not support Priority 1 when on a call.

Cisco Unified IP Phone 8800, 8900, and 9900 Series XML Object Support

The following table shows the supported XML objects for the Cisco Unified IP Phone 8800, 8900, and 9900 Series.

Table 4 XML Objects Supported by Cisco Unified IP Phone Services SDK for Cisco Unified IP Phone 8800, 8900, and 9900 Series

XML object

8831

8841, 8851, 8861

(see note 4)

8941, 8945

8961, 9951, 9971

CiscoIPPhoneMenu

Supported

Supported

Supported

Supported

CiscoIPPhoneText

Supported

Supported

Supported

Supported

CiscoIPPhoneInput

Supported

Supported

Supported

Supported

CiscoIPPhoneDirectory

Supported

Supported

Supported

Supported

CiscoIPPhoneImage

Not supported

Supported

Supported

Supported

CiscoIPPhoneImageFile

Not supported

Supported

Supported

(see note 1)

Supported

CiscoIPPhoneGraphicMenu

Not supported

Supported

Supported

Supported

CiscoIPPhoneGraphicFileMenu

Not supported

Supported

Supported

Supported

CiscoIPPhoneIconMenu

Supported

Supported

Supported

Supported

CiscoIPPhoneIconFileMenu

Not supported

Supported

Supported

(see note 2)

Supported

CiscoIPPhoneStatus

Not supported

Supported

Supported

(see note 3)

Supported

CiscoIPPhoneStatusFile

Not supported

Supported

Supported

(see note 3)

Supported

CiscoIPPhoneExecute

Supported

Supported

Supported

Supported

CiscoIPPhoneResponse

Supported

Supported

Supported

Supported

CiscoIPPhoneError

Supported

Supported

Supported

Supported


Note


  1. The Cisco Unified IP Phones 8941 and 8945 supports display image sizes and color depths: 498x289x24 color.
  2. The Cisco Unified IP Phones 8941 and 8945 do not support Enhanced Icon Menu.
  3. The Cisco Unified IP Phones 8941 and 8945 require firmware 9.3(1) or later.
  4. The Cisco IP Phones 8841, 8851, and 8861 require firmware 10.2(1) or later.

XML Object Definitions

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

CiscoIPPhoneMenu

A menu on the phone contains a list of text items, one per line. Users choose individual menu items using the same mechanisms that are used for built-in menus in the phone.

When a menu loads, the phone behaves 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 softkey 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) that are associated with the menu item.

Related References
Related Information

CiscoIPPhoneMenu 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


  • The Name field under the <MenuItem> supports a maximum of 64 characters. This field can also accept two carriage returns to allow the MenuItem name to span three lines on the display.
  • The Cisco Unified IP Phone 6900 Series do not display 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.

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. IP phones allow a maximum of 100 MenuItems. Each <MenuItem> includes a Name and an associated URL.

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 IP phone firmware controls all other pagination and word wrap issues.


Note


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


CiscoIPPhoneText 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>

Note


The Cisco Unified IP Phone 6900 Series do not display 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.


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 Unified Communications Manager 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.

CiscoIPPhoneInput

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

Figure 1. Sample user input display

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. You can also deliver plain text using HTTP. Pages 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: IP phones allow navigation to a specific line in a menu by pressing numeric DTMF keys. 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. A carefully written text service display can take advantage of this capability.

During text entry, the phones display softkeys to assist users with text entry. Users can navigate between fields with the vertical scroll button that is used to navigate menus.

CiscoIPPhoneInput 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>

Note


The Cisco Unified IP Phone 6900 Series do not display 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.


The Title and Prompt tags in the object define text that are used in the same way as the identical fields in the other CiscoIPPhone XML objects.

The URL tag defines 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 that are appended to it as a query string. The parameters include Name/Value pairs, one for each input item.


Note


CiscoIPPhoneInput objects do not use the HTTP POST method.


The InputItem tag defines each item in the list. The number of InputItems must not exceed five. Each input item includes a DisplayName, which is the prompt that is written to the display for that particular item. Each item also has a QueryStringParam, which is the name of the parameter that is 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 attribute for each input item comprises a set of InputFlags. The following table describes the input types that are currently defined.

Table 5 InputFlag Definitions

InputFlag

Description

Notes

A

Plain ASCII text

Use the DTMF keypad to enter text that consists 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 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 keypad-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 InputFlag field to use plain ASCII as the input type and to mask the input as a password by using an asterisk (*).

CiscoIPPhoneDirectory

The CiscoIPPhoneDirectory XML object supports the Directory operation of IP phones. The following figure shows how an XML CiscoIPPhoneDirectory object displays on the phone.

Figure 2. CiscoIPPhoneDirectory Object Display Sample

CiscoIPPhoneDirectory 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>
</CiscoIPPhoneDirectory>

Note


For the directory listing, the IP phone displays the appropriate softkeys that are 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 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.


Note


The Cisco Unified IP Phone 6900 Series do not display 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.


Custom Directories

You can use the Cisco Unified Communications Manager enterprise URL Directories parameter and CiscoIPPhone XML objects to display custom directories. The URL Directories parameter points to a URL that returns a CiscoIPPhoneMenu object to extend the directories menu. The request for URL Directories must return a valid CiscoIPPhoneMenu object, even if the object has no 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 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 softkey on the phone.

CiscoIPPhoneImage

The CiscoIPPhoneImage provides a bitmap display with a 133 x 65 pixel pane (irrespective of the window mode being normal width or wide width), 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 LCD display, which inverts the palette.


The CiscoIPPhoneImage XML type lets you use the IP phone display to present graphics to the user.

Related References

CiscoIPPhoneImage Definition

<CiscoIPPhoneImage WindowMode="XSI window width mode">
<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 WindowMode attribute is an optional attribute that is used to set the width of an XSI application window. This attribute is supported on the Cisco Unified IP Phones 7941, 7942, 7945, 7961, 7962, 7965, 7970, 7971, and 7975.

The WindowMode attribute accepts either of the following values:

Normal:

(Default value) The application window is in the normal-width mode. See the following figure.

Wide:

The application window is in the full-width mode, that is the window expands to the complete phone screen width. The wide mode supports a maximum width of 320 pixels for an image. See the following figure.

The WindowMode attribute name and value are case sensitive. If the attribute name is wrong, the name is ignored and the default window width is used. If the attribute value is wrong, the parser reports an XML parse error and the object is rejected.

The WindowMode attribute is ignored on phones that does not support this feature. In these cases, the window remains the original width. In phones that support this attribute, the absence of the attribute means that the phone uses Normal mode.

For examples on the use of the WindowMode attribute, see CiscoIPPhoneImage Example 2.

Figure 3. WindowMode

The Title and Prompt 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.

Use Width and Height to size the graphic. If the values do not match with the pixel stream specified in the Data field, results will be unpredictable or incorrect.

Depth specifies the number of bits per pixel. IP phones support a maximum value of 2 bits per pixel. 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 IP phone, each pixel has only four possible values, which means that you can pack four pixels into a single byte. A pair of hexadecimal digits represents each byte.

The following figure 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 reordered in sets of four to create a single reordered byte, which the two hexadecimal digits represent.

Figure 4. Packed Pixel Translation Example

CiscoIPPhoneImage Example 1

The following XML code defines a CiscoIPPhoneImage object that displays the sequence of pixels shown in the above figure 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.


Note


Before displaying a graphic image on an IP phone, the software clears the pane dedicated to services. If a service has text or other information that must be preserved (including the title area), the information must get redrawn as part of the graphic. If the title is to be hidden, the graphic must be large enough to cover it.


CiscoIPPhoneImage Example 2

The following XML code examples show the usage of the WindowMode attribute in the CiscoIPPhoneImage object.

  • CiscoIPPhoneImage object with no WindowMode attribute. See the following figure.
    <CiscoIPPhoneImage>
      <Title>Image Object</Title>
       <LocationX>0</LocationX>
       <LocationY>20</LocationY>
       <Width>133</Width>
       <Height>45</Height>
       <Depth>1</Depth>
       <Data>f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0</Data>
       <Prompt>Image Object</Prompt>
    </CiscoIPPhoneImage>
  • CiscoIPPhoneImage object with WindowMode set to normal. See the following figure.
    <CiscoIPPhoneImage WindowMode="Normal">
      <Title>Image Object</Title>
       <LocationX>0</LocationX>
       <LocationY>20</LocationY>
       <Width>133</Width>
       <Height>45</Height>
       <Depth>1</Depth>
       <Data>f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0</Data>
       <Prompt>Image Object</Prompt>
    </CiscoIPPhoneImage>
Figure 5. CiscoIPPhoneImage Object

  • CiscoIPPhoneImage object with WindowMode set to wide. See the following figure.
    <CiscoIPPhoneImage WindowMode="Wide">
      <Title>Image Object</Title>
       <LocationX>0</LocationX>
       <LocationY>20</LocationY>
       <Width>133</Width>
       <Height>45</Height>
       <Depth>1</Depth>
       <Data>f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0</Data>
       <Prompt>Image Object</Prompt>
    </CiscoIPPhoneImage>
Figure 6. CiscoIPPhoneImage Object with WindowMode Wide

CiscoIPPhoneImageFile

The latest generation of IP phones have higher-resolution displays with more color depth. The Cisco Unified IP Phone 7970G, for example, has a display area of 298x168 pixels available to the Services pane and renders images in 12-bit color.

To support these more advanced displays, the XML object allows the use of color PNG images in addition to the grayscale CiscoIPPhoneImage objects. The CiscoIPPhoneImageFile object behaves like the CiscoIPPhoneImage object, except for the image data. Instead of using the <Data> tag to embed the image data, the <URL> tag points to the PNG image file.

The web server must deliver the PNG image to the phone with an appropriate MIME Content-Type header, such as image/png, so that the phone recognizes the content as a compressed, binary PNG image. The PNG image can be either palettized or RGB, and the maximum image size and color depth are model dependent (see the following table).

Model

Resolution (see note 1)

(width x height)

Resolution in wide mode

(width x height)

Color, Grayscale, Monochrome

Color depth (bits)

Cisco Unified IP Phones 6921, 6961

396 x 81

N/A

Monochrome

Cisco Unified IP Phones 6941, 6945

396 x 162

N/A

Monochrome

Cisco IP Phones 7821, 7841, 7861

N/A

N/A

Monochrome

Cisco Unified IP Phones 7905G, 7906G, 7911G, 7912G (see note 2), 7931G

N/A

N/A

Grayscale

1

Cisco Unified IP Phone 7920

128 x 59

N/A

Grayscale

1

Cisco Unified Wireless IP Phones 7921G, 7925G, 7926G, 7925G-EX

176 x 140

N/A

Color

16

Cisco Unified IP Phone 7937G

255 x 128

N/A

Grayscale

2

Cisco Unified IP Phones 7940G, 7960G

133 x 65

N/A

Grayscale

2

Cisco Unified IP Phones 7941G, 7941G-GE, 7942G, 7961G, 7961G-GE, 7962G

298 x 144

320 x 144

Grayscale

4

Cisco Unified IP Phones 7945G, 7965G

298 x 156

320 x 156

Color

16

Cisco Unified IP Phone 7970G, 7971G

298 x 168

320 x 168

Color

12

Cisco Unified IP Phone 7975G

298 x 168

320 x 168

Color

16

Cisco IP Communicator

298 x 168

N/A

Color

24

Cisco Unified IP Conference Station 8831

396 x 162

N/A

Monochrome

Cisco IP Phone 8841, 8851, and 8861

559 x 313

N/A

Color

24

Cisco Unified IP Phones 8941, 8945

498 x 289

N/A

Color

24

Cisco Unified IP Phones 8961, 9951, 9971

498 x 289

N/A

Color

24


Note


  1. Resolution represents the size of the display that is accessible by Services; not the full resolution of the physical display.
  2. The Cisco 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) correctly dithers the color palette of the image for the best display results on the Cisco Unified IP Phone 7970G.

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

Figure 7. Cisco Unified IP Phone 7970G Image File Display

CiscoIPPhoneImageFile Definition

<CiscoIPPhoneImageFile WindowMode="Width Mode of XSI window">
  <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>

For the description on WindowMode attribute, see CiscoIPPhoneImage

For examples of the use of the WindowMode attribute, see CiscoIPPhoneImageFile Examples.

CiscoIPPhoneImageFile Examples

The following XML code shows the usage of WindowMode attribute in CiscoIPPhoneImageFile object.

  • Without the WindowMode attribute. See the following figure.
    <CiscoIPPhoneImageFile>
      <Title>Image File Object</Title>
      <Prompt>Image File Object</Prompt>
      <LocationX>0</LocationX>
      <LocationY>0</LocationY>
      <URL>http://10.74.63.74:8080/xsi/normal1.png</URL>
    </CiscoIPPhoneImageFile>
  • With WindowMode attribute set to Normal. See the following figure.
    <CiscoIPPhoneImageFile WindowMode="Normal">
      <Title>Image File Object</Title>
      <Prompt>Image File Object</Prompt>
      <LocationX>297</LocationX>
      <LocationY>0</LocationY>
      <URL>http://10.74.63.74:8080/xsi/normal1.png</URL>
    </CiscoIPPhoneImageFile>
Figure 8. CiscoIPPhoneImageFile Object

  • WindowMode attribute set to Wide and point the URL to a larger png image file. See the following figure.
    <CiscoIPPhoneImageFile WindowMode="Wide">
      <Title>Image File Object</Title>
      <Prompt>Image File Object</Prompt>
      <LocationX>319</LocationX>
      <LocationY>0</LocationY>
      <URL>http://10.74.63.74:8080/xsi/wide1.png</URL>
    </CiscoIPPhoneImageFile>
Figure 9. WindowMode Attribute Set to Wide

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. When using non-ASCII character sets, the system presents the information as a bitmap graphic. To select a menu, the user enters a number from 1 to 12 using the numeric keypad (* and # are not active).

CiscoIPPhoneGraphicMenu Definition

<CiscoIPPhoneGraphicMenu WindowMode="Width Mode of XSI window">
  <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>

For the description on WindowMode attribute, see CiscoIPPhoneImage.

For examples of the use of the WindowMode attribute, see CiscoIPPhoneGraphicFileMenu WindowMode Examples.

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 the URL for the chosen item loads. If the loaded page has a title of its own, the phone uses the defined 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.

CiscoIPPhoneGraphicMenu WindowMode Examples

The following XML code shows the usage of WindowMode attribute in CiscoIPPhoneGraphicMenu object.

  • Without WindowMode attribute. See the following figure.
    <CiscoIPPhoneGraphicMenu>
      <Title>Graphic menu</Title>
      <Prompt>Graphic menu</Prompt>
      <LocationX>10</LocationX>
      <LocationY>15</LocationY>
      <Width>133</Width>
      <Height>45</Height>
      <Depth>1</Depth>
      <Data>f0f0f0f0f0f0f0f0f0f0f0f0f0</Data>
      <MenuItem>
        <Name>dial_1000</Name>
        <URL>Dial:1000</URL>
      </MenuItem>
    </CiscoIPPhoneGraphicMenu>
  • With WindowMode attribute set to Normal. See the following figure.
    <CiscoIPPhoneGraphicMenu WindowMode="Normal">
      <Title>Graphic menu</Title>
      <Prompt>Graphic menu</Prompt>
      <LocationX>10</LocationX>
      <LocationY>15</LocationY>
      <Width>133</Width>
      <Height>45</Height>
      <Depth>1</Depth>
      <Data>f0f0f0f0f0f0f0f0f0f0f0f0f0</Data>
      <MenuItem>
        <Name>dial_1000</Name>
        <URL>Dial:1000</URL>
      </MenuItem>
    </CiscoIPPhoneGraphicMenu>
Figure 10. CiscoIPPhoneGraphicMenu Object

  • With WindowMode attribute set to Wide. See the following figure.
    <CiscoIPPhoneGraphicMenu WindowMode="Wide">
      <Title>Graphic menu</Title>
      <Prompt>Graphic menu</Prompt>
      <LocationX>10</LocationX>
      <LocationY>15</LocationY>
      <Width>133</Width>
      <Height>45</Height>
      <Depth>1</Depth>
      <Data>f0f0f0f0f0f0f0f0f0f0f0f0f0</Data>
      <MenuItem>
        <Name>dial_1000</Name>
        <URL>Dial:1000</URL>
      </MenuItem>
    </CiscoIPPhoneGraphicMenu>
Figure 11. WindowMode Attribute set to Wide

CiscoIPPhoneGraphicFileMenu

Some of the Cisco Unified IP Phone models, such as the Cisco Unified IP Phone 7970G and Cisco IP Communicator, have pointer devices. The Cisco Unified IP Phone 7970G uses a touchscreen overlay on the display, and the PC-based Cisco IP Communicator uses the standard Windows mouse pointer.

Because these devices can receive and process “pointer” events, a CiscoIPPhoneGraphicFileMenu object exposes the capability to application developers. The CiscoIPPhoneGraphicFileMenu behaves similar to the CiscoIPPhoneGraphicMenu, in that a group of options are presented by an image. When one of those objects is selected, a URL action initiates. However, the FileMenu does not use the keypad, but uses rectangular touch areas. This rectangular touch area, <TouchArea>, is defined by coordinates relative to the upper-left corner of the Services display. The (X1,Y1) points specify the upper-left corner of the <TouchArea>, and (X2,Y2) specify the lower-right corner of the <TouchArea>.

The following figure shows the display of the CiscoIPPhoneGraphicFileMenu.

Figure 12. CiscoIPPhoneGraphicFileMenu

If the coordinates that are supplied in the <TouchArea> tag exceed the dimensions of the phone display, the <TouchArea> rectangle will be clipped to fit.

The <TouchArea> rectangles can overlap, and the first match is always taken. This allows a sense of Z-order for images where smaller touchable objects can be overlaid on top of larger ones. In this case, the smaller object <MenuItem> must appear before the larger one in the <CiscoIPPhoneGraphicFileMenu> object.

The requirements for the PNG image referenced by the <URL> tag match those that the CiscoIPPhoneImageFile object uses.

CiscoIPPhoneGraphicFileMenu Definition

<CiscoIPPhoneGraphicFileMenu WindowMode="Width Mode of XSI window">
  <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>

For the description on WindowMode attribute, see CiscoIPPhoneImage.

For examples of the use of the WindowMode attribute, see CiscoIPPhoneGraphicFileMenu WindowMode Examples.

CiscoIPPhoneGraphicFileMenu WindowMode Examples

The following XML code shows the usage of WindowMode attribute in CiscoIPPhoneGraphicFileMenu object.

  • Without WindowMode attribute. See the following figure.
    <CiscoIPPhoneGraphicFileMenu>
      <Title>Graphic File Menu</Title>
      <Prompt>Graphic File Menu</Prompt>
      <LocationX>0</LocationX>
      <LocationY>0</LocationY>
      <URL>http://10.74.63.74:8080/xsi/normal1.png</URL>
      <MenuItem>
        <Name>dial_1000</Name>
        <URL>Dial:1000</URL>
        <TouchArea X1="0" Y1="0" X2="160" Y2="168"/>
      </MenuItem>
    </CiscoIPPhoneGraphicFileMenu>
  • With WindowMode attribute set to Normal. See the following figure.
    <CiscoIPPhoneGraphicFileMenu WindowMode="Normal">
      <Title>Graphic File Menu</Title>
      <Prompt>Graphic File Menu</Prompt>
      <LocationX>0</LocationX>
      <LocationY>0</LocationY>
      <URL>http://10.74.63.74:8080/xsi/normal1.png</URL>
      <MenuItem>
        <Name>dial_1000</Name>
        <URL>Dial:1000</URL>
        <TouchArea X1="0" Y1="0" X2="160" Y2="168"/>
      </MenuItem>
    </CiscoIPPhoneGraphicFileMenu>
Figure 13. CiscoIPPhoneGraphicFileMenu

  • With WindowMode attribute set to Wide. See the following figure
    <CiscoIPPhoneGraphicFileMenu WindowMode="Wide">
      <Title>Graphic File Menu</Title>
      <Prompt>Graphic File Menu</Prompt>
      <LocationX>0</LocationX>
      <LocationY>0</LocationY>
      <URL>http://10.74.63.74:8080/xsi/wide3.png</URL>
      <MenuItem>
        <Name>dial_1000</Name>
        <URL>Dial:1000</URL>
        <TouchArea X1="0" Y1="0" X2="160" Y2="168"/>
      </MenuItem>
    </CiscoIPPhoneGraphicFileMenu>
Figure 14. WindowMode Attribute set to Wide

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. For example, you include a read and unread icon in a mail viewer. You can use the icons can to convey the message state.

Icons in the CiscoIPPhoneIconMenu object have a maximum width of 16 pixels and a maximum height of 10 pixels.

The following figure shows an IconMenu on an IP phone.

Figure 15. CiscoIPPhoneIconMenu on a Cisco Unified IP Phone Sample

The system presents the information as a bitmap graphic to the left of the menu item text. The user selects menu items in the same way as a CiscoIPPhoneMenu object.

CiscoIPPhoneIconMenu 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 softkey</Name>
    <URL>URL or URI of softkey</URL>
    <Position>Position information of the softkey</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>

Note


The Cisco Unified IP Phone 6900 Series do not display 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.


The XML tags in CiscoIPPhoneIconMenu use the tag definitions for CiscoIPPhoneImage and CiscoIPPhoneMenu. Although the semantics of the tags are identical, you can have only 32 MenuItem objects in a CiscoIPPhoneIconMenu object.

CiscoIPPhoneIconFileMenu


Note


The CiscoIPPhoneIconFileMenu object is updated to support new attributes. For details, see Enhanced Icon Menu Support Feature.


This icon menu is similar to CiscoIPPhoneMenu, but it uses color PNG icons rather than grayscale CIP icons. 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, you can use icons to indicate priority (see the following figure).

Icons in the CiscoIPPhoneIconFileMenu object have a maximum width of 18 pixels and a maximum height of 18 pixels. Instead of using the <Data> tag to embed the image data into the <IconItem> tag, this object uses a <URL> tag to point to the PNG image file to be used for that icon.

Figure 16. CiscoIPPhoneIconFileMenu Object Display Sample

CiscoIPPhoneIconFileMenu Definition

<CiscoIPPhoneIconFileMenu>
  <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>
  <IconItem>
    <Index>A unique index from 0 to 9</Index>
    <URL>location of the PNG icon image</URL>
  </IconItem>
</CiscoIPPhoneIconFileMenu>

Note


The Cisco Unified IP Phone 6900 Series do not display 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.


Enhanced Icon Menu Support Feature

The Enhanced Icon Menu Support feature extends the existing CiscoIPPhoneIconFileMenu XML object by allowing:

  • An icon in its <Title> element.
  • Internal phone firmware icons, like security state or call state icons, in its <MenuItems> and <Title> elements.
Supported IP Phones and Codecs

The following table lists the IP phone models that support the Enhanced Icon Menu Support feature.

Phone model Support Firmware supported

Cisco Unified IP Phone 9900 Series

9971

Supported

9.0(1) and later

9951

Supported

9.0(1) and later

Cisco Unified IP Phone 8900 Series

8941, 8945

Not supported

8961

Supported

9.0(1) and later

Cisco IP Phone 8800 Series

8831

Not supported

9.3 and later

8841

Not supported

10.2(1) and later

8851

Not supported

10.2(1) and later

8861

Not supported

10.2(1) and later

Cisco Unified IP Phone 7900 Series

7905

Not supported

7906

Supported

8.4(1) and later

7911

Supported

8.4(1) and later

7912

Not supported

7931

Supported

8.4(1) and later

7937

Not supported

7940

Not supported

7941

Supported

8.4(1) and later

7942

Supported

8.4(1) and later

7945

Supported

8.4(1) and later

7960

Not supported

7961

Supported

8.4(1) and later

7962

Supported

8.4(1) and later

7965

Supported

8.4(1) and later

7970

Supported

8.4(1) and later

7971

Supported

8.4(1) and later

7975

Supported

8.4(1) and later

7985

Not supported

Cisco Unified Wireless IP Phone 7900 Series

7920

Not supported

7921G

Not supported

7925G, 7925G-EX

Not supported

7926G

Not supported

Cisco IP Phone 7800 Series

7821

Not supported

7841

Not supported

7861

Not supported

Cisco Unified IP Phone 6900 Series

6921

Not supported

6941

Not supported

6945

Not supported

6961

Not supported

Other devices

Cisco IP Phone Communicator

Not supported


Note


Cisco recommends the use of latest firmware. The firmware can be downloaded from the following location (requires login or service contract):

http:/​/​software.cisco.com/​download/​navigator.html?i=!mmd


Although several codecs are listed within the schema, only the codecs G711, G729, and G722 are currently supported.

CiscoIPPhoneIconFileMenu XML Object Changes

The following changes have been made in the CiscoIPPhoneIconFileMenu XML object for the Enhanced Icon Menu Support feature:

  • The CiscoIPPhoneIconFileMenu schema is updated to allow an IconIndex attribute in the <Title> element.
  • A Resource URI attribute is available for the <URL> element of the <IconItem> element. This Resource URI can be used in place of the HTTP URL.
  • The Resource URI identifies the icons in the <IconItems>. When a phone parses the <URL> element in <IconItem>, the phone looks for the Resource URI.
    • If the Resource URI is present, the phone validates the URI against the valid Resource Icon values. If the validation is successful, the phone uses the icon specified by the Resource URI.
    • If the Resource URI is not present or if the URI fails the validation against a recognized Icon value, then a default unknown-icon image displays.
Related References
Schema Definition

The definition of the CiscoIPPhoneIconFileMenu schema remains the same except for the <Title> element and the IconIndex attribute specified as follows:

<xsd:complexType name="Title">
		<xsd:attribute name="IconIndex"
 type="xsd:unsignedShort"
 use="optional"/>	
</xsd:complexType>
CiscoIPPhoneIconFileMenu Example

The following is an example of the CiscoIPPhoneIconFileMenu object with IconIndex attribute in <Title> element and Resource URI attribute in <IconItem> element:

<CiscoIPPhoneIconFileMenu>
  <Title IconIndex="2">Conference List</Title>
  <IconItem>
    <Index>1</Index>
    <URL>Resource:Icon.SecureCall</URL>
  </IconItem>
  <IconItem>
    <Index>2</Index>
    <URL>Resource:Icon.Connected</URL>
  </IconItem>
  <IconItem>
    <Index>3</Index>
    <URL>Resource:AnimatedIcon.Ringin</URL>
  </IconItem>
  <MenuItem>
    <Name>Schmo, Joe</Name>
    <IconIndex>1</IconIndex>
    <URL>http://192.168.1.12:8080/details?user=jschmo</URL>
  </MenuItem>
  <MenuItem>
    <Name>Blow, Joe</Name>
    <IconIndex>2</IconIndex>
    <URL>http://192.168.1.12:8080/details?user=jblow</URL>
  </MenuItem>
  <MenuItem>
    <Name>Joining, Just Now</Name>
    <IconIndex>3</IconIndex>
    <URL>http://192.168.1.12:8080/details?user=jjoining</URL>
  </MenuItem>
</CiscoIPPhoneIconFileMenu>
Valid Resource Icon Names

The following are the valid Resource Icon names:

  • Icon.Connected
  • Icon.AuthenticatedCall
  • Icon.SecureCall
  • Icon.OnHook
  • Icon.OffHook
  • Icon.Messages
  • Icon.InUse
  • Icon.Headset
  • Icon.Handset
  • Icon.Speaker
  • Icon.Locked
  • Icon.UnLocked
  • Icon.Checked
  • Icon.UnChecked
  • Icon.RadioButtonOn
  • Icon.RadioButtonOff
  • AnimatedIcon.Ringin
  • AnimatedIcon.Hold
  • AnimatedIcon.MessageWaiting
  • AnimatedIcon.StreamingRx
  • AnimatedIcon.StreamingTx
  • AnimatedIcon.StreamRxTx
  • AnimatedIcon.Throbber
Troubleshooting CiscoIPPhoneIconFileMenu XML Objects Using Enhanced Icon Menu Support Feature

The following errors and conditions may occur in the Enhanced Icon Menu Support feature:

  • If the CiscoIPPhoneIconFileMenu object is invalid, a parsing error is generated and a CiscoIPPhoneError object (with Number=“1”) is returned as the response.
  • If the Resource URI does not specify a recognized Icon resource, then a default unknown-icon image is displayed.
Error Handling

Standard XML services debugging techniques are applied to the Enhanced Icon Menu Support feature. The root cause for any parsing errors displays in the phone console logs. For HTTP requests and responses, sniffer traces and web server debug can be used to examine the CiscoIPPhoneIconFileMenu object to ensure that the object conforms to the schema.

CiscoIPPhoneStatus

The CiscoIPPhoneStatus object is also a displayable object, but differs from other objects in that it displays on the Call plane of the phone rather than the Services plane. The CiscoIPPhoneStatus object hovers above the Call plane and is typically used in conjunction with CTI applications to present application status to the user.

The Status object cannot be closed or cleared by the user (for example, by pressing Services) because the Status object is only present on the Call plane. In order to clear the object, the phone must execute the Init:AppStatus URI. This would typically occur as the result of an application server pushing an Execute object to the phone that contains the Init:AppStatus URI.


Note


The CiscoIPPhoneStatus object can only be pushed (HTTP POST) to the phone; the object cannot be pulled (HTTP GET).


The CiscoIPPhoneStatus object can be refreshed or replaced at any time. It is not necessary to clear an existing Status object before sending a new Status object. The new object simply replaces the old object.

The following figure shows the CiscoIPPhoneStatus object that contains the following visual elements:

  • 106 x 21 graphics area for displaying CIP images (same image format as CiscoIPPhoneImage)
  • Seedable, free-running timer (optional)
  • Single-line text area (optional)
Figure 17. IconMenu on a CiscoIPPhoneStatus sample

CiscoIPPhoneStatus Definition

<CiscoIPPhoneStatus>
  <Text>This is the text area</Text>
  <Timer>Timer seed value in seconds</Timer>
  <LocationX>Horizontal alignment</LocationX>
  <LocationY>Vertical alignment</LocationY>
  <Width>Pixel width of graphic</Width>
  <Height>Pixel height of graphic</Height>
  <Depth>Color depth in bits</Depth>
  <Data>Hex binary image data</Data>
</CiscoIPPhoneStatus>

Note


The Cisco Unified IP Phone 6900 Series do not display 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.


Dynamic Application Status Window Size

You can enable applications to dynamically adjust their window sizes based on the displayed content. The minimum size requirements limit the windows size so that it is large enough to stand out from the Overview content. For example, using a smaller window for an application allows more content from the Overview to be displayed. Sizing the window occurs when the phone receives a CiscoIPPhoneStatus or CiscoIPPhoneStatusFile object with its associated PNG file.

The Application Status window contains three main areas (see the following figure):

  • Text Area
  • Timer Area
  • Image Area
Figure 18. Application Status Window Elements


Note


Selfterminating XML elements, undeclared or missing elements, and elements with the default values are all considered unconfigured elements.


To allow dynamic sizing, do not configure the Text and Timer areas with any value other than the default used by the XML parser. If both elements are not configured, you can proceed, but must follow these rules:

  • Do not display the Text Area and Timer Area sections of the Application Status window.
  • If the LocationX element is not configured or is set to centered, and the image provided is less than the maximum width allowed, the Image Area can be resized.
  • If the image provided is smaller than the minimum width, the minimum allowed window width should be used.
  • If the width of the image provided is between the minimum and maximum sizes of the window, the window should be sized to display the image as well as the standard surrounding borders.
  • The image height should never change.

See the following table for an overview of the maximum and minimum image area sizes by phone model. Most phone models support all sizes between the minimum and maximum. An exception is allowed for the Cisco Unified IP Phones 7940G and 7960G due to resource constraints. For these phones, you should implement both the maximum size and minimum size windows, ignoring all of the intermediate sizes.

Table 6 Application Status Window Allowable Image Sizes
Phone models Maximum image area width Minimum image area width Maximum image area height

7937G

133

21

65

7940G, 7960G

106

21

21

7941G, 7941G-GE, 7942G, 7945G, 7961G, 7961G-GE, 7962G, 7965G

252

50

50

7970G, 7971G-GE, 7975G, IP Communicator

262

50

50

8831

8841, 8851, 8861

414

70

70

8941, 8945

342

73

73

8961, 9951, 9971

342

73

73

The following table shows an overview of the text and timer area sizes by phone model.

Table 7 Application Status Window Allowable Text and Timer Sizes
Phone models Text area size (WxH) Timer area size (WxH) Text area sixe No timer (WxH)

7940G, 7960G

76x11

30x11

106x11

7941G, 7941G-GE, 7942G, 7945G, 7961G, 7961G-GE, 7962G, 7965G,

192x20

60x20

252x20

7970G, 7971G-GE, 7975G, IP Communicator

202x20

60x20

262x20

8831

8841, 8851, 8861

300x36

100x36

414x36

8941, 8945

278x23

52x23

342x23

8961, 9951, 9971

278x23

52x23

342x23

CiscoIPPhoneStatusFile

The behavior of this object is identical to the CiscoIPPhoneStatus object, except it uses a color PNG image instead of a grayscale CIP image for the graphics area.

The maximum image size is 262 x 50 pixels for the Cisco Unified IP Phone 7970G, but differs for other phone models.

The following figure shows how an XML CiscoIPPhoneStatusFile object displays on a phone.

Figure 19. CiscoIPPhoneStatusFile Object Display Sample

Related References

CiscoIPPhoneStatusFile Definition

<CiscoIPPhoneStatusFile>
<Text>This is the text area</Text>
<Timer>Timer seed value in seconds</Timer>
<LocationX>Horizontal alignment</LocationX>
<LocationY>Vertical alignment</LocationY>
<URL>location of the PNG image</URL>
</CiscoIPPhoneStatusFile>

Note that instead of using the <Data> tag to embed the image data, this object uses a <URL> tag to point to the PNG image file to be used for the graphics area.

CiscoIPPhoneExecute

The CiscoIPPhoneExecute object differs from the other CiscoIPPhone objects. It is not a displayable object for providing user interaction. The purpose of this object is to deliver (potentially multiple) execution requests to the phone.

Like the other XML objects, the CiscoIPPhoneExecute can be either pushed (HTTP POST) or pulled (HTTP GET). Upon receiving a CiscoIPPhoneExecute object, the phone begins executing the specified ExecuteItems. Order of execution is not guaranteed, so ExecuteItems will likely not execute in the order in which they are listed in the CiscoIPPhoneExecute object.


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.


CiscoIPPhoneExecute Definition

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

The <ExecuteItem> tag of the CiscoIPPhoneExecute object includes an optional attribute called Priority. The Priority attribute is used to inform the phone of the urgency of the execute request and to indicate whether the phone should be interrupted to perform the request. The Priority levels determine whether the phone must be idle to perform the requested action. The Idle Timer (along with an optional Idle URL) is defined globally in the Cisco Unified Communications Manager Administration Enterprise Parameters and can be overridden on an individual phone basis in the Cisco Unified Communications Manager Device configuration.

The following table lists the Priority levels and their behavior.

Priority Behavior Description

0

Execute Immediately

The URL executes regardless of the state of the phone. If the Priority attribute does not get specified in the <ExecuteItem>, the default priority gets set to zero for backward compatibility.

1

Execute When Idle

The URL gets delayed until the phone goes idle, then it executes.

2

Execute If Idle

The URL executes on an idle phone; otherwise, it does not get executed (it does not get delayed).


Note


The Priority attribute is only used for HTTP URLs. Internal URIs always execute immediately.


CiscoIPPhoneExecute Example

The following CiscoIPPhoneExecute object results in the phone playing an alert chime, regardless of the state of the phone, but waits until the phone goes idle before displaying the specified XML page.

<CiscoIPPhoneExecute>
	<ExecuteItem Priority=”0” URL=”Play:chime.raw”/>
	<ExecuteItem Priority=”1” URL=”http://server/textmessage.xml”/>
</CiscoIPPhoneExecute>

CiscoIPPhoneResponse

The CiscoIPPhoneResponse objects provide messages and information resulting from a CiscoIPPhoneExecute. As a result, a ResponseItem exists for each ExecuteItems that you send. The order differs based on 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.

CiscoIPPhoneResponse 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

CiscoIPPhoneError Definition

<CiscoIPPhoneError Number=”x”/> optional error message <CiscoIPPhoneError>

The text value of the CiscoIPPhoneError object may contain an optional error message to further describe the nature of the error condition.

Custom Softkeys

IP Phones can use custom softkeys with any of the displayable CiscoIPPhone XML objects, with the following exceptions:

  • CiscoIPPhoneStatus object, which cannot control softkeys
  • CiscoIPPhoneExecute object, which is not displayable

Softkeys can have either URL or URI actions associated with them. The SoftkeyItem can define separate actions to be taken when the softkey is pressed and released. The standard UI behavior is to execute an action when a key is released, and this action is defined by the <URL> tag. An action can also be taken when the softkey is initially pressed by including the optional <URLDown> tag. For example, you might use <URLDown> for a press-to-talk application in which pressing the button starts audio streaming and releasing the button stops it.


Note


The <URLDown> tag can only contain Internal URIs: it cannot contain an HTTP URL. The "URL" in the name "URLDown" does not signify that an HTTP URL can be used.


SoftKeyItem Definition

<SoftKeyItem>
	<Name>Displayed sofkey label</Name>
	<URL>URL or URI action for softkey RELEASE event</URL>
	<URLDown>URL or URI action for softkey PRESS event</URLDown>
	<Position>position of softkey</Position>
</SoftKeyItem>

SoftKeyItem Example 1

In this example, a CiscoIPPhoneText object has a single custom softkey defined.

<CiscoIPPhoneText>
	<Text>This object has one softkey named "Custom"</Text>
	<SoftKeyItem>
		<Name>Custom</Name>
		<URL>http://someserver/somepage</URL>
		<Position>4</Position>
	</SoftKeyItem>
</CiscoIPPhoneText>

If any custom softkeys are defined in the XML object, then all default softkeys are removed from that object. To retain default softkey behavior, you must explicitly define the softkeys in the XML object using a <SoftKeyItem> tag. The internal Softkey URIs can be used in the <URL> tag of <SoftKeyItem> to invoke default softkey actions from custom softkeys.


Note


If there are no custom softkeys and there is no default softkey placed in position 1, either a Next or Update softkey is assigned automatically. If the URL is a Refresh URL, the Next softkey is assigned. If not, the Update softkey is assigned.


Related Information

SoftKeyItem Example 2

The following softkey definitions would provide the Custom softkey, without losing the default Select softkey behavior.

<SoftKeyItem>
	<Name>Select</Name>
	<URL>SoftKey:Select</URL>
	<Position>1</Position>
</SoftKeyItem>
<SoftKeyItem>

XML Considerations

The XML parser in the 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 provide escape values for a few special characters. The following table lists characters and their escape values.

Table 8 Escape Sequences for Special Characters
Character Name Escape sequence

&

Ampersand

&amp;

"

Quote

&quot;

'

Apostrophe

&apos;

<

Left angle bracket

&lt;

>

Right angle bracket

&gt;

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

XML Encoding

Because the phone firmware can support multiple encodings, the XML encoding should always be set in the XML header.

If the XML encoding header is not specified, the phone will default to the encoding specified by the current user locale.


Note


This behavior is NOT compliant with XML standards, which specify UTF-8 as the default encoding, so any UTF-8 encoded XML object must have the encoding explicitly set for the phone to parse it correctly.


The encoding value specified in the XML header must match one of the encodings provided by the IP Phone in its Accept-Charset HTTP request header, as shown in XML Encoding Example

XML Encoding Example

The following examples illustrate UTF-8 and ISO-8859-1 encoding, respectively:

<?xml version="1.0" encoding="utf-8" ?>

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

Related References

Application Event Handlers

The Application Manager API includes an Application Management Event Handler, which is supported by any displayable object, as noted in the following table. The unsupported objects are not contained in a standard application context and are handled differently by the Application Manager API.

Table 9 Application Event Handler Support
Supported Unsupported

CiscoIPPhoneMenu

CiscoIPPhoneStatus

CiscoIPPhoneText

CiscoIPPhoneStatusFile

CiscoIPPhoneInput

 

CiscoIPPhoneDirectory

 

CiscoIPPhoneImage

 

CiscoIPPhoneImageFile

 

CiscoIPPhoneGraphicMenu

 

CiscoIPPhoneGraphicFileMenu

 

CiscoIPPhoneIconMenu

 

CiscoIPPhoneIconFileMenu

 

Note


Support for the Application Event Handlers requires an updated XML Parser.


Application Event Handler Attributes

The Application Event Handlers can be attached to a supported object by specifying the attributes described in the following table.


Note


An Application URI with Priority=0 is not allowed in the Application Event Handlers.


Table 10 Application Event Handler Attributes
Attribute Description

appID

Identifies the application to which this displayable object belongs. The format of the appID attribute should be in the format vendor/product, such as Cisco/Unity, but this syntax is not enforced, and the application can assign any unique identifier.

onAppFocusLost

Invoked when the application loses focus, if one of the following conditions occurs:

  • The application context loses focus
  • The application was navigated away from, either directly by the user, or programmatically by a refresh header or HTTP push
Note   

If a Notify URI is used as the event handler, a notification is sent with this default data: <notifyApplicationEvent appId="appId" type="focusLost"/>

onAppFocusGained

Note   

Invoked when the application gains focus, if one of the following conditions occurs:

  • The application is Active and the application context gains focus
  • The application was navigated to, either directly by the user, or by a refresh header or HTTP push

If a Notify URI is used as the event handler, a notification is sent with this default data: <notifyApplicationEvent appId="appId" type="focusGained"/>

onAppMinimized

Invoked when the application is minimized.

An application can only be minimized in a program by a call to App:Minimize, but this invocation could occur by direct action of the user (for example, from a softkey invocation) or from the application using a push request. <notifyApplicationEvent appId="appId" type="minimized"/>

onAppClosed

Invoked when the application closes, if one of the following conditions occur:

  • The application context is closed which will, in turn, close all applications in its stack
  • The application no longer exists on the context URL stack because it was navigated away from, or because it was pruned from the URL stack (stack size exceeded)
Note   

This event handler cannot contain HTTP or HTTPS URLs.

Note   

If a Notify URI is used as the event handler, a notification is sent with this default data: <notifyApplicationEvent appId="appId" type="closed"/>

Related References

Event Handler Schema

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" attributeFormDefault="unqualified">
  <xs:element name="notifyApplicationEvent">
    <xs:complexType>
      <xs:attribute name="appId" use="required">
        <xs:simpleType>
          <xs:restriction base="xs:string">
            <xs:minLength value="1"/>
            <xs:maxLength value="64"/>
          </xs:restriction>
        </xs:simpleType>
      </xs:attribute>
      <xs:attribute name="type" use="required">
        <xs:simpleType>
          <xs:restriction base="xs:string">
            <xs:enumeration value="closed"/>
            <xs:enumeration value="minimized"/>
            <xs:enumeration value="focusLost"/>
            <xs:enumeration value="focusGained"/>
          </xs:restriction>
        </xs:simpleType>
      </xs:attribute>
    </xs:complexType>
  </xs:element>
</xs:schema>

Event Handler Example

<CiscoIPPhoneImage appId="Cisco/Unity"
  onAppFocusLost="RTPRx:Stop; RTPTx:Stop; Notify:http:server:80:path"
  onAppFocusGained="http://server/mainpage/updateUI"
  onAppClosed="Notify:http:server:80:eventlistener/appClosed">
  ...
</CiscoIPPhoneImage>