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.

Table C-14. JTAPI Core Package Support

Class Name

Method Name

Comments

Address

addCallObserver

 

addressObserver

getAddressCapabilities

getCallObservers

getCapabilities

getConnections

getName

getObservers

getProvider

getTerminals

removeCallObserver

removeObserver

AddressObserver

addressChangedEvent

 

Call

addObserver

 

connect

A CallObserver must exist for the terminal or address originating the call.

getCallCapabilities

 

getCapabilities

getConnections

getObservers

getProvider

getState

removeObserver

CallObserver

callChangedEvent

 

Connection

disconnect

 

getAddress

getCall

getCapabilities

getConnectionCapabilities

getState

getTerminalConnections

JtapiPeer

getName

 

getProvider

getServices

JtapiPeerFactory

getJtapiPeer

 

Provider

addObserver

 

createCall

getAddress

getAddressCapabilities()

getAddressCapabilities(Terminal)

getAddresses

getCallCapabilities()

getCallCapabilities(Terminal, Address)

getCalls

This method returns calls only when there are CallObservers attached to addresses or terminals, when a RouteAddress is registered for routing, or when a CiscoMedia Terminal is registered.

getCapabilities

 

getConnectionCapabilities()

getConnectionCapabilities(Terminal, Address)

getName

getObservers

getProviderCapabilities()

getProviderCapabilities(Terminal)

getState

getTerminal

getTerminalCapabilities()

getTerminalCapabilities(Terminal)

getTerminalConnectionCapabilities()

getTerminalConnectionCapabilities (Terminal)

getTerminals

removeObserver

shutdown

ProviderObserver

providerChangedEvent

 

Terminal

addCallObserver

 

addObserver

getAddresses

getCallObservers

getCapabilities

getName

getObservers

getProvider

getTerminalCapabilities

getTerminalConnections

removeCallObserver

removeObserver

TerminalConnection

answer

 

getCapabilities

getConnection

getState

getTerminal

getTerminalConnectionCapabilities

TerminalObserver

terminalChangedEvent

 

 

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.

Table C-15. JTAPI Call Center Package Support

Class Name

Method Name

Cisco JTAPI Support

ACDAddress

getACDManagerAddress

No

getLoggedOnAgents

No

getNumberQueued

No

getOldestCallQueued

No

getQueueWaitTime

No

getRelativeQueueLoad

No

ACDAddressObserver

 

No

ACDConnection

getACDManagerConnection

No

ACDManagerAddress

getACDAddresses

No

ACDManagerConnection

getACDConnections

No

Agent

getACDAddress

No

getAgentAddress

No

getAgentID

No

getAgentTerminal

No

getState

No

setState

No

AgentTerminal

addAgent

No

getAgents

No

removeAgents

No

setAgents

No

AgentTerminalObserver

 

No

CallCenterAddress

addCallObserver

No

CallCenterCall

connectPredictive

No

getApplicationData

No

getTrunks

No

setApplicationData

No

CallCenterCallObserver

 

No

CallCenterProvider

getACDAddresses

No

getACDManagerAddresses

No

getRouteableAddresses

No

CallCenterTrunk

getCall

No

getName

No

getState

No

getType

No

RouteAddress

cancelRouteCallback

Yes

getActiveRouteSessions

Yes

getRouteCallback

Yes

registerRouteCallback

Yes

RouteCallback

reRouteEvent

Yes

routeCallbackEndedEvent

Yes

routeEndEvent

Yes

routeEvent

Yes

routeUsedEvent

Yes

RouteSession

endRoute

Yes

getCause

Yes

getRouteAddress

Yes

getState

Yes

selectRoute

Yes

 

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.

Table C-16. JTAPI Call Center Capabilities Package Support

Class Name

Method Name

Cisco JTAPI Support

ACDAddressCapabilities

canGetACDManagerAddress

No

canGetLoggedOnAgents

No

canGetNumberQueued

No

canGetOldestCallQueued

No

canGetQueueWaitTime

No

canGetRelativeQueueLoad

No

ACDConnectionCapabilities

canGetACDManagerConnection

No

ACDManagerAddressCapabilities

canGetACDAddresses

No

ACDManagerConnectionCapabilities

canGetACDConnections

No

