Application Protocols

CallManager provides support for application development. The protocols to support applications include TAPI, JTAPI, and XML for application development. TAPI is not covered in this appendix; you can learn about TAPI in Chapter 3.

JTAPI Package Support

JTAPI supports call control and primitive media support. JTAPI consists of a set of packages. A package is a means of grouping the functionality used by applications. Telephony server implementations choose the functionality that they support in each of the packages to leverage the underlying capabilities offered to the application. Applications can query to discover what packages and functionality is provided. The Core package support is the central functionality and the surrounding JTAPI packages include Call Center, Call Control, and Media packages, described in the tables that follow.

Core Package

Table C-14 lists each JTAPI interface in the JTAPI Core Package, all of which are supported in the Cisco JTAPI implementation.

Call Center Package

Table C-15 lists each JTAPI interface in the JTAPI Call Center Package and the support provided by the Cisco JTAPI implementation.

Call Center Capabilities Package

Table C-16 lists each JTAPI interface in the JTAPI Call Center Capabilities Package and the support provided by the Cisco JTAPI implementation.

Call Center Events Package

Table C-17 lists each JTAPI interface in the JTAPI Call Center Events Package and the support provided by the Cisco JTAPI implementation.

Call Control Package

Table C-18 lists each JTAPI interface in the JTAPI Call Control Package and the support provided by the Cisco JTAPI implementation.

Call Control Capabilities Package

Table C-19 lists each JTAPI interface in the JTAPI Call Control Capabilities Package, all of which are supported in the Cisco JTAPI implementation.

Call Control Events Package

Table C-20 lists each JTAPI interface in the JTAPI Call Control Events Package and the support provided by the Cisco JTAPI implementation.

Capabilities Package

Table C-21 lists each JTAPI interface in the JTAPI Capabilities Package, all of which are supported by the Cisco JTAPI implementation.

Events Package

Table C-22 lists each JTAPI interface in the JTAPI Events Package and the support provided by the Cisco JTAPI implementation.

Media Package

Table C-23 lists each JTAPI interface in the JTAPI Media Package and the support provided by the Cisco JTAPI implementation.

Media Capabilities Package

Table C-24 lists each JTAPI interface in the JTAPI Media Capabilities Package, all of which are supported by the Cisco JTAPI implementation.

Media Events Package

Table C-25 lists each JTAPI interface in the JTAPI Media Events Package and the support provided by the Cisco JTAPI implementation.

XML Data Types

This section provides the details of the XML support provided by the Cisco IP Phones to support the development of IP phone services described in Chapter 3.

Several of the XML data types described here have optional Title and Prompt fields. These fields behave identically, so this section describes them and the remainder of this chapter does not repeat the description.

Text defined in the Title field appears at the top of the page. If the data page specifies no Title field, the IP phone displays the Name field of the last selected MenuItem in the Title field.

The Prompt field defines text to appear at the bottom of the display page. If the data page specifies no Prompt parameter, the prompt area of the display is cleared.

Menu

The XML type CiscoIPPhoneMenu simply lists text items, one per line. Users select individual menu items either by using the scroll and entry selector or by number from the numeric keypad. The XML format allows you to specify a menu Title and Prompt, followed by up to 100 MenuItems. Each MenuItem has a name and an associated URL. After the user selects a menu option, the phone sends an HTTP request based on the URL associated with the menu item selected. Example C-1 shows the CiscoIPPhoneMenu XML type.

Example C-1. CiscoIPPhoneMenu XML Type

Title text goes here Prompt text goes here The name of each menu item The URL associated with the menu item Name of softkey URL or URI of softkey Position information of the softkey

IconMenu

Icon menus, like text menus, enable you to select a URL from a list. The icon menu allows you the additional capability to display visual information, such as item state or category, for each item in the list. Example C-2 shows the IconMenu XML type.

Example C-2. CiscoIPPhoneIconMenu XML Type

Title text goes here Prompt text goes here Indicates what IconItem to display The name of each menu item The URL associated with the menu item Name of softkey URL or URI of softkey Position information of the softkey A unique index from 0 to 9 size information for the icon

Text

The XML type CiscoIPPhoneText displays text on the phone display. The text should contain no control characters other than carriage return, line feed, or tab. The phone provides pagination and word-wrap to fit the text to the phone display. Plain text can be delivered either through this XML type or as plain text through HTTP. Text delivered as type text/HTML behaves the same as type CiscoIPPhoneText, except for the inability to include a Title or Prompt. Example C-3 shows the CiscoIPPhoneText XML type.

