Cisco Unified IP Phone Services Application Development Notes Supporting XML Applications Release 8.5(1) Americas Headquarters Cisco Systems, Inc. 170 West Tasman Drive San Jose, CA 95134-1706 USA http://www.cisco.
THE SPECIFICATIONS AND INFORMATION REGARDING THE PRODUCTS IN THIS MANUAL ARE SUBJECT TO CHANGE WITHOUT NOTICE. ALL STATEMENTS, INFORMATION, AND RECOMMENDATIONS IN THIS MANUAL ARE BELIEVED TO BE ACCURATE BUT ARE PRESENTED WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. USERS MUST TAKE FULL RESPONSIBILITY FOR THEIR APPLICATION OF ANY PRODUCTS.
C O N T E N T S Preface vii Overview vii Audience vii Organization viii Related Documentation ix Document Conventions x Cisco Developer Network xi Obtaining Documentation and Submitting a Service Request Cisco Product Security Overview CHAPTER 1 Overview CHAPTER 2 New and Changed Information CHAPTER 3 xi xi 1-1 2-1 New Information for Unified CM 8.5(1) 2-1 New Information for Unified CM 8.
Contents CiscoIPPhoneExecute 3-27 CiscoIPPhoneResponse 3-28 CiscoIPPhoneError 3-29 Custom Softkeys 3-29 XML Considerations 3-30 Mandatory Escape Sequences XML Encoding 3-31 Application Event Handlers CHAPTER 4 Component APIs 3-30 3-31 4-1 Supported Phone Models 4-1 Application Management API 4-2 RTP Streaming API 4-3 Interaction Rules with Legacy RTP URI Streams RTP Streaming Schema 4-3 Error Schema 4-5 Examples 4-6 Errors and Responses 4-7 CHAPTER 5 Internal URI Features 4-3 5-1 Support
Contents Dial 5-15 EditDial 5-16 SendDigits 5-17 Application Management URIs Init 5-18 Notify 5-18 Application 5-20 CHAPTER 6 5-18 HTTP Requests and Header Settings HTTP Client Requests (HTTP GET) 6-1 6-1 HTTP Server Requests (HTTP POST) 6-1 HTTP Header Settings 6-2 HTTP Refresh Setting 6-3 MIME Type and Other HTTP Headers 6-4 Audio Clips 6-4 Content Expiration Header Setting 6-4 Set-Cookie Header Setting 6-5 HTTP Encoding Header Setting 6-6 HTTP Response Headers: Content-Type Identifying the Capab
Contents CHAPTER IP Phone Service Administration and Subscription 9 Accessing Phone Service Administration Adding a Phone Service User Service Subscription 10 DeviceListX Report Benefits 9-1 9-2 Defining IP Phone Service Parameters CHAPTER 9-3 9-4 10-1 10-2 Restrictions 10-2 Integration Considerations and Interoperability Performance and Scalability Security 10-3 Supported Platforms Prerequisites 10-3 10-3 10-3 Message and Interface Definitions DeviceList XML Object 10-3 10-3 Troubl
Preface This preface includes the following sections: • Overview, page vii • Audience, page vii • Organization, page viii • Related Documentation, page ix • Document Conventions, page x • Cisco Developer Network, page xi • Obtaining Documentation and Submitting a Service Request, page xi • Cisco Product Security Overview, page xi Overview Use this document with Cisco Unified Communications Manager, Release 8.
Preface Organization This document comprises the following sections: Chapter Description Chapter 1, “Overview” Provides an overview of the Cisco Unified IP Phone services for developers. Chapter 2, “New and Changed Information” Provides details on the new and changed information in the XML service interface for the latest release of Cisco Unified Communication Manager. Chapter 3, “CiscoIPPhone XML Objects” Describes the general behavior and usage of each XML object.
Preface Related Documentation For more information about Cisco Unified IP Phones or Cisco Unified Communications Manager, refer to the following publications: Cisco Unified IP Phone 6900 Series These publications are available at the following URL: http://www.cisco.com/en/US/products/ps10326/tsd_products_support_series_home.html Cisco Unified IP Phone 7900 Series These publications are available at the following URL: http://www.cisco.com/en/US/products/hw/phones/ps379/tsd_products_support_series_home.
Preface Document Conventions This document uses the following conventions: Convention Indication bold font Commands and keywords and user-entered text appear in bold font. italic font Document titles, new or emphasized terms, and arguments for which you supply values are in italic font. [ ] Elements in square brackets are optional. {x | y | z } Required alternative keywords are grouped in braces and separated by vertical bars.
Preface Cisco Developer Network The Cisco Developer Network (CDN) portal provides access to multiple Cisco technology developer interfaces and collaborative support communities. CDN also provides formalized support services for these interfaces to enable developers, customers, and partners to accelerate their development. The formalized process provides access to CDN Engineers who are an extension of the product technology engineering teams.
Preface Cisco Unified IP Phone Services Application Development Notes xii OL-22505-01
CH A P T E R 1 Overview You can use Cisco Unified IP Phones 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. Users access these features using the services and directories buttons or menu options (availability varies by phone model). When a user presses the services button (or chooses the services menu item), a menu of configured services displays.
Chapter 1 Figure 1-2 Overview Graphic Menu on a Cisco Unified IP Phone Sample Phone users can navigate a text menu by using the Navigation button followed by the Select softkey, or by using the numeric keypad to enter a selection directly. Graphic menus currently do not support cursor-based navigation; users simply enter a number using the DTMF keypad. When a menu selection is made, the Cisco Unified IP Phone acts on it by using its HTTP client to load a specific URL.
Chapter 1 Overview 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 by 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.
Chapter 1 Overview Cisco Unified IP Phone Services Application Development Notes 1-4 OL-22505-01
CH A P T E R 2 New and Changed Information This chapter gives details on the new and changed information in the latest XML IP Phone services interface for Cisco Unified Communication Manager. New Information for Unified CM 8.5(1) • Added information on WinodwMode attribute in the following sections: – CiscoIPPhoneImage – CiscoIPPhoneImageFile – CiscoIPPhoneGraphicMenu – CiscoIPPhoneGraphicFileMenu • Added information on the new Cisco IP Phone 6945. New Information for Unified CM 8.
Chapter 2 New and Changed Information New Information for Unified CM 8.
CH A P T E R 3 CiscoIPPhone XML Objects The following sections describe the general behavior and use of XML objects: • Understanding Object Behavior • XML Object Definitions • Custom Softkeys • XML Considerations • Application Event Handlers Understanding Object Behavior Creating interactive service applications is relatively easy when you understand the XML objects that are defined for Cisco Unified IP Phones and the behavior that each object generates.
Chapter 3 CiscoIPPhone XML Objects Understanding Object Behavior Table 3-1 shows the supported XML objects for this release. Table legend: Table 3-1 • —Supported • —Not supported XML Objects Supported for Release 8.
Chapter 3 CiscoIPPhone XML Objects XML Object Definitions XML Object Definitions The following sections provide definitions and descriptions of each CiscoIPPhone XML object: • CiscoIPPhoneMenu • CiscoIPPhoneText • CiscoIPPhoneInput • CiscoIPPhoneDirectory • CiscoIPPhoneImage • CiscoIPPhoneImageFile • CiscoIPPhoneGraphicMenu • CiscoIPPhoneGraphicFileMenu • CiscoIPPhoneIconMenu • CiscoIPPhoneIconFileMenu • CiscoIPPhoneStatus • CiscoIPPhoneStatusFile • CiscoIPPhoneExecute • CiscoIP
Chapter 3 CiscoIPPhone XML Objects XML Object Definitions When a menu is loaded, the phone behaves the same as for built-in phone menus. The user navigates through the list of menu items and eventually chooses one by using either the Select softkey or the DTMF keys. After the user chooses a menu option, the phone generates an HTTP request for the page with the URL or executes the uniform resource identifiers (URIs) that are associated with the menu item.
Chapter 3 CiscoIPPhone XML Objects XML Object Definitions CiscoIPPhoneInput When a Cisco Unified 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 3-1 shows a sample display that is receiving input from a user.
Chapter 3 CiscoIPPhone XML Objects XML Object Definitions InputFlag Description A Plain ASCII text—use the DTMF keypad to enter text that consists of uppercase and lowercase letters, numbers, and special characters. T Telephone number—enter only DTMF digits for this field. The acceptable input includes numbers, #, and *. N Numeric—enter numbers as the only acceptable input. E Equation—enter numbers and special math symbols. U Uppercase—enter uppercase letters as the only acceptable input.
Chapter 3 CiscoIPPhone XML Objects XML Object Definitions Note For the directory listing, the Cisco Unified IP Phone displays the appropriate softkeys that are needed to dial the numbers that are listed on the display. The softkeys include the Edit Dial softkey, which allows users to insert access codes or other necessary items before dialing. The Title and Prompt tags in the XML object have the usual semantics.
Chapter 3 CiscoIPPhone XML Objects XML Object Definitions Packed Pixel Data Name of the soft key URL of soft key Numerical position of the soft key WindowMode is an optional attribute used to set the width of an XSI application window. This attribute is supported on the 7941, 7942, 7945, 7961, 7962, 7965, 7970, 7971, and 7975 phone models .
Chapter 3 CiscoIPPhone XML Objects XML Object Definitions The Data tag delimits a string of hexadecimal digits that contain the packed value of the pixels in the display. In the Cisco Unified IP Phone, each pixel has only four possible values, which means that you can pack four pixels into a single byte. A pair of hexadecimal digits represents each byte. Figure 3-4 provides an example of the mechanics of pixel packing.
Chapter 3 CiscoIPPhone XML Objects XML Object Definitions • Image Object 0 20 133 45 1 f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0 Image Object CiscoIPPhoneImage object with WindowMode set to normal. See Figure 3-5.
Chapter 3 CiscoIPPhone XML Objects XML Object Definitions Figure 3-6 CiscoIPPhoneImage Object with WindowMode Wide CiscoIPPhoneImageFile The latest generation of Cisco Unified IP Phones have higher-resolution displays with more color depth. The Cisco Unified IP Phone 7970G, for example, has a display area of 298x168 pixels available to the Services pane and renders images in 12-bit color.
Chapter 3 CiscoIPPhone XML Objects XML Object Definitions Table 3-2 Cisco Unified IP Phones Display Image Sizes and Color Depths (continued) Model Resolution in Resolution1 Wide Mode Color/Grayscale (width x height) (width x height) /Monochrome Color Depth (bits) Cisco Unified IP Phone 7937G 255x128 N/A Grayscale 2 Cisco Unified IP Phones 7940G/60G 133 x 65 N/A Grayscale 2 Cisco Unified IP Phones 7941G, 7941G-GE, 7942G, 7961G, 7961G-GE, 7962G 298 x 144 320 x 144 Grayscale 4 Cisco Unifi
Chapter 3 CiscoIPPhone XML Objects XML Object Definitions Image File Object 0 0 http://10.74.63.74:8080/xsi/normal1.png • With WindowMode attribute set to Normal. See Figure 3-8. Image File Object Image File Object 297 0 http://10.74.63.74:8080/xsi/normal1.
Chapter 3 CiscoIPPhone XML Objects XML Object Definitions CiscoIPPhoneGraphicMenu Graphic menus serve the same purpose as text menus: they allow a user to select a URL from a list. Use graphic menus in situations when the items may not be easy to display in a text list. For example, users might prefer to have their choices presented in a non-ASCII character set such as Kanji or Arabic. When using non-ASCII character sets, the system presents the information as a bitmap graphic.
Chapter 3 CiscoIPPhone XML Objects XML Object Definitions • With WindowMode attribute set to Normal. See Figure 3-10.
Chapter 3 CiscoIPPhone XML Objects XML Object Definitions Figure 3-11 WindowMode Attribute Set to Wide CiscoIPPhoneGraphicFileMenu Some of the Cisco Unified IP Phone models, such as the Cisco Unified IP Phone 7970G and Cisco IP Communicator, have pointer devices. The Cisco Unified IP Phone 7970G uses a touchscreen overlay on the display, and the PC-based Cisco IP Communicator uses the standard Windows mouse pointer.
Chapter 3 CiscoIPPhone XML Objects XML Object Definitions The requirements for the PNG image referenced by the tag match those that the CiscoIPPhoneImageFile object uses.
Chapter 3 CiscoIPPhone XML Objects XML Object Definitions Figure 3-13 • CiscoIPPhoneGraphicFileMenu With WindowMode attribute set to Wide. See Figure 3-14 Graphic File Menu Graphic File Menu 0 0 http://10.74.63.74:8080/xsi/wide3.
Chapter 3 CiscoIPPhone XML Objects XML Object Definitions Figure 3-15 IconMenu on a Cisco Unified IP Phone Sample The system presents the information as a bitmap graphic to the left of the menu item text. The user selects menu items in the same way as a CiscoIPPhoneMenu object.
Chapter 3 CiscoIPPhone XML Objects XML Object Definitions This icon menu is similar to CiscoIPPhoneMenu, but it uses color PNG icons rather than grayscale CIP icons. Use icon menus in situations when you want to provide additional visual information to the user to show the state or category of an item. For example, you can use icons to indicate priority (see Figure 3-16). Icons in the CiscoIPPhoneIconFileMenu object have a maximum width of 18 pixels and a maximum height of 18 pixels.
Chapter 3 CiscoIPPhone XML Objects XML Object Definitions • Schema Definition, page 3-22 • Example, page 3-22 • Valid Resource Icon Names, page 3-23 • Troubleshooting, page 3-24 Supported IP Phones and Codecs Table 3lists the Cisco Unified IP Phone models that support the Enhanced Icon Menu Support feature: Table legend: • —Supported • —Not supported Table 3 Phone Models that Support the Enhanced Icon Menu Support Feature Phone Model Supported/Not Supported Firware Supported1 9900 Series
Chapter 3 CiscoIPPhone XML Objects XML Object Definitions Table 3 Phone Models that Support the Enhanced Icon Menu Support Feature Phone Model Supported/Not Supported Firware Supported1 7921 — 7925/7925G-EX — 7926 — 6900 Series Phones 6921 — 6941 — 6945 — 6961 — Other Devices Cisco IP Phone Communicator — 1. Cisco recommends the use of latest firmware. The firmware can be downloaded from the following location (requires login and/or service contract): http://tools.cisco.
Chapter 3 CiscoIPPhone XML Objects XML Object Definitions Conference List 1 Resource:Icon.SecureCall 2 Resource:Icon.Connected 3 Resource:AnimatedIcon.Ringin
Chapter 3 CiscoIPPhone XML Objects XML Object Definitions • AnimatedIcon.Ringin • AnimatedIcon.Hold • AnimatedIcon.MessageWaiting • AnimatedIcon.StreamingRx • AnimatedIcon.StreamingTx • AnimatedIcon.StreamRxTx • AnimatedIcon.Throbber Troubleshooting The following errors and conditions may occur in this feature: • If the CiscoIPPhoneIconFileMenu object is invalid, a parsing error is generated and a CiscoIPPhoneError object (with Number="1") is returned as the response.
Chapter 3 CiscoIPPhone XML Objects XML Object Definitions Figure 3-17 IconMenu on a CiscoIPPhoneStatus Sample Definition 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 Note The 6900 series IP phone
Chapter 3 CiscoIPPhone XML Objects XML Object Definitions To allow dynamic sizing, do not configure the Text and Timer areas with any value other than the default used by the XML parser. If both elements are not configured, you can proceed, but must follow these rules: • Do not display the Text Area and Timer Area sections of the Application Status window.
Chapter 3 CiscoIPPhone XML Objects XML Object Definitions Figure 3-19 shows how an XML Figure 3-19 CiscoIPPhoneStatusFile object displays on a phone.
Chapter 3 CiscoIPPhone XML Objects XML Object Definitions The tag of the CiscoIPPhoneExecute object includes an optional attribute called Priority. The Priority attribute is used to inform the phone of the urgency of the execute request and to indicate whether the phone should be interrupted to perform the request. The Priority levels determine whether the phone must be idle to perform the requested action.
Chapter 3 CiscoIPPhone XML Objects Custom Softkeys CiscoIPPhoneError The following list gives possible CiscoIPPhoneError codes: • Error 1 = Error parsing CiscoIPPhoneExecute object • Error 2 = Error framing CiscoIPPhoneResponse object • Error 3 = Internal file error • Error 4 = Authentication error Definition optional error message The text value of the CiscoIPPhoneError object may contain an optional error message to further describe the nature
Chapter 3 CiscoIPPhone XML Objects XML Considerations If any custom softkeys are defined in the XML object, then all default softkeys are removed from that object. To retain default softkey behavior, then you must explicitly define it in the XML object using a tag. The internal Softkey URIs can be used in the tag of to invoke default softkey actions from custom softkeys. See Chapter 5, “Internal URI Features” for more information on invoking internal softkey features.
Chapter 3 CiscoIPPhone XML Objects Application Event Handlers XML Encoding Because the phone firmware can support multiple encodings, the XML encoding should always be set in the XML header. If the XML encoding header is not specified, the phone will default to the encoding specified by the current user locale.
Chapter 3 CiscoIPPhone XML Objects Application Event Handlers Note Support for the Application Event Handlers requires an updated XML Parser (see “Updated XML Parser and Schema Enforcement” section on page B-1 for details). Attributes The Application Event Handlers can be attached to a supported object by specifying the attributes: Note An Application URI with Priority=0 is not allowed in the Application Event Handlers (see “Application” section on page 5-20).
Chapter 3 CiscoIPPhone XML Objects Application Event Handlers Attribute Description onAppMinimized Invoked when the application is minimized. An application can only be minimized programmatically by a call to App:Minimize, but this invocation could occur by direct action of the user (from a softkey invocation, for example) or from the application via a push request.
Chapter 3 CiscoIPPhone XML Objects Application Event Handlers Event Handler Schema PAGE 53CH A P T E R 4 Component APIs In addition to the primary phone XSI API, the following two additional component APIs are available: • Application Management API • RTP Streaming API This section contains information on the following topics: • Supported Phone Models, page 4-1 • Application Management API, page 4-2 • RTP Streaming API, page 4-3 Supported Phone Models Table 1 lists the Cisco Unified IP Phone models that support the component APIs.
Chapter 4 Component APIs Application Management API Table 1 Phone Models that Support the Component APIs Phone Model Supported/Not Supported Firware Supported1 7940G — 7941G/7941G-GE 8.3(2) or later 7942G 8.3(2) or later 7945G 8.3(2) or later 7960G — 7961G/7961G-GE 8.3(2) or later 7962G 8.3(2) or later 7965G 8.3(2) or later 7970G 8.3(2) or later 7971G-GE 8.3(2) or later 7975G 8.
Chapter 4 Component APIs RTP Streaming API Note Support for the Application Management API requires an updated XML Parser (see “Updated XML Parser and Schema Enforcement” section on page B-1 for details). RTP Streaming API This XML-based RTP Streaming API allows applications to initiate and observe RTP audio streams.
Chapter 4 Component APIs RTP Streaming API PAGE 57Chapter 4 Component APIs RTP Streaming API PAGE 58Chapter 4 Component APIs RTP Streaming API <
Chapter 4 Component APIs RTP Streaming API If the user terminates the media stream by placing the active audio path on-hook, the following notification is sent: HTTP POST /server/path/page DATA= Errors and Responses Error conditions and responses for the RTP Streaming API include: Condition Applicable Methods HTTP Result Code Authorization failed Request object does not comply with the API’s XML schema Type
Chapter 4 Component APIs RTP Streaming API Cisco Unified IP Phone Services Application Development Notes 4-8 OL-22505-01
CH A P T E R 5 Internal URI Features Internal uniform resource identifiers (URIs) provide access to embedded phone features such as placing calls, playing audio files, and invoking built-in object features.
Chapter 5 Internal URI Features Device Control URIs Table 5-1 URIs Supported for Release Cisco Unified IP Phone Services SDK (continued) 7905G 7912G URI 7906G 7911G 7931G 7920G 7921G 7925G 7925GEX 7926G 7937G 7940G 7960G 7941G/7941G-GE, 7961G/7961G-GE, 7942G, 7962G, 7945G, 7965G, 7970G IP 7971G-GE Communicator 7975G 6921, 6941, 6945 6961 9971, 9951, 8961 5 Unicast RTP Multicast RTP Display Vibrate Notify6 SendDigits6 Application6 Device 1.
Chapter 5 Internal URI Features Device Control URIs Key The Key URI allows a programmer to send an event that a key has been pressed. The system initiates the event as if the button was physically pressed. Note that when buttons are pressed with this method, if the button is not present on the phone (hard button) or not available (softkey) when the URI is processed, the event is discarded. If the softkey set is changing and disabled while the event is being processed, the request is discarded.
Chapter 5 Internal URI Features Device Control URIs Table 5-2 Key URIs With Supported Phone Models 7905G 7912G Key URIs 7906G 7911G 7931G 7920G 7921G 7925G 7925GEX 7926G 7937G 7940G 7960G 7941G/7941GGE, 7961G/7961GGE, 7942G, 7962G, 7945G, 7965G, 7970G IP 7971G-GE Communicator 7975G 6921, 6941, 6945, 6961 9971, 9951, 8961 Key:Line1 to Key:Line120 Key:Messages Key:Mute Key:NavBack Key:NavDwn Key:NavLeft Key:NavRight Key:NavSelect Key:NavUp Key:Offhook Key:Onhook Key:PTT Key:Release Key:Services
Chapter 5 Internal URI Features Device Control URIs Table 5-3 Unsupported Key URIs and Alternative Options Phone Models Unsupported URI 9971, 9951, 8961 Key:Services The 8900 and 9900 series IP phones does not have a services button. As such, the “Key:Services” URI is not supported in these phones. The application has to use the “Init:Services” URI and the “App:Close” URI to close the last XSI application launched from the application. If there is no application open, then the request has no effect.
Chapter 5 Internal URI Features Device Control URIs Display The Display URI is available only on those Cisco Unified IP Phones that have a color backlight on the phone display, including the Cisco Unified IP Phone 7970G and 7971G-GE. Using the Display URI, you can control how long the backlight remains on or off. Note, however, that other administrator-controlled or user-indicated display settings take precedence over the Display URI.
Chapter 5 Internal URI Features XML Displayable Object URIs XML Displayable Object URIs These sections describe the XML displayable object URIs: • SoftKey • QueryStringParam SoftKey You can execute native softkey functionality when the phone executes a Softkey URI. The SoftKey URI allows developers to customize softkey names and layout in the Services and Directories windows while retaining the functionality that the softkeys provide.
Chapter 5 Internal URI Features XML Displayable Object URIs Table 5-4 Valid Softkey Actions for CiscoIPPhoneObject Types (continued) Edit Select Exit Update Submit Search << Cancel Next Dial Dial IPPhoneObject1 CiscoIPPhoneImage X X CiscoIPPhoneGraphicMenu X X CiscoIPPhoneInput X X2 X CiscoIPPhoneDirectory X X X X3 X3 1. The SoftKey URI is not allowed in an Execute object. 2. Only when used under the Directories button. 3.
Chapter 5 Internal URI Features XML Displayable Object URIs Delete http://server/delete.asp Example 5-1 shows how to use the QueryStringParam URI in a CiscoIPPhoneMenu object. The CiscoIPPhoneMenu object includes two MenuItems with QueryStringParam URIs. If the user chooses the MenuItem(s) with the numeric keypad, the cursor moves to that entry, but nothing executes because the values are QueryStringParam URIs.
Chapter 5 Internal URI Features Multimedia URIs Multimedia URIs These sections describe the multimedia URIs: • RTP Streaming • Play • Vibrate RTP Streaming You can invoke RTP streaming via URIs in services. You can instruct the phone to transmit or receive an RTP stream with the following specifications: Note • RTPRx • RTPTx • RTPMRx • RTPMTx For some Cisco Unified IP Phone models, the RTP Streaming URIs have been deprecated by the RTP Streaming API.
Chapter 5 Internal URI Features Multimedia URIs The user has no explicit mechanism for terminating the Rx or MRx URI stream independent of the call. Thus, if the Rx or MRx stream is not terminated automatically, it would continue to play. For example, a user is listening to Internet radio feed and gets an incoming call. The user answers the call, which either closes or minimizes the Internet radio XSI application. Otherwise, the user has no intuitive way to stop the music stream.
Chapter 5 Internal URI Features Multimedia URIs RTPTx Use the RTPTx URI to instruct the phone to transmit a Unicast RTP stream or to stop transmitting Unicast or Multicast RTP streams. URI Formats RTPTx:i:p RTPTx:Stop Where i = the IP Address to which an RTP stream is transmit ed. p = the UDP port on which to transmit the RTP stream. Ensure that this is an even port number within the decimal range of 20480 to 32768.
Chapter 5 Internal URI Features Multimedia URIs Play The Play URI downloads an audio file from the TFTP server and plays through the phone speaker. This same mechanism also plays ring files, and 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 the phone is equipped with an MWI light, it will be flashing while the audio file is playing, providing a visual alert as well. Note The Play URI is a synchronous request.
Chapter 5 Internal URI Features Multimedia URIs URI Format Vibrate:vibrateDuration:silenceDuration:count Where vibrateDuration = duration (in milliseconds) in which the vibrate state remains on. Value must be an integer ranging from 0-65536 milliseconds. silenceDuration = duration (in milliseconds) in which the vibrate state remains off. Value must be an integer ranging from 0-65536 milliseconds. count = number of times to repeat the vibrate on and off sequence.
Chapter 5 Internal URI Features Telephony URIs Please go to room 1234. Accept http:///AlertResponse.jsp?reason=accept Busy http:///AlertResponse.jsp?reason=busy Error and Response When the Device URI is invoked via an Execute object, it uses the standard URI Status and Data values in the ResponseItems.
Chapter 5 Internal URI Features Telephony URIs Where dialSequence—The sequence of DTMF digits to be dialed. Commas represent 1 second pauses. Value Type: String Values: minLength=0, no maxLength, can only contain 0123456789#*ABCD, Default value: N/A useAppUI—Specifies whether or not this application will be used as the user interface for this call. A value of true will cause the application to keep UI focus when the call is made instead of switching to the Call UI application.
Chapter 5 Internal URI Features Telephony URIs SendDigits The SendDigits URI instructs the phone to send a specified sequence of DTMF digits in-band within the media stream of the current active (streaming) call. Audible feedback to the user can be enabled or disabled and an optional application ID can be specified to ensure that the DTMF digits will only be sent to the call which is associated with a specific application.
Chapter 5 Internal URI Features Application Management URIs Condition Status Data Unable to execute URI because the current active (streaming) call is not associated with the specified application 6 (Internal error) No Active Call for Application Phone is temporarily unable to execute URI due to some other transient issue 6 (Internal error) Application Management URIs These sections describe the application management URIs: • Init • Notify • Application Init The Init URI allows an
Chapter 5 Internal URI Features Application Management URIs You can also specify the Notify URI in place of most fields that accept a generic URI, including softkeys and menu items. For example, you can call the Notify URI from a softkey or menu item to trigger a back-end event that does not require an interface change, such as manipulating the state of audio streams or other non-visual resources.
Chapter 5 Internal URI Features Application Management URIs DATA= • Called from SoftKey, with credentials, with data: Notify:http:myserver:8080:path/streamhandler?event=stopped: 8fh4hf7s7dhf :myStreamStoppedData HTTP POST /path/streamhandler?event=stopped HTTP/1.
Chapter 5 Internal URI Features Application Management URIs Note The other component of the Application Management API is the Application Management Event Handler, see the “Application Event Handlers” section on page 3-31 for details. When an Application URI request is made, it has a specific application associated with it (not just the application context) and that action can only be taken on that specific application.
Chapter 5 Internal URI Features Application Management URIs – If the requested application is open, but not currently active, this request will not succeed (error response). This request will result in the application context (and all applications within that context) being closed. – If the application has focus when this URI executes, the onAppFocusLost event handler will be invoked prior to the onAppClosed event handler (which will always be invoked).
CH A P T E R 6 HTTP Requests and Header Settings Cisco Unified IP Phones use HTTP to communicate to external applications. The phone firmware includes both an HTTP client for making requests, and an HTTP server for receiving requests. This chapter describes the capabilities of the HTTP interface.
Chapter 6 HTTP Requests and Header Settings HTTP Header Settings The form that is posted should have a case-sensitive form field name called “XML” that contains the desired XML object. For any HTTP POST operation, the server must provide basic HTTP authentication information with the POST. The provided credentials must be of a user in the global directory with a device association with the target phone.
Chapter 6 HTTP Requests and Header Settings HTTP Header Settings 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.
Chapter 6 HTTP Requests and Header Settings HTTP Header Settings MIME Type and Other HTTP Headers Although delivering pages with the proper MIME type and other formatting items is not difficult, it requires moderately in depth knowledge of your web server. The following code excerpt, written in JavaScript and used with Microsoft IIS and ASP, sets these values in a few lines: <%@ Language=JavaScript %> <% Response.AddHeader( "Refresh", "3; url=http://services.cisco.com/s/q.asp"); Response.
Chapter 6 HTTP Requests and Header Settings HTTP Header Settings This functionality allows you to make the content of any page that is sent to the phone expire. When a user presses the Exit softkey, 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.
Chapter 6 HTTP Requests and Header Settings HTTP Header Settings HTTP Encoding Header Setting The encoding header controls language and character settings related to localization. Accept-Language Cisco Unified IP Phones populate the Accept-Language HTTP request header in compliance with the HTTP specification.
Chapter 6 HTTP Requests and Header Settings Identifying the Capabilities of IP Phone Clients If 'charset' is not specified, the phones will use the default encoding for the currently configured user locale. So to avoid possible problems where the phone's default encoding may NOT be ISO-8859-1, the web server should explicitly set the Content-Type charset (which must match one of the Accept-Charset values specified by the phone).
Chapter 6 HTTP Requests and Header Settings Accept Header x-CiscoIPPhoneSDKVersion This Cisco-proprietary header contains the version of the IP Phone Services SDK that the requesting phone supports. The HTTP header does not specify which URIs are supported. Therefore, you must check the “Supported URIs” matrix in the IP Phone Services SDK to determine which URIs are supported based on the Phone Model Name and supported SDK version.
Chapter 6 HTTP Requests and Header Settings Accessing IP Phone Information Accessing IP Phone Information Cisco Unified IP Phones have an embedded web server to provide a programming interface for external applications and a debugging and management interface for system administrators. You can access the administrative pages using a standard web browser and pointing to the IP address of the phone with: /http:///, where phoneIP is the IP address of the specific phone.
Chapter 6 HTTP Requests and Header Settings Accessing IP Phone Information Cisco Unified IP Phone Services Application Development Notes 6-10 OL-22505-01
CH A P T E R 7 Troubleshooting Cisco Unified IP Phone Service Applications This chapter contains the following sections: • Troubleshooting Tips • XML Parsing Errors • Error Messages Troubleshooting Tips The following tips apply to troubleshooting Cisco Unified 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.
Chapter 7 Troubleshooting Cisco Unified IP Phone Service Applications Error Messages – CiscoIPPhoneMenu Object—If the field is missing for a
CH A P T E R 8 Cisco IP Phone Services Software Development Kit (SDK) The Cisco IP Phone Services Software Development Kit (SDK) contains everything that you require to create XML applications, including necessary documentation and sample applications. Contact Cisco Developer Services to obtain the SDK at: http://developer.cisco.
Chapter 8 Cisco IP Phone Services Software Development Kit (SDK) SDK Components • Development Tools – Cip.8bi—Adobe 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.
Chapter 8 Cisco IP Phone Services Software Development Kit (SDK) Sample Services Requirements – Speed Dials (JSP) – Group MWI (JSP) – AutoDialer (JSP) – PhotoDirectory (JSP) – CallerInfo (JSP) – PushAuthenticate (ASP) – ScreenShot (ASP) – Integrating RS-232 devices with IP Telephony Applications (OtherApps) – PNGViewer (ASP) – Keyboard (ASP) – MultiDirectory (ASP) – Phone Push Step and Subsystem (Cisco Unified Contact Center Express / CRS) Sample Services Requirements The following list contains the item
Chapter 8 Cisco IP Phone Services Software Development Kit (SDK) Sample Services Requirements Cisco Unified IP Phone Services Application Development Notes 8-4 OL-22505-01
CH A P T E R 9 IP Phone Service Administration and Subscription Cisco Unified Communications Manager administrators maintain the list of services to which users can subscribe. Administrators must use Cisco Unified Communications Manager Administration to add and administer Cisco Unified IP Phone services. Note This chapter provides just a brief overview about managing IP Phone services.
Chapter 9 IP Phone Service Administration and Subscription Adding a Phone Service Example http:///ccmuser/sample/sample.asp Where designates a fully qualified domain name or an IP address.
Chapter 9 IP Phone Service Administration and Subscription Defining IP Phone Service Parameters Table 9-1 IP Phone Service Configuration Settings (continued) Field Description Secure-Service URL Enter the secure URL of the server where the Cisco Unified IP Phone services application is located. Make sure that this server remains independent of the servers in your Cisco Unified Communications Manager cluster.
Chapter 9 IP Phone Service Administration and Subscription User Service Subscription Table 9-2 IP Phone Service Parameter Settings Field Description Service Parameter Information Parameter Name Enter the exact query string parameter to use when you build the subscription URL; for example, symbol. Parameter Display Name Enter a descriptive parameter name to display to the user in Cisco Unified CM User Options; for example, Ticker Symbol. Default Value Enter the default value for the parameter.
CH A P T E R 10 DeviceListX Report The DeviceListX Report is no longer supported as of Cisco Unified Communications Manager Release 5.0. Retrieving real-time information from Cisco Unified Communications Manager is now supported via the Cisco Unified Communications Manager AXL Serviceability API. The DeviceListX Report provides a list of the services-capable devices along with basic information about the device to identify or classify the devices based on specific criteria.
Chapter 10 DeviceListX Report Benefits • Device Pool • IP Address • Real-Time Information The completed list of data gets formatted into a simple XML object and gets returned in the HTTP Response to the developer. Benefits DeviceListX provides access to critical real-time data that was previously unavailable to third-party developers.
Chapter 10 DeviceListX Report Security Security This report, which is within the Cisco Unified Communications Manager Administration, inherits its security from that web site, so no security issues directly relate to this report. If the Cisco Unified Communications Manager Administration changes how it implements security with additions, such as SSL, this report benefits from that enhancement.
Chapter 10 DeviceListX Report Troubleshooting DeviceListX Reports Table 10-1 DeviceList XML Object Attributes Attribute Name Field Name Description t Device Type Numeric enumeration value that is specified in the database. n Device Name String value that specifies the device name. d Device Description String value that is specified in the database.
Chapter 10 DeviceListX Report Troubleshooting DeviceListX Reports Error Message 1001 Too many simultaneous requests for Device List. Please wait at least 60 seconds and try again. Explanation When two or more clients attempt to get the list at the same time, or if the list is long, overlapping requests can result (first request is processing when the second request attempts processing). Recommended Action Request information only as often as necessary.
Chapter 10 DeviceListX Report Troubleshooting DeviceListX Reports Cisco Unified IP Phone Services Application Development Notes 10-6 OL-22505-01
A P P E N D I X A CiscoIPPhone XML Object Quick Reference Table A-1 provides a quick reference of the CiscoIPPhone XML objects and the definitions that are associated with each.
Appendix A Table A-1 CiscoIPPhone XML Object Quick Reference CiscoIPPhone XML Object Quick Reference (continued) Object Definition CiscoIPPhoneImage 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
Appendix A Table A-1 CiscoIPPhone XML Object Quick Reference CiscoIPPhone XML Object Quick Reference (continued) Object Definition CiscoIPPhoneIconMenu Title text goes here Prompt text goes here Name of softkey URL or URI of softkey
Appendix A Table A-1 CiscoIPPhone XML Object Quick Reference CiscoIPPhone XML Object Quick Reference (continued) Object Definition CiscoIPPhoneResponse Cisco Unified IP Phone Services Application Development Notes A-4 OL-22505-01
A P P E N D I X B Cisco Unified IP Phone Services XML Schema File These sections provide details about the XML schema supported on Cisco Unified IP Phones: • Updated XML Parser and Schema Enforcement • CiscoIPPhone.xsd Updated XML Parser and Schema Enforcement In order to provide a stable and consistent platform upon which to build enhancements to IP phones services, Cisco released an updated XML parser beginning with firmware release 8.3(2).
Appendix B Cisco Unified IP Phone Services XML Schema File CiscoIPPhone.xsd CiscoIPPhone.xsd Note Cisco Unified IP Phones 6921, 6941, 6945, and 6961 does not support: • The NavLeft, NavRight, NavBack, and PushToTalk Key attributes • CiscoIPPhoneKeyType PAGE 115Appendix B Cisco Unified IP Phone Services XML Schema File CiscoIPPhone.
Appendix B Cisco Unified IP Phone Services XML Schema File CiscoIPPhone.
Appendix B Cisco Unified IP Phone Services XML Schema File CiscoIPPhone.
Appendix B Cisco Unified IP Phone Services XML Schema File CiscoIPPhone.
Appendix B Cisco Unified IP Phone Services XML Schema File CiscoIPPhone.
Appendix B Cisco Unified IP Phone Services XML Schema File CiscoIPPhone.
Appendix B Cisco Unified IP Phone Services XML Schema File CiscoIPPhone.
Appendix B Cisco Unified IP Phone Services XML Schema File CiscoIPPhone.
Appendix B Cisco Unified IP Phone Services XML Schema File CiscoIPPhone.
Appendix B Cisco Unified IP Phone Services XML Schema File CiscoIPPhone.
Appendix B Cisco Unified IP Phone Services XML Schema File CiscoIPPhone.
Appendix B Cisco Unified IP Phone Services XML Schema File CiscoIPPhone.
A P P E N D I X C Device Capability Query Via CTI Feature Description A backend CTI application that communicates with the phone via the UserData tunnel, cannot retrieve information on device capabilities such as XSI feature support on a phone. Due to this lack of information, and to ensure compatability, only a minimum set of features were generally configured. The new Device Capability Query via CTI feature overcomes this limitation.
Appendix C Device Capability Query Via CTI Supported IP Phones and Codecs Table 1 Phone Models that Support the Device Capability Query via CTI Feature Phone Model Supported/Not Supported Firware Supported1 7905 — 7906 8.4(1) and later 7911 8.4(1) and later 7912 — 7931 8.4(1) and later 7937 — 7940 — 7941 8.4(1) and later 7942 8.4(1) and later 7945 8.4(1) and later 7960 — 7961 8.4(1) and later 7962 8.4(1) and later 7965 8.4(1) and later 7970 8.4(1) and later 7971 8.
Appendix C Device Capability Query Via CTI Changes in XML Object Changes in XML Object To support this feature new request and response objects are created. The is the request object and the is the response object. On receiving the object, the phone returns the object. All elements in the object are required and must not be null.
Appendix C Device Capability Query Via CTI Example Example The following are the request and response examples for a getDeviceCaps object: Request sent to the phone: Response returned from the phone: CP-7970 PAGE 131I N D EX Cisco IP Phone Services Software Development Kit (SDK) Symbols components << softkey 5-7 8-1 development tools 8-2 sample services description Numerics 8-2 requirements 8961 8-3 CiscoIPPhone XML Objects Color depth CiscoIPPhoneDirectory 3-12 Resolution CiscoIPPhoneError 3-12 URIs supported XML Objects supported 3-2, 3-26 9951 Color depth Reolution 3-12 3-2, 3-26 9971 3-12 Resolution 3-14 CiscoIPPhoneIconFileMenu 3-19 XML Objects Supported 3-2, 3-26 3-7 CiscoIPPhon
Index client requests, using HTTP 6-1 content expiration, header setting cookie behavior F 6-4 featuers, supported 6-5 2-1 G D development tools, included with SDK 8-2 Key 3-14 graphics Device control URI Display graphic menus, creating displaying color images 5-6 3-11 displaying grayscale images 5-3 DeviceInformation PNG support 6-9 device information URLs 3-11, 3-20 using with status 6-9 3-7 3-24 DeviceList XML Object attributes 10-4 description DeviceListX Report DeviceLo
Index I S icon menus, creating Screenshot, CGI script color SDK.
Index tips 7-1 XML parsing errors 7-1 U uniform resource identifiers (URI) description 5-1 miscellaneous Dial 5-15 EditDial Init 5-16 5-18 Play 5-13 to control RTP streaming RTPMTx Update softkey 5-10 5-12 5-7 URI.