AgentTerminalCapabilities

canHandleAgents

No

CallCenterAddressCapabilities

canAddCallObserver

No

CallCenterCallCapabilities

canConnectPredictive

No

canGetTrunks

No

canHandleApplicationData

No

CallCenterProviderCapabilities

canGetACDAddresses

Yes

canGetACDManagerAddresses

Yes

canGetRouteableAddresses

Yes

RouteAddressCapabilities

canRouteCalls

Yes

 

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.

Table C-17. JTAPI Call Center Events Package Support

Class Name

Method Name

Cisco JTAPI Support

ACDAddrBusyEv

 

No

ACDAddrEv

getAgent

No

getAgentAddress

No

getAgentTerminal

No

getState

No

getTrunks

No

ACDAddrLoggedOffEv

 

No

ACDAddrLoggedOnEv

 

No

ACDAddrNotReadyEv

 

No

ACDAddrReadyEv

 

No

ACDAddrUnknownEv

 

No

ACDAddrWorkNotReadyEv

 

No

ACDAddrWorkReadyEv

 

No

AgentTermBusyEv

 

No

AgentTermEv

getACDAddress

No

getAgent

No

getAgentAddress

No

getAgentID

No

getState

No

AgentTermLoggedOffEv

 

No

AgentTermLoggedOnEv

 

No

AgentTermNotReadyEv

 

No

AgentTermReadyEv

 

No

AgentTermUnknownEv

 

No

AgentTermWorkNotReadyEv

 

No

AgentTermWorkReadyEv

 

No

CallCentCallAppDataEv

getApplicationData

No

CallCentCallEv

getCalledAddress

No

getCallingAddress

No

getCallingTerminal

No

getLastRedirectedAddress

No

getTrunks

No

CallCentConnEv

 

No

CallCentConnInProgressEv

 

No

CallCentEv

getCallCenterCause

No

CallCentTrunkEv

getTrunk

No

CallCentTrunkInvalidEv

 

No

CallCentTrunkValidEv

 

No

ReRouteEvent

 

Yes

RouteCallbackEndedEvent

getRouteAddress

Yes

RouteEndEvent

 

Yes

RouteEvent

getCallingAddress

Yes

getCallingTerminal

Yes

getCurrentRouteAddress

Yes

getRouteSelectAlgorithm

Yes

getSetupInformation

Yes

RouteSessionEvent

getRouteSession

Yes

RouteUsedEvent

getCallingAddress

Yes

getCallingTerminal

Yes

getDomain

Yes

getRouteUsed

Yes

 

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.

Table C-18. JTAPI Call Control Package Support

Class Name

Method Name

Cisco JTAPI Support

Comments

CallControlAddress

cancelForwarding

Yes

Only for Call Forward All.

getDoNotDisturb

No

 

getForwarding

Yes

Only for Call Forward All.

getMessageWaiting

No

 

setDoNotDisturb

No

 

setForwarding

Yes

Only for Call Forward All.

setMessageWaiting

No

 

CallControlCall

addParty

No

 

conference

Yes

In a consultation conference scenario where the conference controller speaks with the potential conference participant prior to adding the participant to the conference, only OriginalCall.conference (ConsultCall) is supported. ConsultCall.conference (OriginalCall) is not supported.

CallControlCall

consult(TerminalConnection)

Yes

 

consult(TerminalConnection, String)

Yes

 

drop

Yes

 

getCalledAddress

Yes

 

getCallingAddress

Yes

 

getCallingTerminal

Yes

 

getConferenceController

Yes

 

getConferenceEnable

Yes

 

getLastRedirectedAddress

Yes

 

getTransferController

Yes

 

getTransferEnable

Yes

 

offHook

Yes

 

setConferenceController

Yes

 

setConferenceEnable

Yes

 

setTransferController

Yes

 

setTransferEnable

Yes

 

transfer(Call)

Yes

In a consultation transfer scenario, only OriginalCall.transfer (ConsultCall) is supported. ConsultCall.transfer (OriginalCall) is not supported.

transfer(String)

Yes

 

CallControlCallObserver

 

Yes

 

CallControlConnection

accept

Yes

 

addToAddress

Yes

 

getCallControlState

Yes

 

park

Yes

 

redirect

Yes