Example C-3. CiscoIPPhoneText XML Type

Title text goes here The prompt text goes here The text to be displayed as the message body goes here Name of softkey URL or URI of softkey Position information of the softkey

Image

The Cisco IP Phones 7960 and 7940 have a bitmapped display that is 133 by 65 pixels. Each pixel has four grayscale settings. The CiscoIPPhoneImage is used to render graphics on the Cisco IP Phone 7960 or 7940 display. The CiscoIPPhoneImage objects will display on the 7971, 7970, 7961, 7941, and IP Communicator phones, and the image size is doubled to compensate for the difference in screen resolution. The values specified by parameters LocationX and LocationY control the position of the graphic. These values specify the location, in pixels, of the upper-left corner of the graphic. The values 0, 0 position the graphic at the upper-left corner of the display. The values 1, 1 instruct the phone to center the graphic in the display area.

Width and Height, used to control those two dimensions, must be matched up properly with the pixel stream in the Data field to produce the desired results. Depth specifies the number of bits per pixel, which currently can be set to 1 for black and white image support or 2 bits per pixel grayscale yielding white, light gray, dark gray, and black.

The Data tag delimits a string of hexadecimal digits that contain the packed value of pixels in the display. In the Cisco IP Phones 7960 and 7940, each pixel has only three possible states, allowing 4 pixels packed per byte. Each byte is specified as 2 hex digits.

Table C-26 shows how the hex digits are packed to specify the pixel values, 2 bits per pixel. A contiguous stream of hex digits, with no separators or spaces, specifies the entire display. The stream is (width x height + 3)/4 characters in length. The phone display is cleared at the time the graphic is displayed. For a single pixel depth of 1 (black and white), the pixels are packed 8 pixels per byte.

Example C-4 shows the CiscoIPPhoneImage XML type.

Example C-4. CiscolPPhoneImage XML Type

Image title goes here Prompt text goes here Position information of graphic Position information of graphic Size information for the graphic Size information for the graphic Number of bits per pixel Packed Pixel Data Name of softkey URL or URI of softkey Position information of the softkey

ImageFile

Because the latest generation of Cisco IP Phones7971, 7970, 7961, and 7941, for examplehave higher-resolution displays with more color depth, the ImageFile object has been added to allow the use of color Portable Network Graphics (PNG) images. The PNG image can either be palletized or RGB. The maximum image size and the color depth differ for the various Cisco IP Phone models. For the best display results, the number of colors in the image should be matched to the capabilities of the Cisco IP Phone. Table C-27 lists the resolution and color depth supported in each of the phone models.

Example C-5 shows the CiscoIPPhoneImageFile XML type.

Example C-5. CiscoIPPhoneImageFile XML Type

Image title goes here Prompt text goes here Position information of graphic Position information of graphic Points to the PNG image

GraphicMenu

Graphic menus, like text menus, enable a user to select a menu item. The graphic menu allows a graphic to be used rather than text for the menu items. The menu item is presented as a bitmapped graphic. The user enters a menu selection by using the keypad to enter a number that selects the menu item. The XML tags for GraphicMenu are identical to the tag definitions for CiscoIPPhoneImage and CiscoIPPhoneMenu. Example C-6 shows the CiscoIPPhoneGraphicMenu XML type.

Example C-6. CiscoIPPhoneGraphicMenu XML Type

Menu title goes here Position information of graphic Position information of graphic Size information for the graphic Size information for the graphic Number of bits per pixel Packed Pixel Data Prompt text goes here The name of each menu item The URL associated with the menu item Name of softkey URL or URI of softkey Position information of the softkey

GraphicFileMenu

The GraphicFileMenu enables you to leverage the pointer devices available on some of the Cisco IP Phones, including the touch-screen overlay of the Cisco IP Phone 7971 and 7970 and the standard Windows mouse pointer for Cisco IP Communicator. The GraphicFileMenu behaves similarly to the GraphicMenu but defines touch areas for the selection rather that the keypad. Example C-7 shows the CiscoIPPhoneGraphicFileMenu XML type.

Example C-7. CiscolPPhoneGraphicMenu XML Type

Image title goes here Prompt text goes here Horizontal position of graphic Vertical position of graphic Points to the PNG background image Same as CiscoIPPhoneGraphicMenu Invoked when the TouchArea is touched

