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.