Redirect allows a connection in the state, CallControlConnection. ESTABLISHED, to be redirected.

reject

Yes

 

CallControlForwarding

getDestinationAddress

No

 

getFilter

No

 

getSpecificCaller

No

 

getType

No

 

CallControlTerminal

getDoNotDisturb

No

 

pickup (Address, Address)

No

 

pickup (Connection, Address)

No

 

pickup (TerminalConnection, Address)

No

 

pickupFromGroup(Address)

No

 

pickupFromGroup(String, Address)

No

 

setDoNotDisturb

No

 

CallControlTerminal Connection

getCallControlState

Yes

 

hold

Yes

 

join

No

 

leave

No

 

unhold

Yes

 

CallControlTerminal Observer

 

No

 

 

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.

Table C-19. JTAPI Call Control Capabilities Package Support

Class Name

Method Name

CallControlAddressCapabilities

canCancelForwarding

canGetDoNotDisturb

canGetForwarding

canGetMessageWaiting

canSetDoNotDisturb

canSetForwarding

canSetMessageWaiting

CallControlCallCapabilities

canAddParty

canConference

canConsult

canConsult(TerminalConnection)

canConsult(TerminalConnection, String)

canDrop

canOffHook

canSetConferenceController

canSetConferenceEnable

canSetTransferController

canSetTransferEnable

canTransfer

canTransfer(Call)

canTransfer(String)

CallControlConnectionCapabilities

canAccept

canAddToAddress

canPark

canRedirect

canReject

CallControlTerminalCapabilities

canGetDoNotDisturb

canPickup

canPickup(Address, Address)

canPickup(Connection, Address)

canPickup(TerminalConnection, Address)

canPickupFromGroup

canPickupFromGroup(Address)

canPickupFromGroup(String, Address)

canSetDoNotDisturb

CallControlTerminalConnectionCapabilities

canHold

canJoin

canLeave

canUnhold

 

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.

Table C-20. JTAPI Call Control Events Package Support

Class Name

Method Name

Cisco JTAPI Support

CallCtlAddrDoNotDisturbEv

getDoNotDisturbState

No

CallCtlAddrEv

 

No

CallCtlAddrForwardEv

getForwarding

Yes

CallCtlAddrMessageWaitingEv

getMessageWaitingState

No

CallCtlCallEv

getCalledState

Yes

getCallingAddress

Yes

getCallingTerminal

Yes

getLastRedirectedAddress

Yes

CallCtlConnAlertingEv

 

Yes

CallCtlConnDialingEv

getDigits

Yes

CallCtlConnDisconnectedEv

 

Yes

CallCtlConnEstablishedEv

 

Yes

CallCtlConnEv

 

Yes

CallCtlConnFailedEv

 

Yes

CallCtlConnInitiatedEv

 

Yes

CallCtlConnNetworkAlertingEv

 

Yes

CallCtlConnNetworkReachedEv

 

Yes

CallCtlConnOfferedEv

 

Yes

CallCtlConnQueuedEv

getNumberInQueue

Yes

CallCtlConnUnknownEv

 

Yes

CallCtlEv

getCallControlCause

Yes

CallCtlTermConnBridgedEv

 

No

CallCtlTermConnDroppedEv

 

Yes

CallCtlTermConnEv

 

Yes

CallCtlTermConnHeldEv

 

Yes

CallCtlTermConnInUseEv

 

No

CallCtlTermConnRingingEv

 

Yes

CallCtlTermConnTalkingEv

 

Yes

CallCtlTermConnUnknownEv

 

Yes

CallCtlTermDoNotDisturbEv

 

No

CallCtlTermEv

 

No

 

Capabilities Package

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

Table C-21. JTAPI Capabilities Package Support

Class Name

Method Name

AddressCapabilities

isObservable

CallCapabilities

canConnect

 

isObservable

ConnectionCapabilities

canDisconnect

ProviderCapabilities

isObservable

TerminalCapabilities

isObservable

TerminalConnectionCapabilities

canAnswer

 

Events Package

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

Table C-22. JTAPI Events Package Support

Class Name

Method Name

Cisco JTAPI Support

AddrEv

getAddress

Yes

AddrObservationEndedEv

 

Yes

CallActiveEv

 

Yes

CallEv