Directory

CiscoIPPhoneDirectory XML data type is used for directory-type operations. The directory entry is selected just like menu items. Up to 32 directory entries can be included in the directory. In addition, the Cisco IP Phones 7971, 7970,, 7961, 7960, 7941, 7940, 7912, and 7905 display the appropriate softkeys that are needed to initiate a call to the selected number. One softkey is EditDial, which allows the user to insert an access code or other necessary digits before dialing. The DirectoryEntry field is repeated as many times as is necessary to send all the entries to the phone. Example C-8 shows the CiscoIPPhoneDirectory XML type.

Example C-8. CiscoIPPhoneDirectory XML Type

Directory title goes here Prompt text goes here The name of the directory entry The telephone number for the entry Name of softkey URL or URI of softkey Position information of the softkey

Input

In response to a CiscoIPPhoneInput, the phone builds and displays the input form. The input form prompts the user for specific data. When the user enters the data, the phone collects that data according to the input form specifications and sends the data to the target URL. The URL tag specifies the URL to receive the results. The HTTP request sent to the server is the URL with a list of parameters appended as a query string. The parameters are name/value pairs, one pair for each input item.

Note

Cisco IP Phones do not support the HTTP POST method. POST is an HTTP method for submitting data to a web server.

The InputItem tag delimits each of the lists of input items. Each item has a DisplayName, a QueryStringParam, a DefaultValue, and a set of InputFlags. The DisplayName specifies the prompt that is written to the display for the input list item. The QueryStringParam provides the parameter name used in the URL that is returned to the server when the input is complete. The DefaultValue tag, if specified, denotes the default value to be displayed. The set of InputFlags controls the input to be used for the input item. The input types include

