Download Print this page

Cisco OL-18696-01 Development Manual

Unified ip phone services application development notes
Hide thumbs

Advertisement

Quick Links

Cisco Unified IP Phone Services
Application Development Notes
Supporting XML Applications
Release 7.1(2)
Americas Headquarters
Cisco Systems, Inc.
170 West Tasman Drive
San Jose, CA 95134-1706
USA
http://www.cisco.com
Tel: 408 526-4000
800 553-NETS (6387)
Fax: 408 527-0883
Text Part Number: OL-18696-01

Advertisement

loading

  Related Manuals for Cisco OL-18696-01

  Summary of Contents for Cisco OL-18696-01

  • Page 1 Cisco Unified IP Phone Services Application Development Notes Supporting XML Applications Release 7.1(2) Americas Headquarters Cisco Systems, Inc. 170 West Tasman Drive San Jose, CA 95134-1706 http://www.cisco.com Tel: 408 526-4000 800 553-NETS (6387) Fax: 408 527-0883 Text Part Number: OL-18696-01...
  • Page 2 OR LIMITED WARRANTY, CONTACT YOUR CISCO REPRESENTATIVE FOR A COPY. The Cisco implementation of TCP header compression is an adaptation of a program developed by the University of California, Berkeley (UCB) as part of UCB’s public domain version of the UNIX operating system. All rights reserved. Copyright © 1981, Regents of the University of California.
  • Page 3: Table Of Contents

    Custom Directories CiscoIPPhoneImage CiscoIPPhoneImageFile CiscoIPPhoneGraphicMenu 2-10 CiscoIPPhoneGraphicFileMenu 2-11 CiscoIPPhoneIconMenu 2-12 CiscoIPPhoneIconFileMenu 2-13 CiscoIPPhoneStatus 2-14 CiscoIPPhoneStatusFile 2-16 CiscoIPPhoneExecute 2-16 CiscoIPPhoneResponse 2-17 CiscoIPPhoneError 2-18 Custom Softkeys 2-18 XML Considerations 2-19 Mandatory Escape Sequences 2-19 Cisco Unified IP Phone Services Application Development Notes OL-18696-01...
  • Page 4 Multimedia URIs RTP Streaming RTPRx RTPTx RTPMRx RTPMTx 4-10 Play 4-10 Vibrate 4-11 Telephony URIs 4-11 Dial 4-11 EditDial 4-12 SendDigits 4-13 Application Management URIs 4-14 Init 4-14 Notify 4-15 Application 4-17 Cisco Unified IP Phone Services Application Development Notes OL-18696-01...
  • Page 5 C H A P T E R Accessing Phone Service Administration Adding a Phone Service Defining IP Phone Service Parameters User Service Subscription DeviceListX Report C H A P T E R Benefits Cisco Unified IP Phone Services Application Development Notes OL-18696-01...
  • Page 6 A P P E N D I X Cisco Unified IP Phone Services A P P E N D I X XML Schema File Updated XML Parser and Schema Enforcement CiscoIPPhone.xsd N D E X Cisco Unified IP Phone Services Application Development Notes OL-18696-01...
  • Page 7: Preface

    Use this document with Cisco Unified Communications Manager, Release 7.1(2) to develop and deploy customized client services for the Cisco Unified IP Phones that support Cisco Unified Phone services. Because of the complexity of a Unified Communications network, this guide does not provide complete and detailed information for procedures that you need to perform in Cisco Unified Communications Manager or other network devices.
  • Page 8: Organization

    Preface The Cisco TAC does NOT provide support for this API/interface under standard hardware or software Note support agreements. All technical support for this API/interface, from initial development assistance through API troubleshooting/bugs in final production apps, is provided by Cisco Developer Support and requires a separate Developer Support contract.
  • Page 9: Related Documentation

    Obtaining Documentation and Submitting a Service Request For information on obtaining documentation, submitting a service request, and gathering additional information, see the monthly What’s New in Cisco Product Documentation, which also lists all new and revised Cisco technical documentation, at: http://www.cisco.com/en/US/docs/general/whatsnew/whatsnew.html...
  • Page 10: Document Conventions

    Means the described action saves time. You can save time by performing the action described in Timesaver the paragraph. Means reader be warned. In this situation, you might perform an action that could result in Warning bodily injury. Cisco Unified IP Phone Services Application Development Notes OL-18696-01...
  • Page 11: Chapter 1 Overview

    C H A P T E R 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.
  • Page 12 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. The return type from this URL can be plain text or one of the CiscoIPPhone XML objects.
  • Page 13 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. Cisco Unified IP Phone Services Application Development Notes OL-18696-01...
  • Page 14 Chapter 1 Overview Cisco Unified IP Phone Services Application Development Notes OL-18696-01...
  • Page 15: Chapter 2 Ciscoipphone Xml Objects

    Regarding services, the phone does not have any concept of a state when it loads an XML page. Cisco Unified 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 after it loads a page.
  • Page 16 CiscoIPPhoneError 1. The Cisco Unified IP Phone 7920G has only a 128-by-59 display with 2 grayscale images clipping the graphic equally on both sides and providing vertical scrolling. When an image with 4 grayscale settings occurs (<Depth>2</Depth>), the phone equally splits them into 2 grayscale settings (0-1 get treated as 0 and 2-3 get treated as 1).
  • Page 17: Xml Object Definitions

    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 objects. Cisco Unified IP Phones allow a maximum of 100 . Each MenuItem...
  • Page 18: Ciscoipphonetext

    Note Keypad navigation: Cisco Unified IP Phones allow navigation to a specific line in a menu by pressing numeric DTMF keys. When a menu is on the display, the number for selecting the menu is on the left. When normal text displays, the numbers do not display on the left side of the screen, but the navigation capability still exists.
  • Page 19 Telephone number—enter only DTMF digits for this field. The acceptable input includes numbers, #, and *. Numeric—enter numbers as the only acceptable input. Equation—enter numbers and special math symbols. Uppercase—enter uppercase letters as the only acceptable input. Cisco Unified IP Phone Services Application Development Notes OL-18696-01...
  • Page 20: Ciscoipphonedirectory

    (*). During text entry, Cisco Unified IP Phones display softkeys to assist users with text entry. Users can navigate between fields with the vertical scroll button that is used to navigate menus, and so on.
  • Page 21: Custom Directories

    Each pixel includes four grayscale settings. A value of three (3) displays as black, and a value of zero (0) displays as white. The phone uses an LCD display, which inverts the palette. Note XML type lets you use the Cisco Unified IP Phone display to present graphics CiscoIPPhoneImage to the user. Definition <CiscoIPPhoneImage>...
  • Page 22 Height field, results will be unpredictable incorrect. Data specifies the number of bits per pixel. Cisco Unified IP Phones support a maximum value of 2. A Depth bit depth of 1 is black and white. tag delimits a string of hexadecimal digits that contain the packed value of the pixels in the Data display.
  • Page 23 1. Represents the size of the display that is accessible by Services—not the full resolution of the physical display. 2. The Cisco Unified IP Phones 7905 and 7912 have pixel-based displays, but they do not support XML images. If the number of colors in the image is not reduced to match the phone capabilities, the image will be dithered by the phone and yield less than desirable results in most cases.
  • Page 24 For example, using the value of 16 (4-bits per channel = 16 tones per channel) will correctly dither the color palette of the image for the best display results on the Cisco Unified IP Phone 7970G. Figure 2-4 shows a CiscoIPPhoneImageFile object on a Cisco Unified IP Phone 7970G display.
  • Page 25: Ciscoipphonemenu

    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.
  • Page 26 CiscoIPPhoneMenu pixels. Figure 2-6 shows an IconMenu on a Cisco Unified IP Phone. Figure 2-6 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 object.
  • Page 27: Ciscoipphoneiconmenu

    <Name>The name of each menu item</Name> <URL>The URL associated with the menu item</URL> </MenuItem> <IconItem> <Index>A unique index from 0 to 9</Index> <URL>location of the PNG icon image</URL> </IconItem> </CiscoIPPhoneIconFileMenu> Cisco Unified IP Phone Services Application Development Notes 2-13 OL-18696-01...
  • Page 28: Ciscoipphonestatus

    Overview content. For example, using a smaller window for an application allows more content from the Overview to be displayed. Sizing the window occurs upon the reception of a CiscoIPPhoneStatus or CiscoIPPhoneStatusFile object with its associated PNG file. Cisco Unified IP Phone Services Application Development Notes 2-14 OL-18696-01...
  • Page 29 An exception is allowed for the Cisco Unified IP Phones 7940G/7960G due to resource constraints. For these phones, you should implement both the maximum size and minimum size windows ignoring all of the intermediate sizes.
  • Page 30: Ciscoipphonestatusfile

    CiscoIPPhoneStatus image instead of a grayscale CIP image for the graphics area. The maximum image size is 262 x 50 pixels for the Cisco Unified IP Phone 7970G, but differs for other phone models. See “Dynamic Sizing of the Application Status Window” section on page 2-14 for details.
  • Page 31: Ciscoipphoneresponse

    The Idle Timer (along with an optional Idle URL) is defined globally in the Cisco Unified Communications Manager Administration Enterprise Parameters and can be overridden on a per phone basis in the Cisco Unified Communications Manager Device configuration.
  • Page 32: Ciscoipphoneerror

    CiscoIPPhoneError describe the nature of the error condition. Custom Softkeys Cisco Unified IP Phones can use custom softkeys with any of the displayable CiscoIPPhone XML objects, excluding the object which cannot control softkeys and the CiscoIPPhoneStatus object which is not displayable.
  • Page 33: Xml Considerations

    </SoftKeyItem> XML Considerations The XML parser in Cisco Unified 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. All CiscoIPPhone element names and attribute names are case sensitive.
  • Page 34: Xml Encoding

    The following examples illustrate UTF-8 and ISO-8859-1 encoding, respectively: <?xml version="1.0" encoding="utf-8" ?> <?xml version="1.0" encoding="iso-8859-1" ?> For details on setting HTTP header encoding settings, see the “HTTP Encoding Header Setting” section on page 5-5. Cisco Unified IP Phone Services Application Development Notes 2-20 OL-18696-01...
  • Page 35: Application Event Handlers

    The Application Event Handlers can be attached to a supported object by specifying the attributes: An Application URI with Priority=0 is not allowed in the Application Event Handlers (see “Application” Note section on page 4-17). Cisco Unified IP Phone Services Application Development Notes 2-21 OL-18696-01...
  • Page 36 This event handler cannot contain HTTP or Note HTTPS URLs. Note If a Notify URI is used as the event handler, a notification is sent with this default data: <notifyApplicationEvent appId="appId" type="closed"/> Cisco Unified IP Phone Services Application Development Notes 2-22 OL-18696-01...
  • Page 37 </xs:attribute> <xs:attribute name="type" use="required"> <xs:simpleType> <xs:restriction base="xs:string"> <xs:enumeration value="closed"/> <xs:enumeration value="minimized"/> <xs:enumeration value="focusLost"/> <xs:enumeration value="focusGained"/> </xs:restriction> </xs:simpleType> </xs:attribute> </xs:complexType> </xs:element> </xs:schema> Example <CiscoIPPhoneImage appId="Cisco/Unity" onAppFocusLost="RTPRx:Stop; RTPTx:Stop; Notify:http:server:80:path" onAppFocusGained="http://server/mainpage/updateUI" onAppClosed="Notify:http:server:80:eventlistener/appClosed"> </CiscoIPPhoneImage> Cisco Unified IP Phone Services Application Development Notes 2-23 OL-18696-01...
  • Page 38 Chapter 2 CiscoIPPhone XML Objects Application Event Handlers Cisco Unified IP Phone Services Application Development Notes 2-24 OL-18696-01...
  • Page 39: Chapter 3 Component Apis

    The event handlers typically use the standard Notification framework (see “Notify” section on page 4-15), but they can also invoke most other URIs, with the exception of HTTP URLs. Cisco Unified IP Phone Services Application Development Notes OL-18696-01...
  • Page 40: Interaction Rules With Legacy Rtp Uri Streams

    The port parameter, if startMediaResponse specified, must be an even number in the range of 20480-32768. <?xml version="1.0" encoding="UTF-8"?> <!-- edited with XML Spy v4.4 U (http://www.xmlspy.com) by Cisco Systems, Inc. (Cisco Systems, Inc.) --> <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" attributeFormDefault="unqualified">...
  • Page 41 <xs:enumeration value="Wideband"/> <xs:enumeration value="iLBC"/> </xs:restriction> </xs:simpleType> </xs:element> <xs:element name="mode"> <xs:simpleType> <xs:restriction base="xs:string"> <xs:enumeration value="send"/> <xs:enumeration value="receive"/> <xs:enumeration value="sendReceive"/> </xs:restriction> </xs:simpleType> </xs:element> <xs:element name="address"> <xs:simpleType> <xs:restriction base="xs:string"> <xs:minLength value="7"/> <xs:maxLength value="15"/> </xs:restriction> </xs:simpleType> Cisco Unified IP Phone Services Application Development Notes OL-18696-01...
  • Page 42: Error Schema

    <xs:all> <xs:element name="type"> <xs:simpleType> <xs:restriction base="xs:string"> <xs:enumeration value="InvalidURL"/> <xs:enumeration value="InvalidResource"/> <xs:enumeration value="InvalidResourceID"/> <xs:enumeration value="UnavailableResource"/> <xs:enumeration value="InvalidXML"/> </xs:restriction> </xs:simpleType> </xs:element> <xs:element name="data" nillable="true"> <xs:simpleType> <xs:restriction base="xs:string"/> </xs:simpleType> </xs:element> </xs:all> </xs:complexType> </xs:element> </xs:schema> Cisco Unified IP Phone Services Application Development Notes OL-18696-01...
  • Page 43: Examples

    DATA=<notifyMediaEvent type=”stopped” origin=”user”> <mediaStream id=”abc123”/> </notifyMediaEvent> Errors and Responses Error conditions and responses for the RTP Streaming API include: Applicable Condition Methods HTTP Result Code Type Data Authorization failed 401 (Authorization Failed) N/A Cisco Unified IP Phone Services Application Development Notes OL-18696-01...
  • Page 44 Resource DSP resources is Available available to handle the media Media cannot be stopMedia 400 (BadRequest) InvalidResourceID Unknown Media stopped because the Stream ID: specified stream ID <streamID> does not exist Cisco Unified IP Phone Services Application Development Notes OL-18696-01...
  • Page 45: Chapter 4 Internal Uri Features

    These sections provide details about the available internal URIs: Supported URIs by Phone Model • Device Control URIs • • XML Displayable Object URIs Multimedia URIs • • Telephony URIs Application Management URIs • Cisco Unified IP Phone Services Application Development Notes OL-18696-01...
  • Page 46: Supported Uris By Phone Model

    1. Only supports one incoming and one outgoing unicast stream and does not support the Volume parameter for RTP Receive streams. 2. Requires Cisco Unified IP Phone firmware version 8.3(2) or later, which contains an updated XML parser. See the “Updated XML Parser and...
  • Page 47: Device Control Uris

    Key:KeyPadPound Key:VolDwn • Key:VolUp • Key:Headset • Key:Speaker • Key:Mute • Key:NavLeft • Key:NavRight • Key:NavSelect • Key:Info • Key:Messages • Key:Services • • Key:Directories • Key:Settings • Key:NavUp Key:NavDwn • Cisco Unified IP Phone Services Application Development Notes OL-18696-01...
  • Page 48: Display

    • 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.
  • Page 49 When the user performs an action with a softkey, 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 softkey. Cisco Unified IP Phone Services Application Development Notes OL-18696-01...
  • Page 50: Querystringparam

    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> <Position>1</Position><URL>QueryStringParam:action=read</URL> </SoftKeyItem> <SoftKeyItem> <Name>Delete</Name> <Position>2</Position><URL>QueryStringParam:action=delete</URL> Cisco Unified IP Phone Services Application Development Notes OL-18696-01...
  • Page 51: Multimedia Uris

    • RTPMRx • RTPMTx • For some Cisco Unified IP Phone models, the RTP Streaming URIs have been deprecated by the RTP Note Streaming API. See the “RTP Streaming API” section on page 3-1. The supported format of the RTP stream is as follows: The codec is G.711 mu-Law.
  • Page 52: Rtprx

    The RTPRx URI instructs the phone to receive a Unicast RTP stream or to stop receiving Unicast or Multicast RTP streams. URI Formats RTPRx:i:p:v RTPRx:Stop Where i = the IP Address from which the stream is coming. Cisco Unified IP Phone Services Application Development Notes OL-18696-01...
  • Page 53: Rtptx

    If the optional volume parameter does not get included, the current volume setting on the phone gets used as the default. RTPMTx The RTPMTx URI instructs the phone to transmit a Multicast RTP stream. Cisco Unified IP Phone Services Application Development Notes OL-18696-01...
  • Page 54: Play

    Where f = the filename of a raw audio file in the TFTP path (such as Play:Classic2.raw). The audio files for the rings must meet the following requirements for proper playback on Cisco Unified IP Phones: Raw PCM (no header) •...
  • Page 55: Vibrate

    Telephony URIs Vibrate The Vibrate URI is available on the Cisco Unified IP Phones 7920G and 7921G wireless phone models, and it enables third-party applications to invoke the phone’s vibration capabilities for silent alerts, similar to the way in which the Play URI plays audible alerts. If the Vibrate parameters are not specified or if the device is unable to support custom Vibrate sequences, the device will execute its default vibrate sequence.
  • Page 56 Speaker button • Headset button • Handset hook switch • Normal menu item • Softkey item selection • URI Format EditDial:n Where n = the number dialed (such as EditDial:1000). Cisco Unified IP Phone Services Application Development Notes 4-12 OL-18696-01...
  • Page 57 Invalid URI URI is not supported 6 (Internal error) URI not found Unable to execute URI because there currently is no 6 (Internal error) No Active Call active (streaming) call Cisco Unified IP Phone Services Application Development Notes 4-13 OL-18696-01...
  • Page 58: Application Management Uris

    XSI objects that support action handlers (such as displayable XSI objects and RTP streams). For example, use the Notify URI to deliver notifications to back-end applications when an XSI application is closed or when an RTP stream is terminated. Cisco Unified IP Phone Services Application Development Notes 4-14 OL-18696-01...
  • Page 59 Host: myserver:8080 Content-Length: 23 DATA=myStreamStoppedData Called from RTP onStreamStopped Event Handler, no credentials, no data: • Notify:http:server:8080:path/streamhandler?event=stopped HTTP POST /path/streamhandler?event=stopped HTTP/1.1 Accept: */* Content-Type: application/x-www-form-urlencoded; charset=”UTF-8” Host: myserver:8080 Content-Length: 40 Cisco Unified IP Phone Services Application Development Notes 4-15 OL-18696-01...
  • Page 60: Application

    The Application URI allows applications to request changes to their application or window state. Applications can request to change focus, to be minimized, or to be closed. Cisco Unified IP Phone Services Application Development Notes 4-16 OL-18696-01...
  • Page 61 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. Cisco Unified IP Phone Services Application Development Notes 4-17 OL-18696-01...
  • Page 62 Invalid URI Unknown application ID 6 (Internal error) Unknown Application ID Request made to change state of an application that is 6 (Internal error) Application is not Active not current active Cisco Unified IP Phone Services Application Development Notes 4-18 OL-18696-01...
  • Page 63: Chapter 5 Http Requests And Header Settings

    HTTP Client Requests (HTTP GET) The following description designates how HTTP client requests are handled: The Cisco Unified IP Phone HTTP client performs an HTTP GET for a specified URL. The HTTP server processes request and returns an XML object or plain text.
  • Page 64: Http Header Settings

    512 bytes. See the Cisco Unified Communications Manager JTAPI Developer Guide for more information. HTTP Header Settings The following list provides definitions for HTTP header elements for Cisco Unified IP Phone Services: “Refresh”—sets the refresh time (in seconds) and URL •...
  • Page 65: Http Refresh Setting

    URL points. The Cisco Unified 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.
  • Page 66: Mime Type And Other Http Headers

    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 Unified IP Phone rings. Refer to the chapter on “Custom Phone Rings” in the Cisco Unified Communications Manager System Guide (also available in the online help).
  • Page 67: Set-Cookie Header Setting

    Set-Cookie: ASPSESSIONIDGQGQGRLS=OCPNMLFDBJIPNIOOKFNFMOAL; path=/ The Cisco Unified IP Phone can receive and use a total of four cookies per host per session and can store information for up to eight sessions at once. Each cookie can be up to 255 bytes in size. These cookies are available until the server terminates the session or the client session has been idle for more than 30 minutes.
  • Page 68: Http Response Headers: Content-Type

    HTTP Requests and Header Settings HTTP Header Settings Accept-Language Cisco Unified IP Phones populate the Accept-Language HTTP request header in compliance with the HTTP specification. For example, the Accept-Language value advertised by a phone configured for the English_United_States user locale would look like:...
  • Page 69: Identifying The Capabilities Of Ip Phone Clients

    IP phone to optimize the content returned to the phone. For example, if the requesting phone is a Cisco Unified IP Phone 7960, which cannot support color PNG images, the application server must be able to identify this and return a gray scale CIP image instead.
  • Page 70: Accept Header

    Cisco Unified IP Phones include proprietary content-types to indicate which XML objects are supported. These proprietary content-types all begin with x-CiscoIPPhone, to indicate Cisco Unified IP Phone XML objects, followed by a slash “/”, followed by either a specific XML object or a “*” to indicate all objects.
  • Page 71 The target URL of a phone push (HTTP POST) request. /CGI/Screenshot Returns an exact snapshot of the current phone display. The size and format of the image returned is model-specific. 1. Password-protected CGI script Cisco Unified IP Phone Services Application Development Notes OL-18696-01...
  • Page 72 Chapter 5 HTTP Requests and Header Settings Accessing IP Phone Information Cisco Unified IP Phone Services Application Development Notes 5-10 OL-18696-01...
  • Page 73: Troubleshooting Cisco Unified Ip Phone Service Applications

    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 Unified IP Phone services applications: •...
  • Page 74: Error Messages

    SoftKeyItem—The Position field is mandatory. If the Position field is not present, the updated XML parser will report an error. Error Messages The following error messages may appear on the prompt line of the Cisco Unified IP Phone display: • XML Error[4] = XML Parser error (Invalid Object) •...
  • Page 75: Cisco Ip Phone Services Software Development Kit (Sdk)

    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.com/web/ipps...
  • Page 76: C H A P T E R 7 Cisco Ip Phone Services Software Development Kit (Sdk)

    – Cisco Unified IP Phone Services ASP/Javascript Library (automatically installed) – Cisco Unified IP Phone Services Java Library—Used by the JSP apps (manually installed - see – JSP Install readme) CallManager Simulator —Used for developing Phone Services without a Cisco Unified –...
  • Page 77: Sample Services Requirements

    MultiDirectory (ASP) – – Phone Push Step and Subsystem (Cisco Unified Contact Center Express / CRS) Sample Services Requirements The following list contains the items that are required for the sample services to work properly: Microsoft IIS 4.0 or later (for ASP sample services) •...
  • Page 78 Chapter 7 Cisco IP Phone Services Software Development Kit (SDK) Sample Services Requirements Cisco Unified IP Phone Services Application Development Notes OL-18696-01...
  • Page 79: Chapter 8 Ip Phone Service Administration And Subscription

    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 Unified Communications Manager cluster must have network connectivity to the server.
  • Page 80: Adding A Phone Service

    Service Information Service Name Enter the name of the service as it will display on the menu of available services in Cisco Unified CM User Options. Enter up to 32 characters for the service name. ASCII Service Name Enter the name of the service to display if the phone cannot display Unicode.
  • Page 81: Defining Ip Phone Service Parameters

    IDs. The service provider defines the semantics of a parameter. The Cisco Unified IP Phone Service Parameter Configuration page in Cisco Unified Communications Manager Administration contains the fields as described in Table 8-2.
  • Page 82: User Service Subscription

    IP Phone Service Administration and Subscription User Service Subscription If you change the service URL, remove a Cisco Unified 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.
  • Page 83: Chapter 9 Devicelistx Report

    Troubleshooting DeviceListX Reports • Note DeviceListX does not support all devices. If you have a device that you need to support, contact Cisco Developer Support to verify whether it is supported: http://developer.cisco.com/web/ipps When a third-party developer initiates an HTTP GET request for the DeviceListX.asp report page, the...
  • Page 84: Benefits

    XML version 1.0. Performance and Scalability You can run this report on the largest supported Cisco Unified Communications Manager cluster size for the targeted release without impacting core features, such as delaying dial tone. On multiserver Cisco Unified Communications Manager clusters, the report can access only from the publisher server.
  • Page 85: Security

    Use the following URL to access the report via HTTP: http://x.x.x.x/CCMAdmin/reports/devicelistx.asp where x.x.x.x can either be the IP address or hostname of the Cisco Unified CallManager system that contains the report. Beginning with Cisco Unified CallManager 4.1 release, the DeviceListX report can only be accessed via Note secure HTTP (HTTPS), so the URL must begin with “https:”...
  • Page 86: Troubleshooting Devicelistx Reports

    These sections can assist you in troubleshooting DeviceListX Reports: Error Codes • Determining Problems With the Interface • Error Codes The error codes that are specific to this report interface follow. Cisco Unified IP Phone Services Application Development Notes OL-18696-01...
  • Page 87: Determining Problems With The Interface

    Request information only as often as necessary. Recommended Action Cisco recommends that you wait longer than 60 seconds between requests. Note Error Message 1002 Too many consecutive requests for Device List. Please wait at least 60 seconds and try again.
  • Page 88 Chapter 9 DeviceListX Report Troubleshooting DeviceListX Reports Cisco Unified IP Phone Services Application Development Notes OL-18696-01...
  • Page 89: Appendix

    <InputFlags>The flag specifying the type of allowable input</InputFlags> </InputItem> </CiscoIPPhoneInput> CiscoIPPhoneDirectory <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> </CiscoIPPhoneDirectory> Cisco Unified IP Phone Services Application Development Notes OL-18696-01...
  • Page 90 <LocationX>Horizontal position of graphic</LocationX> <LocationY>Vertical position of graphic</LocationY> <URL>Points to the PNG background image</URL> <MenuItem> <Name>Same as CiscoIPPhoneGraphicMenu</Name> <URL>Invoked when the TouchArea is touched</URL> <TouchArea X1="left edge" Y1="top edge" X2="right edge"Y2="bottom edge"/> </MenuItem> </CiscoIPPhoneGraphicFileMenu> Cisco Unified IP Phone Services Application Development Notes OL-18696-01...
  • Page 91 <ExecuteItem URL=”The URL or URI to be executed”/> </CiscoIPPhoneExecute> CiscoIPPhoneError <CiscoIPPhoneError Number=”x”/> CiscoIPPhoneResponse <CiscoIPPhoneResponse> <ResponseItem Status”the success or failure of the action”Data=”the information associated with the request” URL=”the URL or URI specified in the Execute object”/> </CiscoIPPhoneResponse> Cisco Unified IP Phone Services Application Development Notes OL-18696-01...
  • Page 92 Appendix A CiscoIPPhone XML Object Quick Reference Cisco Unified IP Phone Services Application Development Notes OL-18696-01...
  • Page 93: Appendix

    Cisco released an updated XML parser beginning with firmware release 8.3(2). As a result, many Cisco Unified IP Phones now contain this updated XML parser which provides a more rigid enforcement of the XML schema. This updated parser provides more error logging information when it encounters XML schema violations, and it enables developers to debug their applications more efficiently.
  • Page 94: Ciscoipphone.xsd

    Appendix B Cisco Unified IP Phone Services XML Schema File CiscoIPPhone.xsd CiscoIPPhone.xsd <?xml version="1.0" encoding="UTF-8"?> <!-- edited with XML Spy v4.4 U (http://www.xmlspy.com) by Cisco Systems, Inc. (Cisco Systems, Inc.) --> <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" attributeFormDefault="unqualified" version="3.3.4"> <xsd:complexType name="CiscoIPPhoneExecuteItemType"> <xsd:attribute name="Priority" use="optional">...
  • Page 95 Appendix B Cisco Unified IP Phone Services XML Schema File CiscoIPPhone.xsd </xsd:sequence> </xsd:complexType> <xsd:complexType name="CiscoIPPhoneTouchAreaType"> <xsd:attribute name="X1" type="xsd:unsignedShort" use="required"/> <xsd:attribute name="Y1" type="xsd:unsignedShort" use="required"/> <xsd:attribute name="X2" type="xsd:unsignedShort" use="required"/> <xsd:attribute name="Y2" type="xsd:unsignedShort" use="required"/> </xsd:complexType> <xsd:complexType name="CiscoIPPhoneDirectoryEntryType"> <xsd:sequence> <xsd:element name="Name" minOccurs="0"> <xsd:simpleType> <xsd:restriction base="xsd:string">...
  • Page 96 Appendix B Cisco Unified IP Phone Services XML Schema File CiscoIPPhone.xsd <xsd:enumeration value="PE"/> <xsd:enumeration value="PU"/> <xsd:enumeration value="PL"/> </xsd:restriction> </xsd:simpleType> </xsd:element> <xsd:element name="DefaultValue" minOccurs="0"> <xsd:simpleType> <xsd:restriction base="xsd:string"> <xsd:maxLength value="32"/> <xsd:minLength value="0"/> </xsd:restriction> </xsd:simpleType> </xsd:element> </xsd:sequence> </xsd:complexType> <xsd:complexType name="CiscoIPPhoneMenuItemType"> <xsd:sequence> <xsd:element name="Name" minOccurs="0">...
  • Page 97 Appendix B Cisco Unified IP Phone Services XML Schema File CiscoIPPhone.xsd <xsd:simpleType> <xsd:restriction base="xsd:hexBinary"> <xsd:maxLength value="40"/> <xsd:minLength value="0"/> </xsd:restriction> </xsd:simpleType> </xsd:element> </xsd:sequence> </xsd:complexType> <xsd:complexType name="CiscoIPPhoneIconMenuItemType"> <xsd:sequence> <xsd:element name="Name" minOccurs="0"> <xsd:simpleType> <xsd:restriction base="xsd:string"> <xsd:minLength value="0"/> <xsd:maxLength value="64"/> </xsd:restriction> </xsd:simpleType> </xsd:element> <xsd:element name="URL" minOccurs="0">...
  • Page 98 Appendix B Cisco Unified IP Phone Services XML Schema File CiscoIPPhone.xsd <xsd:enumeration value="KeyPad2"/> <xsd:enumeration value="KeyPad3"/> <xsd:enumeration value="KeyPad4"/> <xsd:enumeration value="KeyPad5"/> <xsd:enumeration value="KeyPad6"/> <xsd:enumeration value="KeyPad7"/> <xsd:enumeration value="KeyPad8"/> <xsd:enumeration value="KeyPad9"/> <xsd:enumeration value="KeyPadStar"/> <xsd:enumeration value="KeyPadPound"/> <xsd:enumeration value="NavUp"/> <xsd:enumeration value="NavDown"/> <xsd:enumeration value="NavLeft"/> <xsd:enumeration value="NavRight"/> <xsd:enumeration value="NavSelect"/>...
  • Page 99 Appendix B Cisco Unified IP Phone Services XML Schema File CiscoIPPhone.xsd <xsd:element name="URLDown" minOccurs="0"> <xsd:simpleType> <xsd:restriction base="xsd:string"> <xsd:minLength value="0"/> <xsd:maxLength value="256"/> </xsd:restriction> </xsd:simpleType> </xsd:element> </xsd:sequence> </xsd:complexType> <xsd:complexType name="CiscoIPPhoneDisplayableType"> <xsd:sequence> <xsd:element name="Title" minOccurs="0"> <xsd:simpleType> <xsd:restriction base="xsd:string"> <xsd:minLength value="0"/> <xsd:maxLength value="32"/> </xsd:restriction>...
  • Page 100 Appendix B Cisco Unified IP Phone Services XML Schema File CiscoIPPhone.xsd </xsd:simpleType> </xsd:attribute> <xsd:attribute name="onAppMinimized" use="optional"> <xsd:simpleType> <xsd:restriction base="xsd:string"> <xsd:minLength value="1"/> <xsd:maxLength value="256"/> </xsd:restriction> </xsd:simpleType> </xsd:attribute> <xsd:attribute name="onAppClosed" use="optional"> <xsd:simpleType> <xsd:restriction base="xsd:string"> <xsd:minLength value="1"/> <xsd:maxLength value="256"/> </xsd:restriction> </xsd:simpleType> </xsd:attribute> </xsd:complexType>...
  • Page 101 Appendix B Cisco Unified IP Phone Services XML Schema File CiscoIPPhone.xsd <xsd:restriction base="xsd:string"> <xsd:minLength value="1"/> <xsd:maxLength value="256"/> </xsd:restriction> </xsd:simpleType> </xsd:element> <xsd:element name="InputItem" type="CiscoIPPhoneInputItemType" minOccurs="0" maxOccurs="5"/> </xsd:sequence> </xsd:extension> </xsd:complexContent> </xsd:complexType> </xsd:element> <xsd:element name="CiscoIPPhoneDirectory"> <xsd:complexType> <xsd:complexContent> <xsd:extension base="CiscoIPPhoneDisplayableType"> <xsd:sequence> <xsd:element name="DirectoryEntry" type="CiscoIPPhoneDirectoryEntryType"...
  • Page 102 Appendix B Cisco Unified IP Phone Services XML Schema File CiscoIPPhone.xsd <xsd:restriction base="xsd:unsignedShort"> <xsd:minInclusive value="1"/> <xsd:maxInclusive value="2"/> </xsd:restriction> </xsd:simpleType> </xsd:element> <xsd:element name="Data" minOccurs="0"> <xsd:simpleType> <xsd:restriction base="xsd:hexBinary"> <xsd:maxLength value="2162"/> <xsd:minLength value="0"/> </xsd:restriction> </xsd:simpleType> </xsd:element> </xsd:sequence> </xsd:extension> </xsd:complexContent> </xsd:complexType> </xsd:element> <xsd:element name="CiscoIPPhoneImageFile">...
  • Page 103 Appendix B Cisco Unified IP Phone Services XML Schema File CiscoIPPhone.xsd </xsd:element> <xsd:element name="CiscoIPPhoneIconMenu"> <xsd:complexType> <xsd:complexContent> <xsd:extension base="CiscoIPPhoneDisplayableType"> <xsd:sequence> <xsd:element name="MenuItem" type="CiscoIPPhoneIconMenuItemType" minOccurs="0" maxOccurs="32"/> <xsd:element name="IconItem" type="CiscoIPPhoneIconItemType" minOccurs="0" maxOccurs="10"/> </xsd:sequence> </xsd:extension> </xsd:complexContent> </xsd:complexType> </xsd:element> <xsd:element name="CiscoIPPhoneIconFileMenu"> <xsd:complexType> <xsd:complexContent> <xsd:extension base="CiscoIPPhoneDisplayableType">...
  • Page 104 Appendix B Cisco Unified IP Phone Services XML Schema File CiscoIPPhone.xsd </xsd:restriction> </xsd:simpleType> </xsd:element> <xsd:element name="Depth"> <xsd:simpleType> <xsd:restriction base="xsd:unsignedShort"> <xsd:minInclusive value="1"/> <xsd:maxInclusive value="2"/> </xsd:restriction> </xsd:simpleType> </xsd:element> <xsd:element name="Data" minOccurs="0"> <xsd:simpleType> <xsd:restriction base="xsd:hexBinary"> <xsd:maxLength value="2162"/> <xsd:minLength value="0"/> </xsd:restriction> </xsd:simpleType> </xsd:element> <xsd:element name="MenuItem" type="CiscoIPPhoneMenuItemType" minOccurs="0"...
  • Page 105 Appendix B Cisco Unified IP Phone Services XML Schema File CiscoIPPhone.xsd <xsd:sequence> <xsd:element name="Text" minOccurs="0"> <xsd:simpleType> <xsd:restriction base="xsd:string"> <xsd:minLength value="0"/> <xsd:maxLength value="32"/> </xsd:restriction> </xsd:simpleType> </xsd:element> <xsd:element name="Timer" minOccurs="0"> <xsd:simpleType> <xsd:restriction base="xsd:unsignedShort"> <xsd:minInclusive value="0"/> </xsd:restriction> </xsd:simpleType> </xsd:element> <xsd:element name="LocationX" default="0" minOccurs="0">...
  • Page 106 Appendix B Cisco Unified IP Phone Services XML Schema File CiscoIPPhone.xsd </xsd:sequence> </xsd:complexType> </xsd:element> <xsd:element name="CiscoIPPhoneStatusFile"> <xsd:complexType> <xsd:sequence> <xsd:element name="Text" minOccurs="0"> <xsd:simpleType> <xsd:restriction base="xsd:string"> <xsd:minLength value="0"/> <xsd:maxLength value="32"/> </xsd:restriction> </xsd:simpleType> </xsd:element> <xsd:element name="Timer" minOccurs="0"> <xsd:simpleType> <xsd:restriction base="xsd:unsignedShort"> <xsd:minInclusive value="0"/> </xsd:restriction>...
  • Page 107: I N D E X

    CGI script supported URIs Execute supported XML objects 2-2, 2-15, 2-16 Screenshot client requests, using HTTP Cisco IP Phone Services Software Development Kit (SDK) content expiration, header setting components cookie behavior development tools sample services description requirements...
  • Page 108 2-13 header settings, for HTTP icon, grayscale 2-12 HTML URL text DeviceInformation MIME type, for HTTP DeviceLog?n EthernetInformation EthernetInformation?n NetworkConfiguration StreamingStatistics?n NetworkConfiguration HTTP Next softkey client requests header settings Cisco Unified IP Phone Services Application Development Notes IN-2 OL-18696-01...
  • Page 109 RTPMTx, used as URI 4-10 troubleshooting error messages tips XML parsing errors Screenshot, CGI script SDK. See Cisco IP Services Software Development Kit (SDK) Search softkey uniform resource identifiers (URI) Select softkey description server requests, using HTTP miscellaneous...
  • Page 110 Index DeviceInformationX DeviceLogX?n EthernetInformationX NetworkConfigurationX PortInformationX?nX StreamingStatisticsX?n Cisco Unified IP Phone Services Application Development Notes IN-4 OL-18696-01...

This manual is also suitable for:

7900 series