Table Of Contents
Cisco IP Phone Services Application Development Notes
Use this document with Cisco CallManager 3.3(2) to develop and deploy customized client services for the Cisco IP Phone 7960 and 7940 models, which support Cisco IP Phone services.
Note Developers using this guide should join the Cisco Developer Support Program because standard Cisco TAC support is limited to the Cisco AVVID installation, configuration, and Cisco-developed applications. This program provides a consistent level of dependable support while leveraging Cisco interfaces in your development projects. For more information about the program and how to join, contact us at firstname.lastname@example.org.
This document covers the following topics:
You can use Cisco IP Phones, such as the Cisco IP Phone 7960 and 7940, to deploy customized client services with which users can interact via the keypad and display. Services deploy using the HTTP protocol from standard web servers, such as Microsoft IIS. This document provides the information needed for eXtensible Markup Language (XML) and X/Open System Interface (XSI) programmers and system administrators to develop and deploy new services.
Note Currently, only Cisco IP Phone 7960 and 7940 models support Cisco IP Phone services. Throughout this document, the term "Cisco IP Phone" applies only to the Cisco IP Phone 7960 and 7940.
Cisco IP Phones have buttons labeled services and directories. When a user presses the services button, a menu of services that are configured for the phone displays. The user then chooses a service from the listing, and the phone display updates.
The following list gives typical services that might be supplied to a phone:
Figure 1 shows a sample text menu created during development.
Figure 1 Cisco IP Phone Text Menu Sample
Cisco IP Phones can also display graphic menus, as shown in Figure 2.
Figure 2 Graphic Menu on a Cisco IP Phone Sample
The way that a service is configured determines whether a graphic or text menu displays.
A phone user can navigate a text menu using the up/down rocker switch followed by the Select soft key, or by using the DTMF keypad to enter a selection directly. Graphic menus do not currently support any type of cursor-based navigation; users simply enter a numeric item selection using the DTMF keypad.
When a menu selection is made, the Cisco IP Phone acts on it by using its HTTP client to load a specific URL. The return type from this URL can be plain text or one of the CiscoIPPhone XML objects. The object loads and then interacts with the user in an appropriate manner for the object.
Figure 3 Plan Text Display Example
Figure 4 displays a graphic image.
Figure 4 Graphic Image Display Example
Cisco CallManager limits Cisco IP Phone service activity to a specific Services pane in the Cisco IP Phone display. A service cannot modify the top line of the phone display, which contains the time, date, and primary extension. A service cannot overwrite the bottom line of the display, which contains soft key definitions. The pane that displays the service sits flush with the left side of the display, and enough of the right side of the display remains intact to ensure that users can see the status of phone lines.
Note HTML Disclaimer: Phone service developers must take into consideration that the phone is not a web browser and cannot parse HTML. Although content is delivered to the phone through HTTP messages using a web server, keep in mind that the content is not HTML. All content comes either as plain text or packaged in proprietary XML wrappers.
CiscoIPPhone XML Objects
Creating interactive service applications proves relatively easy once you understand the XML objects that are defined for Cisco IP Phones and the behavior that each object generates.
Regarding services, understand that the phone does not have any concept of a state when it loads an XML page. Cisco IP Phones can use HTTP to load a page of content in many different places, starting when the services button is pressed. Regardless of what causes the phone to load a page, the phone always behaves appropriately once it loads a page.
Appropriate behavior depends solely on the type of data that has been delivered in the page. This section of the document discusses the supported XML display types and how they work with Cisco IP Phones.
See "MIME Type and Other HTTP Headers" for more information.
The following sections provide definitions and descriptions of each CiscoIPPhone XML object:
A menu on the phone comprises a list of text items, one per line. Users choose individual menu items using the exact same mechanisms that is used for built-in menus in the phone, such as those seen in the Cisco IP Phone settings pages.
Definition<CiscoIPPhoneMenu><Title>Title text goes here</Title><Prompt>Prompt text goes here</Prompt><MenuItem><Name>The name of each menu item</Name><URL>The URL associated with the menu item</URL></MenuItem><SoftKeyItem><Name>Name of soft key</Name><URL>URL or URI of soft key</URL><Position>Position information of the soft key</Position></SoftKeyItem></CiscoIPPhoneMenu>
Note The Name field under the <MenuItem> now supports 64 characters. This field can also accept two carriage returns to allow the MenuItem name to span three lines on the display.
The XML format allows you to specify a title and prompt that are used for the entire menu, followed by a sequence of
MenuItemobjects. Cisco IP Phones allow a maximum of 100
Nameand an associated
When a menu is loaded, the phone behaves exactly the same as for built-in phone menus. The user navigates through the list of menu items and eventually chooses one using either the Select soft key or the DTMF keys.
After the user chooses a menu option, the phone generates an HTTP request for the page with the URL or executes the uniform resource identifiers (URIs) associated with the menu item.
CiscoIPPhoneTextXML object displays ordinary 8-bit ASCII text on the phone display. The <Text> message must not contain any control characters, except for carriage returns, line feeds, and tabs. The Cisco IP Phone firmware controls all other pagination and wordwrap issues.
Note The Cisco IP Phone now supports the full ISO 8859-1 (Latin 1) character set.
Definition<CiscoIPPhoneText><Title>Title text goes here</Title><Prompt>The prompt text goes here</Prompt><Text>The text to be displayed as the message body goes here</Text><SoftKeyItem><Name>Name of soft key</Name><URL>URL or URI of soft key</URL><Position>Position information of the soft key</Position><SoftKeyItem></CiscoIPPhoneText>
Two optional fields can appear in the XML message:
•The first optional field,
Title, defines text that displays at the top of the display page. If a
Titleis not specified, the
Namefield of the last chosen
MenuItemdisplays in the
•The second optional field,
Prompt, defines text that displays at the bottom of the display page. If a
Promptis not specified, Cisco CallManager clears the prompt area of the display pane.
Many XML objects that are described in this document also have
Promptfields. These fields normally behave identically to behavior described in this section.
The display shown in Figure 3 provides an example of a text display. The title appears at the top above the text.
Note Non-XML Text: This document only describes the supported CiscoIPPhone XML objects. You can also deliver plain text via HTTP. Pages delivered as MIME type text/html behave exactly the same as XML pages of type
CiscoIPPhoneText. The only important difference is that you cannot include a title or prompt.
Note Keypad navigation: Cisco IP Phones allow navigation to a specific line in a menu by pressing numeric DTMF keys. When a menu is on the display, the actual number to be pressed displays on the left side of the screen.
When normal text displays, the numbers do not display on the left side of the screen, but the navigation capability still exists. So, a carefully written text service display can take advantage of this capability.
When a Cisco IP Phone receives an XML object of type
CiscoIPPhoneInput, it constructs an input form and displays it. The user then enters data into each input item and sends the parameters to the target URL. Figure 5 shows a sample display that is receiving input from a user.
Figure 5 Sample User Input Display
Definition<CiscoIPPhoneInput><Title>Directory title goes here</Title><Prompt>Prompt text goes here</Prompt><URL>The target URL for the completed input goes here</URL><InputItem><DisplayName>Name of the input field to display</DisplayName><QueryStringParam>The parameter to be added to the target URL</QueryStringParam><DefaultValue>The default display name</DefaultValue><InputFlags>The flag specifying the type of allowable input</InputFlags></InputItem><SoftKeyItem><Name>Name of soft key</Name><URL>URL or URI of soft key</URL><Position>Position information of the soft key</Position><SoftKeyItem></CiscoIPPhoneInput>
Prompttags in the object delimit text that is used in the same way as the identical fields in the other CiscoIPPhone XML objects.
URLtag delimits the URL to which the input results are sent. The actual HTTP request sent to this server specifies the URL with a list of parameters appended to it as a query string. The parameters include Name/Value pairs, one for each input item.
Note Cisco IP Phones do not use the HTTP POST method.
InputItemtag delimits each item in the list. The number of
InputItemsmust not exceed five. Each input item has a
DisplayName, which is the prompt written to the display for that particular item. Each item also has a
QueryStringParam, which is the name of the parameter appended to the URL when it is sent out after input is complete. Each input item can also use the
DefaultValuetag to set the default value to be displayed.
The final item for each input item comprises a set of
InputFlags. The following table describes the input types that are currently defined.
During text entry, Cisco IP Phones display soft keys to assist users with text entry. The soft key names are as follows:
Soft Key Name Description
Cancels the current input.
Indicates that the form is complete and that the resulting URL should be requested via HTTP.
Backspaces within a field.
Users can navigate between fields with the vertical scroll button that is used to navigate menus, and so on.
The phone actually incorporated the
CiscoIPPhoneDirectoryXML object to support the Directory operation of Cisco IP Phones. Because the functionality already exists in the phone, phone service application developers have it available as well. Figure 6 shows how an XML
CiscoIPPhoneDirectoryobject displays on the phone.
Figure 6 CiscoIPPhoneDirectory Object Display Sample
Definition<CiscoIPPhoneDirectory><Title>Directory title goes here</Title><Prompt>Prompt text goes here</Prompt><DirectoryEntry><Name>The name of the directory entry</Name><Telephone>The telephone number for the entry</Telephone></DirectoryEntry><SoftKeyItem><Name>Name of soft key</Name><URL>URL or URI of soft key</URL><Position>Position information of the soft key</Position><SoftKeyItem></CiscoIPPhoneDirectory>
Note For the directory listing, the Cisco IP Phone displays the appropriate soft keys that are needed to dial the numbers listed on the display. The soft keys include the Edit Dial soft key, which allows users to insert access codes or other necessary items before dialing.
Prompttags in the XML object have the usual semantics. A single
CiscoIPPhoneDirectoryobject can contain a maximum of 32
DirectoryEntryobjects. If more than 32 entries must be returned, use multiple
CiscoIPPhoneDirectoryobjects in subsequent HTTP requests.
You can use the "URL Directories" enterprise parameter and CiscoIPPhone XML objects to display custom directories.
The Cisco CallManager enterprise parameter "URL Directories" points to a URL that returns a
CiscoIPPhoneMenuobject that extends the directories menu. The request for "URL Directories" must return a valid
CiscoIPPhoneMenuobject, even if has no
You must use the following optional objects, if used, in the order in which they are listed:
CiscoIPPhoneInputXML object to collect search criteria.
CiscoIPPhoneTextXML object to display status messages or errors.
CiscoIPPhoneDirectoryXML object to return a list of directory entries that can be dialed.
You can omit the
CiscoIPPhoneTextobjects. You can display multiple
CiscoIPPhoneDirectoryobjects by specifying an HTTP refresh header that points to the URL of the next individual directory object, which the user accesses by pressing the Next soft key on the phone.
Cisco IP Phones include a bitmap display with a 133 x 65 pixel pane that is available to access services. Each pixel includes four greyscale settings. A value of three (3) displays as black, and a value of zero (0) displays as white.
Note The phone uses an LCD display, which explains why the palette is inverted.
CiscoIPPhoneImageXML type lets you use the Cisco IP Phone display to present graphics to the user. Figure 4 shows an example of how this looks on the current release of the Cisco IP Phone.
Definition<CiscoIPPhoneImage><Title>Image title goes here</Title><Prompt>Prompt text goes here</Prompt><LocationX>Position information of graphic</LocationX><LocationY>Position information of graphic</LocationY><Width>Size information for the graphic</Width><Height>Size information for the graphic</Height><Depth>Number of bits per pixel</Depth><Data>Packed Pixel Data</Data><SoftKeyItem><Name>Name of the soft key</Name><URL>URL of soft key</Name><Position>Numerical position of the soft key</Position><SoftKeyItem></CiscoIPPhoneImage>
CiscoIPPhoneImageobject definition includes two familiar elements:
Prompt. These elements serve the same purpose as they do in the other CiscoIPPhone XML objects. The
Titledisplays at the top of the page, and the
Promptdisplays at the bottom.
LocationYto position the graphic on the phone display. Position the upper, left corner of the graphic at the pixel defined by these two parameters. Setting the X and Y location values to (0, 0) positions the graphic at the upper, left corner of the display. Setting the X and Y location values to (-1, -1) centers the graphic in the services pane of the phone display.
Self-explanatory values include
Height. If the values specified do not match up properly with the pixel stream specified in the
Datafield, unpredictable and generally incorrect results occur.
Depthspecifies the number of bits per pixel. Cisco IP Phones support a maximum value of 2. A bit depth of 1 is black and white.
Datatag delimits a string of hexadecimal digits that contain the packed value of the pixels in the display. In the Cisco IP Phone, each pixel comprises only four possible values, which means that you can pack four pixels into a single byte. A pair of hexadecimal digits represents each byte.
Figure 7 provides an example of the mechanics of pixel packing. Scanning from left to right in the display, the illustration shows the process for packing consecutive pixel values of 1, 3, 2, and 0. First, the pixels get converted to 2-bit binary numbers. Then, the binary pairs get re-ordered in sets of four to create a single re-ordered byte, which two hexadecimal digits represent.
Figure 7 Packed Pixel Translation Example
The following XML code defines a
CiscoIPPhoneImageobject that displays the sequence of pixels shown in Figure 7 as a graphic positioned at the center of the phone display:<CiscoIPPhoneImage><Title/><LocationX>-1</LocationX><LocationY>-1</LocationY><Width>4</Width><Height>1</Height><Depth>2</Depth><Data>2D</Data><Prompt/></CiscoIPPhoneImage>
The graphic display comprises a contiguous stream of hexadecimal digits, with no spaces or other separators. If the number of pixels to be displayed does not represent an even multiple of four, pad the end of the pixel data with blank (zero value) pixels, so the data is packed correctly. The phone ignores the padded data.
Tip When graphics display on a Cisco IP Phone, the software clears the pane dedicated to services before a graphic image displays. If a service has text or other information that must be preserved, the information must get redrawn as part of the graphic.
This includes the title area. If the title is to be hidden, the graphic must be large enough to cover it.
Graphic menus serve the same purpose as text menus: they allow a user to select a URL from a list. Use graphic menus in situations when the items may not be easy to display in a text list. For example, users might prefer to have their choices presented in a non-ASCII character set such as Kanji or Arabic. Figure 2 shows a graphic menu on a Cisco IP Phone.
In these cases, the system presents the information as a bitmap graphic. The user then enters a menu selection by using the DTMF keypad to enter a number.
Definition<CiscoIPPhoneGraphicMenu><Title>Menu title goes here</Title><Prompt>Prompt text goes here</Prompt><LocationX>Position information of graphic</LocationX><LocationY>Position information of graphic</LocationY><Width>Size information for the graphic</Width><Height>Size information for the graphic</Height><Depth>Number of bits per pixel</Depth><Data>Packed Pixel Data</Data><MenuItem><Name>The name of each menu item</Name><URL>The URL associated with the menu item</URL></MenuItem><SoftKeyItem><Name>Name of soft key</Name><URL>URL of soft key</URL><Position>Numerical position of the soft key</Position><SoftKeyItem></CiscoIPPhoneGraphicMenu>
Menu items in the graphic menu have a name, just like the text menu counterparts. Although the name does not display to the user, it still performs a function. The name of the menu item provides the default title used when the URL for the chosen item is loaded. If the loaded page has a title of its own, the phone uses that title instead.
The XML tags in GraphicMenu use the tag definitions for
CiscoIPPhoneMenu. Although the semantics of the tags are identical, you can have only 12
MenuItemobjects in a
CiscoIPPhoneGraphicMenuobject. See "CiscoIPPhoneMenu" and "CiscoIPPhoneImage" for detailed descriptions.
Icon menus serve the same purpose as text menus: they allow a user to select a URL from a list. Use icon menus in situations when you want to provide additional visual information to the user to show the state or category of an item. Having a read and unread icon in a mail viewer serves as an example. The icons can convey the message state with the icon.
Figure 8 shows an IconMenu on a Cisco IP Phone.
Figure 8 IconMenu on a Cisco IP Phone Sample
In these cases, the system presents the information as a bitmap graphic to the left of the menu item text. The user selects menu items that are the same as a
Definition<CiscoIPPhoneIconMenu><Title>Title text goes here</Title><Prompt>Prompt text goes here</Prompt><MenuItem><IconIndex>Indicates what IconItem to display</IconIndex><Name>The name of each menu item</Name><URL>The URL associated with the menu item</URL></MenuItem><SoftKeyItem><Name>Name of soft key</Name><URL>URL or URI of soft key</URL><Position>Position information of the soft key</Position></SoftKeyItem><IconItem><Index>A unique index from 0 to 9</Index><Height>Size information for the icon</Height><Width>Size information for the icon</Width><Depth>Number of bits per pixel</Depth><Data>Packed Pixel Data</Data></IconItem></CiscoIPPhoneIconMenu>
The XML tags in IconMenu use the tag definitions for CiscoIPPhoneImage and CiscoIPPhoneMenu. Although the semantics of the tags are identical, you can only have 32 MenuItem objects in a
CiscoIPPhoneIconMenuobject. See "CiscoIPPhoneMenu" and "CiscoIPPhoneImage" for detailed descriptions.
CiscoIPPhoneExecuteobject differs from the other CiscoIPPhone objects. You use this object to push a request to the phone via its web server. You must use the HTTP POST method to submit the object to the phone.
You post the
CiscoIPPhoneExecuteobject to a case-sensitive URL. The URL http://x.x.x.x/CGI/Execute, replaces the x.x.x.x with the IP address of the destination Cisco IP Phone. The form that you post should have a case-sensitive form field name called "XML" that contains the XML object that you are posting. You can post multiple requests in a single object and receive a ResponseItem for each ExecuteItem.
When posting a
CiscoIPPhoneExecuteobject to a phone you must provide basic HTTP authentication information with the POST. The credentials that you provide must be that of a user in the global directory with a device association with the target phone. If the credentials are invalid, or the Authentication URL is not set properly in the Cisco CallManager administration, the phone will return a CiscoIPPhoneError with a value of 4 (Authentication Error).
Note Limit the requests to three ExecuteItems: only one can be a URL and two URIs per
CiscoIPPhoneExecuteobject. Or you can send three URIs with no URL.
Definition<CiscoIPPhoneExecute><ExecuteItem URL="the URL or URI to be executed"/><CiscoIPPhoneExecute>
ResponseItems exist for all ExecuteItems that you send. The order differs according to completion time and the execution order is not guaranteed. The URL attribute specifies the URL or URI that was sent with the request. The Data attribute contains any special data for the item. The Status attribute specifies a status code. Zero indicates that no error occurred during processing of the ExecuteItem. If an error occurred, the phone returns a
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>
The following list gives possible CiscoIPPhoneError codes:
•Error 1 = Error parsing
•Error 2 = Error framing
•Error 3 = Internal file error
•Error 4 = Authentication error
CiscoIPPhone XML Object Quick Reference
Table 1 provides a quick reference of the CiscoIPPhone XML objects and the definitions associated with each.
The XML parser in Cisco IP Phones does not function as a fully capable XML parser. Do not include any tags other than those defined in your XML display definitions.
Note All CiscoIPPhone element names and attribute names are case sensitive.
Mandatory Escape Sequences
By XML convention, the XML parser also requires that you escape a few special characters. Table 2 lists characters and their escape values.
Table 2 Escape Sequences for Special Characters
Character Name Escape Sequence
Left angle bracket
Right angle bracket
Escaping text can be tedious, but some authoring tools or scripting languages can automate this task.
Custom Soft Keys
Cisco IP Phones now have the ability to receive custom soft keys with the CiscoIPPhone objects. Soft keys can have URLs or URIs associated with them. Newly created URIs allow you to call the native softkey event with a custom soft key.
XML Objects Used With Nonstreaming URIs
This section describes objects that you use in what context with nonstreaming URIs and what, if any, comprise the object order requirements.
The following list contains the XML objects that can be used:
URIs for Pressing Buttons on the Phone
The Key URI allows a programmer to send an event that a key has been pressed. The same event is fired as when the physical buttons are pressed. The phone hook switch is not exposed since this would cause the hardware to be out of sync with the software.
Note While pressing buttons with this method, the button may not be available when the URI is processed and the event is thrown away as a result.
Example 1 Key:Soft1
If the soft key set is changing and disabled while the event is being processed, the request is discarded.
Verification of available soft keys is achieved with the QA web pages provided by the phones web server that indicate the active soft key set.
n is a Key name. The following is a complete listing of the Key URIs:
•Key:Line1 to Key:Line34
•Key:KeyPad0 to Key:KeyPad9
•Key:Soft1 to Key:Soft4
URIs for Invoking SoftKey Functionality
An XSI developer can execute native soft key functionality when the phone executes a SoftKey URI. The primary purpose for the SoftKey URI is to allow developers the ability to customize soft key names and layout in the Services and Directories windows while retaining the functionality that the soft keys provide.
SoftKey URIs work in menu items, soft key items, and execute items that are pushed to the phone. The SoftKey URIs use is limited to the objects on which they natively occur on the phone.
n is one of the following soft key names:
Valid soft key actions for each XSI object type follow. The URI invokes the native functionality that each key possesses in the given object context.
–SoftKey:Search—only when used under the Directories button
–SoftKey:Next—only when used under the Directories button
Generic URIs that can be used in place of URLs follow:
•Dial:2000 (where 2000 represents the number to be dialed)
•EditDial:2000 (where 2000 represents the number to load into the edit dial context)
The QueryStringParam URI allows an application developer to collect more information from the user with less interaction. When the user performs an action with a soft key, you can either append a query string parameter to the URL of the highlighted MenuItem or append the query string parameter from the MenuItem to the URL of the soft key.
d = the data to be appended to a corresponding URL.
Example 2 QueryStringParam URI in a CiscoIPPhoneMenu object<CiscoIPPhoneMenu><Title>Message List</Title><Prompt>Two Messages</Prompt><MenuItem><Name>Message One</Name><URL>QueryStringParam:message=1</URL></MenuItem><MenuItem>Name>Message Two</Name><URL>queryStringParam:message=2</URL></MenuItem><SoftKeyItem><Name>Read</Name><URL>http://server/read.asp</URL></SoftkeyItem><SoftKeyItem><Name>Delete</Name><URL>http://server/delete.asp</URL></SoftkeyItem></CiscoIPPhoneMenu>
Example 2 shows how to use the QueryStringParam URI in a
CiscoIPPhoneMenuobject has two MenuItems with QueryStringParam URIs. If the user selects the MenuItem(s) with the numeric keypad, the cursor moves to that entry but nothing executes because the values are QueryStringParam URIs.
If the user presses either of the custom soft keys, the currently highlighted MenuItem URI value is appended to the soft key URL that was pressed and requested from the web server.
If you highlight the first MenuItem and press the Read soft key, the phone generates the following URL:
Example 3 Selecting an Item with Numeric Keypad calls the URL<CiscoIPPhoneMenu><Title>Message List</Title><Prompt>Two Messages</Prompt><MenuItem><Name>Messae One</Name><URL>http://server/messages.asp?message=1</URL></MenuItem><MenuItem><Name>Messae Two</Name><URL>http://server/messages.asp?message=2</URL></MenuItem><SoftKeyItem><Name>Read</Name><URL>QueryStringParam:action=read</URL></SoftKeyItem><SoftKeyItem><Name>Delete</Name><URL>QueryStringParam:action=delete</URL></SoftKeyItem></CiscoIPPhoneMenu>
The Cisco IP Phones allow you to implement the QueryStringParam URI in either manner. However, Example 3 is not as efficient as Example 2. Choose the best way to perform the action based on your applications needs.
Example 3 does have a slight advantage in that if the user selects an item with the numeric keypad, the URL is called. This would allow you to invoke some default behavior such as to read the message in the example. By highlighting the first message and pressing the Read soft key, the phone creates the following URL:
Using the QueryStringParam URI reduces the size of the XML objects that you generate by not having to repeat redundant portions of a URL in every MenuItem.
URIs to Control RTP Streaming
It is possible to invoke RTP streaming via URIs in services. You can instruct the phone to transmit or receive an RTP stream with the following specifications.
The supported format of the RTP stream follows:
•The codec is G.711 mu-Law.
•The packet size is 20 ms.
The RTPRx URI instructs the phone to receive a Unicast RTP stream or to stop receiving Unicast or Multicast RTP streams.
i is the IP Address from which the stream is coming
p is the TCP port on which to receive the RTP stream. This must be an even port number within the decimal range of 20480 to 32768. If no port is specified, the phone chooses a port and returns it when initiated by a push request.
Stop is the parameter that will stop any active RTP stream from being received on channel one.
The RTPTx URI is used to instruct the phone to transmit a Unicast RTP stream or to stop transmitting Unicast or Multicast RTP streams.
i is the IP Address to transmit an RTP stream to.
p is the TCP port on which to transmit the RTP stream. This must be an even port number within the decimal range of 20480 to 32768.
Stop is the parameter that will stop any active RTP stream from being transmitted on channel one.
The RTPMRx URI instructs the phone to receive a Multicast RTP
i is the Multicast IP Address from which to receive an RTP stream.
p is the Multicast TCP port from which to receive the RTP stream. This must be an even port number within the decimal range of 20480 to 32768.
The RTPMTx URI instructs the phone to transmit a Multicast RTP stream.
i is the Multicast IP Address to transmit an RTP stream to.
p is the Multicast TCP port on which to transmit the RTP stream. This must be an even port number within the decimal range of 20480 to 32768.
This section describes the following miscellaneous URIs:
The Init URI allows an application to initialize a feature or data with the argument that is passed with the URI.
o is the Object name.
Valid object name:
CallHistory—When the phone encounters an Init:CallHistory URI, it clears the internal call history logs that are stored in the phone. This initializes Missed Calls, Received Calls, and Placed Calls.
The Dial URI initiates a new call to a specified number. The Dial URI invokes when it is contained in a menu item, the menu item is highlighted, and the device is taken off hook.
Activate the Dial URI by one of the following:
•Handset hook switch
•Normal menu item
•Soft key item selection
n is the number dialed (such as Dial:1000).
The EditDial URI initiates a new call to a specified number. The EditDial URI invokes when it is contained in a menu item, the menu item is highlighted, and the device is taken off hook.
Activate the EditDial URI by one of the following:
•Handset hook switch
•Normal menu item
•Soft key item selection
n is the number dialed (such as EditDial:1000).
The Play URI downloads an audio file from the TFTP server and plays through the phone speaker. This is the same mechanism that is used to play ring files. The format of the files is the same. You could use the Play URI to play files that are in the Ringlist.xml or those that are not.
If you want to achieve a unique audible notification, use a file that is not available from the Ringlist.xml.
f is the filename of a raw audio file in the TFTP path (such as Play:Classic2.raw).
Cisco IP Services Software Development Kit (SDK)
The Cisco IP Services Software Development Kit (SDK) contains everything that is needed to create XML applications, including necessary documentation and sample applications.
The following list contains the components included in the SDK:
–Cisco IP Phone Services Application Development Notes (this document) in Adobe .pdf format
–Cisco URL Proxy Guide in rich text format
–Cisco LDAP Programming Guide in Microsoft Word format
–Cisco CIP Image Release Notes in Microsoft Word format
–Cip.8bi—Photoshop plug-in that allows .cip extensions to be viewed and saved.
–Cip2Gif.exe—DOS-based program that converts .cip files to .gif.
–Gif2Cip.exe—DOS-based program that converts .gif files to .cip.
–ImageViewer.exe—Windows application that displays .cip graphic files.
–Cisco URL Proxy—Proxy server that is needed to use the sample services (automatically installed).
–Cisco LDAP Search—Service that is installed to do LDAP searches (automatically installed).
•Calendar—A graphical calendar
•LDAP—www interface for Cisco LDAP Search
•Real-time Stock Ticker—Stock quote
•Stock Chart—Stock graphic that charts a stock symbol
•Airline flight information
•Foreign currency exchange
–Windows Scripting (WSH)
•Cip—A command line windows scripting graphic conversion example using ActiveX.
Sample Services Requirements
The following list contains the items that are required for the sample services to work properly:
•Cisco IP 7940/7960 IP Phone
•Microsoft IIS 4.0 or higher (for sample services)
•Windows Scripting (for WSH example code)
The setup program installs a CiscoServices web project to c:\CiscoIpServices directory. The sample services get copied to the c:\CiscoIpServices\Services subdirectory, and IIS and WSH example codes are provided. The web server already senses these services; you need no further administration. You can view or edit all the source code with any text editor. The c:\CiscoIpServices\Documentation directory provides further documentation. Find tools to help develop services in c:\CiscoIpServices\Tools.
HTTP Client Requests
The following procedure designates how HTTP client requests are handled:
•The Cisco IP Phone HTTP client performs an HTTP GET for a specified URL.
•The HTPP server processes request and returns an XML object or plain text.
•The phone processes the supported HTTP headers.
•The phone parses the XML object if ContentType is
•The phone presents data and options to the user per the server response.
HTTP Header Settings
The following list provides definitions for HTTP header elements for Cisco IP Phone services:
•"Refresh" (Time in Seconds, URL)
–If no time is set or it is zero, the refresh gets set to manual.
–If no URL is set, the current URL gets used.
See "HTTP Refresh Setting" for details.
•"ContentType" — The ContentType notifies the phone of the MIME type that was sent. See "MIME Type and Other HTTP Headers".
•"Expires" — Expires sets the Date/Time in GMT when the page is to expire.
Pages that have expired before being loaded do not get added to the URL stack in the phone. The phone does not cache content. See "Content Expiration Header Setting" for more information.
HTTP Refresh Setting
The HTTP headers that are sent with any page from an HTTP server can include a Refresh setting. This setting comprises two parameters: a time in seconds and a URL. These two parameters direct the recipient to wait the time given in the seconds parameter and then get the data to which the URL points.
The Cisco IP Phone HTTP client properly supports this setting, which gives a great deal of power to service developers. It means that a new page can replace any XML object that displays after a fixed time.
Figure 9 shows a good example of how to use the refresh setting. This sample page shows the current value of Cisco stock to the user.
1. A splash screen that displays the Yahoo logo.
2. After a very short time, it displays the numeric Cisco stock parameters.
3. Finally, it shows a graph of Cisco intraday stock performance. The display then repeatedly cycles between the final two views.
Figure 9 Refresh Display Sample
Refreshing the display can occur without user intervention, as the display automatically cycles if a timer parameter is specified. However, on any given screen, the user can force an immediate reload by pressing the Update soft key. Also, if a timer parameter of 0 was sent in the header, the page never automatically reloads. In this case, the display will move to the next page only when the Update soft key is pressed. If no refresh URL is specified, the current page gets reloaded.
MIME Type and Other HTTP Headers
Usually, you can set the MIME type for pages in any web server by simply performing an association to the .xml file extension. Your web server documentation should explain how to accomplish this. This action allows you to serve static pages without the need for writing script.
If you want to deliver dynamic content using the other supported HTTP headers, you will need to understand how to generate the HTTP headers using the desired programming language and have common gateway interface (CGI) or script access on the target web server.
It is possible to serve audio clips to the phone from a web server using the "audio/basic" MIME type setting. When this MIME type is used, the body of the response should contain raw audio data in the same format that is used for custom Cisco IP Phone rings. Refer to the chapter on "Custom Phone Rings" in the Cisco CallManager System Guide (also available in the online help).
Note The audio file should not be longer than 5 seconds in length.
The advantage of using script to generate the MIME header when playing a sound is that you may also include a refresh header to take the phone to a subsequent URL. Usually, you can set the MIME type for pages in any web server by simply performing an association to the .xml or .raw file extension. Your web server documentation should explain how to accomplish this. This action allows you to serve static pages without the need for writing script.
Content Expiration Header Setting
The expiration header can control what URLs are added to the phone URL history. This behavior differs slightly from traditional web browsers but is implemented to perform the same function. Disable the back button functionality to avoid calling a URL twice.
This functionality allows you to make the content of any page that is sent to the phone expire. When a user presses the Exit soft key, the user goes back to the last URL that did not expire when it was loaded. This differs from traditional browsers by not considering the current freshness of the data but the freshness of the data when the URL was requested. This requires you to have a page expire when it is first loaded and to not set a time and date in the future.
The "Expires" property specifies the number of minutes to wait for the content to expire. Setting this value to -1 subtracts 1 minute from the request time and returns a date and time that have already passed.
IP Phone Service Administration and Subscription
Cisco CallManager administrators maintain the list of services to which users can subscribe. Add and administer Cisco IP Phone services through Cisco CallManager Administration:
•To access phone service administration, open Cisco CallManager Administration and choose Feature > Cisco IP Phone Services.
•Phone services can have any number of parameters associated with them.
•You can specify phone service parameters as optional or required, depending on how the phone service application defines them.
•Users can subscribe to any service configured in their cluster.
•Service subscriptions currently occur on a device basis.
A URL constitutes the core of each service. When a service is chosen from the menu, the URL is requested via HTTP, and a server somewhere provides the content. The Service URL field shows this URL entry. For the services to be available, the phones in the Cisco CallManager cluster must have network connectivity to the server.
Where <servername> designates a fully qualified domain name or an IP address.
Adding a Phone Service
Figure 10 shows the pane that the administrator uses to add new services to the system:
•To access this pane in Cisco CallManager Administration, choose Feature > Cisco IP Phone Services.
•You can insert, update, or delete a service definition.
•After a service is inserted, you can insert, update, or delete service parameter definitions.
•When you delete a Cisco IP Phone subscription, Cisco CallManager removes all service information, user subscriptions, and user subscription data from the database.
•The Update Subscriptions button rebuilds all user subscriptions if the service has been modified after subscriptions exist.
Caution Do not put Cisco IP Phone services on any Cisco CallManager server at your site or any server associated with Cisco CallManager, such as the TFTP server or directory database publisher server. This precaution eliminates the possibility of errors in a Cisco IP Phone Service application having an impact on Cisco CallManager performance or interrupting call-processing services.
Figure 10 Adding a New Service in Cisco CallManager Administration
Defining IP Phone Service Parameters in Cisco CallManager Administration
Each service can have a list of parameters. You can use these parameters, which are appended to the URL when they are sent to the server, to personalize a service for an individual user. Examples of parameters include stock ticker symbols, city names, or user IDs. The service provider defines the semantics of a parameter. The Cisco IP Phone Service Parameter Configuration pane in Cisco CallManager Administration contains the following fields:
Tip If you change the service URL, remove a Cisco IP Phone service parameter, or change the Parameter Name of a phone service parameter for a phone service to which users are already subscribed, be sure to click Update Subscriptions to update all currently subscribed users with the changes. If you do not do so, users must resubscribe to the service to rebuild the URL correctly.
Figure 11 displays an example Cisco IP Phone Service Parameter Configuration pane in Cisco CallManager Administration.
Figure 11 Defining Service Parameters in Cisco CallManager Administration
User Service Subscription
User service subscriptions get configured with the CCMUser web site after the user has logged in and chosen a device.
The end user has a single list of services that are attached to an individual phone. The user configures this list of services via the user pages, which are also used to set speed-dial numbers and call-forwarding options. These password-protected pages get authenticated via the LDAP directory.
Users use these user configuration panes to assign values to the service parameters, allowing for personalization:
•The user can customize the name of the service when it displays on the services list.
•The user can enter any service parameters that are available for the chosen service.
•The user can review the description of each parameter.
•After all the required fields are set, the user can click Subscribe.
•A custom URL gets built and stored in the database for this subscription.
•The service then appears on the device services list.
Figure 12 Cisco CallManager User Subscription Screen
Figure 13 Personalizing a User Subscription
Figure 14 Personalizing a User Subscription Completed
The following tips apply to troubleshooting Cisco IP Phone service applications:
•Microsoft Internet Explorer 5 or higher can display the XML source with its default style sheet.
•Understand that standard IP troubleshooting techniques are important for HTTP errors.
•Externally verify name resolution (Phone has DNS set).
•If DNS is suspected, use IP addresses in URLs.
•Browse the URL in question with IE5 or download and verify with Netscape.
Use a logged telnet session to verify that the desired HTTP headers are returned (Telnet to the server on port 80; then, enter get /path/page).
XML Parsing Errors
The following tips apply to troubleshooting XML parsing errors in Cisco IP Phone services applications:
•Verify the object tags (the object tags are case-sensitive).
•Verify that "&" and the other four special characters are used per the restrictions while inside the XML objects. See "Mandatory Escape Sequences" for more information.
The following error messages may appear on the prompt line of the Cisco IP Phone display.
XML Error = XML Parser error (Invalid Object)
•HTTP Error = Unknown HTTP Error
HTTP Error = HTTP Connection Failed
Refer to the Cisco IP Phone Administration Guide for Cisco CallManager for more information.
The following documents provide further information:
•Cisco CallManager Administration Guide (also available in the online help). Refer to the chapter on configuring Cisco IP Phone services.
•Cisco CallManager System Guide (also available in the online help).
•Cisco IP Phone 7960/7940 Quick Start Guide
Provides instructions for users on subscribing to phone services.
•Cisco IP Phone Administration Guide for Cisco CallManager
Provides administration information for Cisco IP Phones.
•CiscoURLProxy ActiveX Component
Provided with the Cisco IP Services SDK.
•LDAP Search COM Server Programming Guide
Provided with the Cisco IP Services SDK.
•CipImage Release Notes
Provided with the Cisco IP Services SDK.
Obtaining Technical Assistance
Cisco provides Cisco.com as a starting point for all technical assistance. Customers and partners can obtain online documentation, troubleshooting tips, and sample configurations from online tools by using the Cisco Technical Assistance Center (TAC) Web Site. Cisco.com registered users have complete access to the technical support resources on the Cisco TAC Web Site.
Cisco.com is the foundation of a suite of interactive, networked services that provides immediate, open access to Cisco information, networking solutions, services, programs, and resources at any time, from anywhere in the world.
Cisco.com is a highly integrated Internet application and a powerful, easy-to-use tool that provides a broad range of features and services to help you with these tasks:
•Streamline business processes and improve productivity
•Resolve technical issues with online support
•Download and test software packages
•Order Cisco learning materials and merchandise
•Register for online skill assessment, training, and certification programs
If you want to obtain customized information and service, you can self-register on Cisco.com. To access Cisco.com, go to this URL:
Technical Assistance Center
The Cisco Technical Assistance Center (TAC) is available to all customers who need technical assistance with a Cisco product, technology, or solution. Two levels of support are available: the Cisco TAC Web Site and the Cisco TAC Escalation Center.
Cisco TAC inquiries are categorized according to the urgency of the issue:
•Priority level 4 (P4)—You need information or assistance concerning Cisco product capabilities, product installation, or basic product configuration.
•Priority level 3 (P3)—Your network performance is degraded. Network functionality is noticeably impaired, but most business operations continue.
•Priority level 2 (P2)—Your production network is severely degraded, affecting significant aspects of business operations. No workaround is available.
•Priority level 1 (P1)—Your production network is down, and a critical impact to business operations will occur if service is not restored quickly. No workaround is available.
The Cisco TAC resource that you choose is based on the priority of the problem and the conditions of service contracts, when applicable.
Cisco TAC Web Site
You can use the Cisco TAC Web Site to resolve P3 and P4 issues yourself, saving both cost and time. The site provides around-the-clock access to online tools, knowledge bases, and software. To access the Cisco TAC Web Site, go to this URL:
All customers, partners, and resellers who have a valid Cisco service contract have complete access to the technical support resources on the Cisco TAC Web Site. The Cisco TAC Web Site requires a Cisco.com login ID and password. If you have a valid service contract but do not have a login ID or password, go to this URL to register:
If you are a Cisco.com registered user, and you cannot resolve your technical issues by using the Cisco TAC Web Site, you can open a case online by using the TAC Case Open tool at this URL:
If you have Internet access, we recommend that you open P3 and P4 cases through the Cisco TAC Web Site.
Cisco TAC Escalation Center
The Cisco TAC Escalation Center addresses priority level 1 or priority level 2 issues. These classifications are assigned when severe network degradation significantly impacts business operations. When you contact the TAC Escalation Center with a P1 or P2 problem, a Cisco TAC engineer automatically opens a case.
To obtain a directory of toll-free Cisco TAC telephone numbers for your country, go to this URL:
Before calling, please check with your network operations center to determine the level of Cisco support services to which your company is entitled: for example, SMARTnet, SMARTnet Onsite, or Network Supported Accounts (NSA). When you call the center, please have available your service agreement number and your product serial number.
This document is to be used in conjunction with the documents listed in the "Related Documentation" section.
CCIP, the Cisco Arrow logo, the Cisco Powered Network mark, the Cisco Systems Verified logo, Cisco Unity, Follow Me Browsing, FormShare, iQ Breakthrough, iQ Expertise, iQ FastTrack, the iQ Logo, iQ Net Readiness Scorecard, Networking Academy, ScriptShare, SMARTnet, TransPath, and Voice LAN are trademarks of Cisco Systems, Inc.; Changing the Way We Work, Live, Play, and Learn, Discover All That's Possible, The Fastest Way to Increase Your Internet Quotient, and iQuick Study are service marks of Cisco Systems, Inc.; and Aironet, ASIST, BPX, Catalyst, CCDA, CCDP, CCIE, CCNA, CCNP, Cisco, the Cisco Certified Internetwork Expert logo, Cisco IOS, the Cisco IOS logo, Cisco Press, Cisco Systems, Cisco Systems Capital, the Cisco Systems logo, Empowering the Internet Generation, Enterprise/Solver, EtherChannel, EtherSwitch, Fast Step, GigaStack, Internet Quotient, IOS, IP/TV, LightStream, MGX, MICA, the Networkers logo, Network Registrar, Packet, PIX, Post-Routing, Pre-Routing, RateMUX, Registrar, SlideCast, StrataView Plus, Stratm, SwitchProbe, TeleRouter, and VCO are registered trademarks of Cisco Systems, Inc. and/or its affiliates in the U.S. and certain other countries.
All other trademarks mentioned in this document or Web site are the property of their respective owners. The use of the word partner does not imply a partnership relationship between Cisco and any other company. (0208R)
Copyright © 2002, Cisco Systems, Inc.
All rights reserved.