• APlain ASCII text. The dual-tone multifrequency (DTMF) keypad is used to enter text consisting of uppercase and lowercase letters, numbers, and special characters.
• TTelephone number. DTMF digits are the only acceptable input for this field. This includes numbers, the pound key (#), and the asterisk key (*).
• NNumeric. Numbers are the only acceptable input.
• EEquation. This includes numbers and special math symbols.
• UUppercase. This is only uppercase letters.
• LLowercase. This is only lowercase letters.
• PPassword field. Individual characters are displayed as they are keyed in using the standard keypad-repeat entry mode. As soon as each character is accepted, it is converted to an asterisk, allowing for privacy of the entered value. The password type is always a modifier to one of the other types and not used by itself. AP, for example, is valid and uses the Password field to modify the plain ASCII text field.

Example C-9 shows the CiscoIPPhoneInput XML type.

Example C-9. CiscoIPPhoneInput XML Type

Directory title goes here Prompt text goes here The target URL for the completed input goes here Name of the input field to display The URL query parameter Value Name of softkey URL or URI of softkey Position information of the softkey

Softkeys

During the entry of the text, as shown in Example C-9, the Cisco IP Phones 7971, 7970, 7961, 7960, 7941, and 7940 display softkeys that are intended to help the data-entry process. The following softkeys are used:

• SelectSelect an item for action.
• OKLeave the current page, committing any value changes made on the page.
• CancelLeave the current page, and cancel any value changes made on the page.
• ExitExit the current menu page.
• NextUse to move to the next item or page.
• BackUse to go back to the previous item or page.
• UpdateReload and update the current page.
• DialInitiate a call to the current entry selected.
• EditDialOpen an edit screen for the current entry selected.
• SubmitIndicates that the form is complete and the resulting URL should be sent by HTTP.
• <<Backspace within a field.

Field-to-field navigation can be performed with the navigation control (vertical scroll bar or 4-way control) used to navigate menus.

IPPhoneStatus

Status is a displayable object that enables you to display information on the call plane of a Cisco IP Phone. The display object is typically used by CTI applications to present status updates to the user, which can be refreshed or replaced as needed.

Example C-10 shows the CiscoIPPhoneStatus XML type.

Example C-10. CiscoIPPhoneStatus XML Type

This is the text area Timer seed value in seconds Horizontal alignment Vertical alignment Pixel width of graphic Pixel height of graphic Color depth in bits Hex binary image data

IPPhoneExecute

Use the Execute object to push a request to the phone via the web server using the HTTP POST method, providing HTTP authentication information with the POST. You can include up to three ExecuteItems in a single POST composed of URIs and URLs. You can include one URL or none in a POST, and the rest of the items, up to the maximum, are URIs as needed. The optional Priority attribute determines when the requested action is performed by the phone.

• 0Execute immediately (default priority). The URL executes regardless of the state of the phone.
• 1Execute when idle. Delay the URL execution until the phone is idle.
• 2Execute if idle. Execute the URL if the phone is idle; otherwise do not execute.

Example C-11 shows the CiscoIPPhoneExecute XML type.

Example C-11. CiscoIPPhoneExecute XML Type

IPPhoneResponse

You receive a response item for every ExecuteItem sent to the phone. The URL attribute identifies the URL or URI that you sent with the request. Data contains any special data and the Status attribute returns the status code. A status code of zero indicates no error; if an error occurs, the CiscoIPPhoneError object described below is returned. Example C-12 shows the CiscoIPPhoneResponse XML type.

Example C-12. CiscoIPPhoneResponse XML Type

IPPhoneError

The error response provides a means of returning an error status to an execute request. Example C-13 shows the CiscoIPPhoneError XML type.

Example C-13. CiscoIPPhoneError XML Type

The error response values are as follows:

• Error 1Error parsing CiscoIPPhoneExecute object. There is a syntax error in the executed code. You should correct the syntax of the object and rerun.
• Error 2Error framing CiscoIPPhoneResponse object. There is a problem rendering the object data. Review the rendering that the object attempted and make the required changes to allow it to be properly framed and rerun.
• Error 3Internal file error. You should correct the file problems encountered and rerun.
• Error 4Authentication error. You should correct the improper authentication issues and then rerun.

Phone-Supported URIs

Table C-28 and the sections that follow describe the URIs that you can use in conjunction with the XML objects with support provided by the various Cisco IP Phone models.

Key URI

With the Key URI, you are able to send an event that a key has been pressed and have the same effect as if the button had been pressed on the phone. Just as with actual keypress events, the keypress must be valid at the time of the keypress to have the desired effect.

Key: n

where n = one of the following key names:

• Key:Line1 to Key:Line36
• Key:KeyPad0 to Key:Keypad9
• Key:Soft1 to Key:Soft4 or Soft5 (to Soft5 for 7971/7970/IP Communicator only)
• 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
• Key:NavLeft
• Key:NavRight

QueryStringParam URI

The QueryStringParam URI enables you to collect more user information with less interaction. You can, for example, append a query string parameter to a highlighted menu item or apply the query string parameter from the menu item to the URL of the softkey.

QueryStringParam: d

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

RTP Streaming Control URIs

The RTP Streaming Control URIs are a collection of URIs that control media to and from the Cisco IP Phones, enabling you to instruct the phone to start or stop sending or receiving a Unicast or Multicast RTP stream. These URIs are as follows:

• RTPRx:i:p:vReceive Unicast RTP stream
• RTPRx:StopStop Unicast RTP stream receive
• RTPTx:i:pTransmit Unicast RTP stream
• RTPTx:StopStop Unicast RTP stream transmit
• RTPMRx:i:p:vReceive Multicast RTP stream
• RTPMRx:StopStop Multicast RTP stream receive
• RTPMTx:i:pTransmit Multicast RTP stream
• RTPMTx:StopStop Multicast RTP stream transmit

where:

• ithe Unicast or Multicast IP address for the transmit or receive.
• pthe Unicast or Multicast TCP port number. If specified, make sure the port number is an even number in the decimal range 20480 to 32768.
• voptional volume setting that specifies a percentage of the max volume level of the phone on the range 0100.

Init URI

The init URI allows you to initialize a feature or data:

Init: o

where o is the object name and can take on the following values:

• CallHistoryUsed to clear the call history logs and initialize missed calls, received calls, and placed calls.
• AppStatusUsed to clear the application status window, which is the window above the status line of the phone.

Dial URI

The Dial URI enables you to initiate a new call to the specified number. The URI is contained in a menu item and is invoked when the menu item is highlighted and the phone goes off-hook:

Dial: n

where n is the number to be dialed.

EditDial URI

The EditDial URI is identical in functionality to the Dial URI except that it allows the user the option of editing the number prior to placing the call:

EditDial: n

where n is the number to be dialed.

Play URI

With the Play URI, you can direct the Cisco IP Phone to download and play an audio file from the TFTP server:

Play: f

where f is the filename of a raw audio file in the TFTP path.