getCall

Yes

CallInvalidEv

 

Yes

CallObservationEndedEv

getEndedObject

Yes

ConnAlertingEv

 

Yes

ConnConnectedEv

 

Yes

ConnCreatedEv

 

Yes

ConnDisconnectedEv

 

Yes

ConnEv

getConnection

Yes

ConnFailedEv

 

Yes

ConnInProgressEv

 

Yes

ConnUnknownEv

 

Yes

Ev

getCause

Yes

getID

Yes

getMetaCode

Yes

getObserved

Yes

isNewMetaEvent

Yes

ProvEv

getProvider

Yes

ProvInServiceEv

 

Yes

ProvObservationEndedEv

 

Yes

ProvOutOfServiceEv

 

Yes

ProvShutdownEv

 

Yes

TermConnActiveEv

 

Yes

TermConnCreatedEv

 

Yes

TermConnDroppedEv

 

Yes

TermConnEvgetTerminalConnection

 

Yes

TermConnPassiveEv

 

No

TermConnRingingEv

 

Yes

TermConnUnknownEv

 

Yes

TermEv

getTerminal

Yes

TermObservationEndedEv

 

Yes

 

Media Package

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

Table C-23. JTAPI Media Package Support

Class Name

Method Name

Cisco JTAPI Support

MediaCallObserver

 

Yes

MediaTerminalConnection

generateDtmf

Yes

getMediaAvailability

No

getMediaState

No

setDtmfDetection

Yes

startPlaying

No

startRecording

No

stopPlaying

No

stopRecording

No

useDefaultMicrophone

No

useDefaultSpeaker

No

usePlayURL

No

useRecordURL

No

 

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.

Table C-24. JTAPI Media Capabilities Package Support

Class Name

Method Name

MediaTerminalConnectionCapabilities

canDetectDtmf

canGenerateDtmf

canStartPlaying

canStartRecording

canStopPlaying

canStopRecording

canUseDefaultMicrophone

canUseDefaultSpeaker

canUsePlayURL

canUseRecordURL

 

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.

Table C-25. JTAPI Media Events Package Support

Class Name

Method Name

Cisco JTAPI Support

MediaEv

getMediaCause

Yes

MediaTermConnAvailableEv

 

No

MediaTermConnDtmfEv

getDtmfDigit

Yes

MediaTermConnEv

 

Yes

MediaTermConnStateEv

getMediaState

No

MediaTermConnUnavailableEv

 

No

 

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.

Table C-26. Data Tag Digits

Pixels

1

3

2

0

Binary Value

01

11

10

00

Reordered Pairs

00

10

11

01

Hex Digits

2

 

D

 

Packed Value

2D

     

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.

Table C-27. Display Size and Color Depth

Model

Resolution Width x Height

Color/Grayscale

Color Depth (Bits)

7905/7912

Does not support DisplayImage

N/A

1

7920

128 x 59

Grayscale

1

7940/7960

133 x 65

Grayscale

2

7941/7961

298 x 144

Grayscale

4

7970/7971

298 x 168

Color

12

IP Communicator

298 x 168

Color

24

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.

Table C-28. URIs Supported

Phone Model URI

7905/7912

7920

7940/7960

7941/7961

797x/IP Communicator

Key

X

X

X

X

X

SoftKey

X

X

X

X

X

Init

 

X

X

X

X

Dial, EditDial

X

X

X

X

X

Play

X

X

X

X

X

QueryStringParam

 

X

X

X

X

Unicast RTP (RTPRx,RTRTx)

v parameter not supported

v parameter not supported; single stream in/out

X

X

X

Multicast RTP (RTPMRx,RTRMTx)

v parameter not supported

 

X

X

X

 

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.

Cisco CallManager Architecture

Call Routing

Station Devices

Trunk Devices

Media Processing

Manageability and Monitoring

Call Detail Records

Appendix A. Feature List

Appendix B. Cisco Integrated Solutions

Appendix C. Protocol Details

Index



Cisco CallManager Fundamentals
Cisco CallManager Fundamentals (2nd Edition)
ISBN: 1587051923
EAN: 2147483647
Year: 2004
Pages: 141

Flylib.com © 2008-2020.
If you may any questions please contact us: flylib@qtcs.net