Cisco OL-18696-01, Development Manual

Page 1: ...est Tasman Drive San Jose CA 95134 1706 USA http www cisco com Tel 408 526 4000 800 553 NETS 6387 Fax 408 527 0883 Cisco Unified IP Phone Services Application Development Notes Supporting XML Applications Release 7 1 2 Text Part Number OL 18696 01 ...

Page 2: ...SSIBILITY OF SUCH DAMAGES CCDE CCENT Cisco Eos Cisco HealthPresence the Cisco logo Cisco Lumin Cisco Nexus Cisco StadiumVision Cisco TelePresence Cisco WebEx DCE and Welcome to the Human Network are trademarks Changing the Way We Work Live Play and Learn and Cisco Store are service marks and Access Registrar Aironet AsyncOS Bringing the Meeting To You Catalyst CCDA CCDP CCIE CCIP CCNA CCNP CCSP CC...

Page 3: ... 2 CiscoIPPhone XML Objects 2 1 Understanding Object Behavior 2 1 XML Object Definitions 2 3 CiscoIPPhoneMenu 2 3 CiscoIPPhoneText 2 4 CiscoIPPhoneInput 2 4 CiscoIPPhoneDirectory 2 6 Custom Directories 2 7 CiscoIPPhoneImage 2 7 CiscoIPPhoneImageFile 2 9 CiscoIPPhoneGraphicMenu 2 10 CiscoIPPhoneGraphicFileMenu 2 11 CiscoIPPhoneIconMenu 2 12 CiscoIPPhoneIconFileMenu 2 13 CiscoIPPhoneStatus 2 14 Cisc...

Page 4: ...g Schema 3 2 Error Schema 3 4 Examples 3 5 Errors and Responses 3 5 C H A P T E R 4 Internal URI Features 4 1 Supported URIs by Phone Model 4 2 Device Control URIs 4 3 Key 4 3 Display 4 4 XML Displayable Object URIs 4 4 SoftKey 4 4 QueryStringParam 4 6 Multimedia URIs 4 7 RTP Streaming 4 7 RTPRx 4 8 RTPTx 4 9 RTPMRx 4 9 RTPMTx 4 10 Play 4 10 Vibrate 4 11 Telephony URIs 4 11 Dial 4 11 EditDial 4 12...

Page 5: ...Phone Clients 5 7 x CiscoIPPhoneModelName 5 7 x CiscoIPPhoneDisplay 5 7 x CiscoIPPhoneSDKVersion 5 7 Accept Header 5 8 Accessing IP Phone Information 5 8 C H A P T E R 6 Troubleshooting Cisco Unified IP Phone Service Applications 6 1 Troubleshooting Tips 6 1 XML Parsing Errors 6 1 Error Messages 6 2 C H A P T E R 7 Cisco IP Phone Services Software Development Kit SDK 7 1 SDK Components 7 1 Sample ...

Page 6: ...nologies 9 3 Supported Platforms 9 3 Prerequisites 9 3 Message and Interface Definitions 9 3 DeviceList XML Object 9 3 Troubleshooting DeviceListX Reports 9 4 Error Codes 9 4 Determining Problems With the Interface 9 5 A P P E N D I X A CiscoIPPhone XML Object Quick Reference A 1 A P P E N D I X B Cisco Unified IP Phone Services XML Schema File B 1 Updated XML Parser and Schema Enforcement B 1 Cis...

Page 7: ...o Developer Support Program The Developer Support Program was developed to provide formalized support for Cisco interfaces to accelerate the delivery of compatible solutions to Cisco customers The program web site at http developer cisco com provides a central resource point for all your development needs Program Benefits Product and document downloads Bug reports Sample scripts Frequently Asked Q...

Page 8: ...TP Requests and Header Settings Provides a procedure on handling HTTP client requests definitions for HTTP header elements identifies the capabilities of the requesting IP phone client and defines the Accept header Chapter 6 Troubleshooting Cisco Unified IP Phone Service Applications Provides troubleshooting tips XML parsing errors and error messages Chapter 7 Cisco IP Phone Services Software Deve...

Page 9: ...equest 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 Subscribe to the What s New in Cisco Product Documentation as a Really Simple Syndication RSS feed and set content to be delivered directly to your desktop using a rea...

Page 10: ...onvention 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 x y z Optional alternative keywords are grouped in brackets an...

Page 11: ...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 The user then chooses a service from the list and the phone displays the service The following list gives typical services that might be supplied to a phone Weather Stock information Contact information Company news To do lists Daily sc...

Page 12: ...d the user interacts with the object Figure 1 3 and Figure 1 4 show typical displays that result from selecting a service Figure 1 3 shows a stock quote that was generated using plain text and Figure 1 4 displays a graphic image Figure 1 3 Plain Text Display Example Figure 1 4 Graphic Image Display Example Cisco Unified Communications Manager limits Cisco Unified IP Phone service activity to a spe...

Page 13: ...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 ...

Page 14: ...1 4 Cisco Unified IP Phone Services Application Development Notes OL 18696 01 Chapter 1 Overview ...

Page 15: ...oes 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 Appropriate behavior depends solely on the type of data that has been delivered in the page T...

Page 16: ... 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 X X X CiscoIPPhoneImageFile X X CiscoIPPhoneGraphicMenu X1 X X X CiscoIPPhoneGraphicFileMenu X X 2 2 The Cisco Unified IP Phones 6921 6941 and 6961 do not support CiscoIPPhoneGraphicFileMenu because these phones use monochrome LCM CiscoIPPhoneIconMenu X3 3 The Cisco Unified I...

Page 17: ...used for built in menus in the phone as described in Chapter 1 Overview 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 CiscoIPPhoneMenu Note The Name field under the MenuItem supports a maximum of 64 characters This field can also accept two carriag...

Page 18: ... Prompt defines text that displays at the bottom of the display page If a Prompt is not specified Cisco Unified Communications Manager clears the prompt area of the display pane Many XML objects that are described in this document also have Title and Prompt fields These fields normally behave identically to behavior described in this section Note Non XML Text This document only describes the suppo...

Page 19: ... query string The parameters include Name Value pairs one for each input item Note CiscoIPPhoneInput objects do not use the HTTP POST method The InputItem tag delimits each item in the list The number of InputItems must not exceed five Each input item includes a DisplayName which is the prompt that is written to the display for that particular item Each item also has a QueryStringParam which is th...

Page 20: ...t Prompt text goes here Prompt DirectoryEntry Name The name of the directory entry Name Telephone The telephone number for the entry Telephone DirectoryEntry CiscoIPPhoneDirectory 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...

Page 21: ...ou can display multiple CiscoIPPhoneDirectory objects 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 softkey on the phone CiscoIPPhoneImage The CiscoIPPhoneImage provides a bitmap display with a 133 x 65 pixel pane that is available to access services Each pixel includes four grayscale settings A valu...

Page 22: ...al digits represents each byte Figure 2 3 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 re...

Page 23: ... phone recognizes the content as a compressed binary PNG image The PNG image can be either palettized or RGB and the maximum image size and color depth are model dependent see Table 2 2 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 To reduce the number of colors in a gr...

Page 24: ...eFile 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 informat...

Page 25: ... application developers The CiscoIPPhoneGraphicFileMenu behaves similar to the CiscoIPPhoneGraphicMenu in that a group of options are presented by an image When one of those objects is selected a URL action initiates However the new FileMenu does not use the keypad but uses rectangular touch areas This rectangular touch area TouchArea is defined by coordinates relative to the upper left corner of ...

Page 26: ...d and unread icon in a mail viewer You can use the icons can to convey the message state Icons in the CiscoIPPhoneMenu object have a maximum width of 16 pixels and a maximum height of 10 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 ...

Page 27: ... 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 2 7 Icons in the CiscoIPPhoneIconFileMenu object have a maximum width of 18 pixels and a maximum height of 18 pixels Instead of using the Data tag to embed the image data into the IconItem tag this object uses a URL tag to point to the PNG image file to ...

Page 28: ...o clear an existing Status object before sending a new Status object The new object simply replaces the old object Figure 2 8 shows the CiscoIPPhoneStatus object that contains the following visual elements 106 x 21 graphics area for displaying CIP images same image format as CiscoIPPhoneImage Seedable free running timer optional Single line text area optional Figure 2 8 IconMenu on a CiscoIPPhoneS...

Page 29: ...the maximum width allowed the Image Area can be resized If the image provided is smaller than the minimum width the minimum allowed window width should be used If the width of the image provided is between the minimum and maximum sizes of the window the window should be sized to display the image as well as the standard surrounding borders The image height should never change See Table 2 3 for an ...

Page 30: ... CiscoIPPhoneStatusFile Text This is the text area Text Timer Timer seed value in seconds Timer LocationX Horizontal alignment LocationX LocationY Vertical alignment LocationY URL location of the PNG image URL CiscoIPPhoneStatusFile Note that instead of using the Data tag to embed the image data this object uses a URL tag to point to the PNG image file to be used for the graphics area CiscoIPPhone...

Page 31: ...fied Communications Manager Administration Enterprise Parameters and can be overridden on a per phone basis in the Cisco Unified Communications Manager Device configuration The following table lists the Priority levels and their behavior Note The Priority attribute is only used for HTTP URLs Internal URIs always execute immediately Example The following CiscoIPPhoneExecute object results in the ph...

Page 32: ...n optional error message to further 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 CiscoIPPhoneStatus object which cannot control softkeys and the CiscoIPPhoneExecute object which is not displayable Softkeys can have either URL or URI actions associated with them The Softk...

Page 33: ... internal softkey features Note If there are no custom softkeys and there is no default softkey placed in position 1 either a Next or Update softkey is assigned automatically If the URL is a Refresh URL the softkey will be Next If not the Update softkey is assigned Example The following softkey definitions would provide the custom softkey without losing the default Select behavior SoftKeyItem Name...

Page 34: ...cify UTF 8 as the default encoding so any UTF 8 encoded XML object must have the encoding explicitly set for the phone to parse it correctly The encoding value specified in the XML header must match one of the encodings provided by the IP Phone in its Accept Charset HTTP request header as shown in the example below Example The following examples illustrate UTF 8 and ISO 8859 1 encoding respectivel...

Page 35: ...ation Manager API 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 36: ...ext has gained focus or The application was navigated to either directly by the user or by a refresh header or HTTP push Note If a Notify URI is used as the event handler a notification is sent with this default data notifyApplicationEvent appId appId type focusGained onAppMinimized Invoked when the application is minimized An application can only be minimized programmatically by a call to App Min...

Page 37: ...riction base xs string xs minLength value 1 xs maxLength value 64 xs restriction xs simpleType 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 Cis...

Page 38: ...2 24 Cisco Unified IP Phone Services Application Development Notes OL 18696 01 Chapter 2 CiscoIPPhone XML Objects Application Event Handlers ...

Page 39: ... section on page 2 21 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 It extends capabilities beyond the legacy RTP streaming URIs by providing support for stream start stop even...

Page 40: ...ll services RTP streams in any direction send or receive and of any type multicast and unicast This allows applications using the RTP Streaming API to stop media streams which may have been started by the legacy RTP URIs or by other applications for which a stream ID is not known RTP Streaming Schema Note The port number parameter of the startMedia request is optional and if it is not specified th...

Page 41: ...t xs complexType name mediaStream xs all xs element name type xs simpleType xs restriction base xs string xs enumeration value audio xs restriction xs simpleType xs element xs element name codec xs simpleType xs restriction base xs string xs enumeration value G 711 xs enumeration value G 722 xs enumeration value G 723 xs enumeration value G 728 xs enumeration value G 729 xs enumeration value GSM x...

Page 42: ... xs integer xs minInclusive value 0 xs maxInclusive value 100 xs restriction xs simpleType xs attribute xs complexType xs schema Error Schema xml version 1 0 encoding UTF 8 xs schema xmlns xs http www w3 org 2001 XMLSchema elementFormDefault qualified attributeFormDefault unqualified xs element name errorResponse xs complexType xs all xs element name type xs simpleType xs restriction base xs strin...

Page 43: ... Response HTTP200 OK mediaStream id abc123 Stop Media Request HTTP POST CGI Execute stopMedia mediaStream id abc123 stopMedia Response HTTP 200 OK 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 notifyMediaEvent type stopped origin user mediaStream id abc123 notifyMediaEvent Errors and Responses Err...

Page 44: ...t InfalidXML parser error description Media cannot be started because no DSP resources is available to handle the media startMedia 400 BadRequest Unavailable Resource No Media Resource Available Media cannot be stopped because the specified stream ID does not exist stopMedia 400 BadRequest InvalidResourceID UnknownMedia Stream ID streamID Condition Applicable Methods HTTP Result Code Type Data ...

Page 45: ...e identifiers URIs provide access to embedded phone features such as placing calls playing audio files and invoking built in object 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 ...

Page 46: ...cator 7970G 7971G GE 7975G 6921 6941 6961 Key X X X X X X X X Softkey X X X X X X X X Init X X X X X X X X Dial EditDial X X X X X X X X Play X X X X X X X X QueryStringParam X X X X X X X X Unicast RTP X X X1 1 Only supports one incoming and one outgoing unicast stream and does not support the Volume parameter for RTP Receive streams X X X X X Multicast RTP X X X X X X X X Display X Vibrate X X N...

Page 47: ...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 URI Format Key n Where n 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 Soft5...

Page 48: ... phone state remains in the specified state unless activated by automated or user input Value must be an integer ranging from 0 1440 minutes If the value is set to 0 the display remains in the indicated state indefinitely unless activated by automated or user input For example Display Off 60 turns the phone display off for 1 hour 60 minutes Display On 10 turns the phone display on for 10 minutes D...

Page 49: ...y 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 Table 4 2 Valid Softkey Actions for CiscoIPPhoneObject Types IPPhoneObject1 1 The SoftKey URI is not allowed in an Execute object Select Exit Update Submit Search Cancel Next Dial Edit Dial CiscoIPPhoneMenu X X CiscoIPPhoneIconMenu...

Page 50: ... 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 If the user presses either custom softkey the currently highlighted MenuItem URI value gets appended to the softkey URL that was pressed and requested from the web server If you highlight the first Menu...

Page 51: ...e 1 action read 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 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 follo...

Page 52: ... URI request was done via push then the associated application is responsible for using push Priority attributes and for stopping and starting the stream If the user initiates the Rx URI via an application then the user likely is not concerned about having the audio mixed with the current call However they should also be presented with an option to stop the application when needed For the Rx URI t...

Page 53: ...itting 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 Stop the parameter that will stop any active RTP stream from being transmitted on channel one RTPMRx The RTPMRx URI instructs the ph...

Page 54: ...fter the playback has completed Interaction with Incoming Calls The Play URI and incoming calls ringing have equal priority access to the DSP ringer resources resulting in the following interactions If a Play URI is currently playing an incoming call ringing will not preempt the Play URI the Play URI will finish playing first If the phone is ringing and a Play URI request is sent to the phone the ...

Page 55: ...e 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 For example Vibrate 1000 0 1 initiates a single vibrate for 1 second Vibrate 500 1500 5initiates five vibrations each lasting for 500 ms follo...

Page 56: ... 1 0 false 1 true Default value 0 applicationId The unique name of the XSI web application requesting this call Value Type String Values minLength 1 no maxLength cannot contain semicolons should be in the format Company Product Default value Nil which means this dial request will not be associated with any application audibleFeedback Whether or not to provide audible feedback to the user when the ...

Page 57: ...annot contain colons The default value is null indicating that the active call should receive the DTMF digits regardless of any application association For example Make a call using a calling card service that implements these steps 1 Connects to a 800 calling card service using the Dial URI 2 Application waits to give call time to connect 3 Dials the destination number ensuring that the digits ca...

Page 58: ...n it has no effect Messages When the phone encounters an Init Messages URI it closes the Messages application If Messages is not currently open it has no effect Directories When the phone encounters an Init Directories URI it closes the Directories application If Directories is not currently open it has no effect Notify The Notify URI generates network notifications to back end applications This f...

Page 59: ... use for the Notify connection http is the only supported protocol host network host designated to receive the notification Value must be entered as a hostname or IP address port network port to use for the Notify connection Value must be a number from 1 65535 path protocol specific information Value cannot contain colons or semicolons credentials optional protocol specific credentials used to aut...

Page 60: ...8 Host myserver 8080 Content Length 5 Called from SoftKey with QueryStringParam URI CiscoIPPhoneMenu MenuItem Name Voicemail1 Name URL QueryStringParam id 1 URL MenuItem MenuItem Name Voicemail2 Name URL QueryStringParam id 2 URL MenuItem SoftKeyItem Name Play Name URL Notify http vmailSrvr 8080 path play URL SoftKeyItem CiscoIPPhoneMenu If the Voicemail2 menu item was selected when the Play softk...

Page 61: ...on from actually gaining focus Applications must use onAppFocusGained event handlers see the Application Event Handlers section on page 2 21 to know when focus is actually gained If the requested application is Open but not currently Active this request will not succeed error response If the application already has focus the request has no effect ReleaseFocus Makes a request to the application man...

Page 62: ...quests Any pending timers are automatically cancelled when the displayable object changes for an application context applicationId optional identifier of the application on which the action should be taken Values must range in length from 1 64 string characters and cannot contain colons The default value is the application of the displayable object in which the URI is defined Note If the Applicati...

Page 63: ... GET The following description designates how HTTP client requests are handled 1 The Cisco Unified IP Phone HTTP client performs an HTTP GET for a specified URL 2 The HTTP server processes request and returns an XML object or plain text 3 The phone processes the supported HTTP headers 4 The phone parses the XML object if ContentType is text xml 5 The phone presents data and options to the user or ...

Page 64: ...ne that contains an ExecuteItem pointing to the URL of the large object Note JTAPI also can push an XML object directly to an IP phone with the added benefit of not requiring authentication since the JTAPI connection itself is already authenticated This option works particularly well for adding XML services interfaces to existing CTI applications where the overhead of the CTI connection is already...

Page 65: ...e 5 1 shows an example of how to use the refresh setting This sample page shows the user the current value of Cisco stock 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 5 1 Refresh Display Sampl...

Page 66: ...to the phone from a web server by 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 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 Note The audio file should not be lon...

Page 67: ...he identifier is commonly referred to as a session ID Most Web servers have a built in session management layer that uses this second type of cookie which is commonly referred to as a session cookie The following example shows the Set Cookie header that is returned to the browser when a request method is used Set Cookie ASPSESSIONIDGQGQGRLS OCPNMLFDBJIPNIOOKFNFMOAL path The Cisco Unified IP Phone ...

Page 68: ... advertise their supported encodings using the standard HTTP Accept Charset header Per HTTP standard q values are used to specify preferred encodings The older phone models with more limited UTF 8 support will specify a lower q value for UTF 8 than the default user locale encoding For example an older phone model configured with the English_United_States user locale would include an Accept Charset...

Page 69: ...ries between different models Some examples of manufacturing Model Names are CP 7960 CP 7960G CP 7940G CP 7905G and CP 7970G x CiscoIPPhoneDisplay This Cisco proprietary header contains the display capabilities of the requesting device with the following four parameters listed in the order in which they appear Width in pixels Height in pixels Color depth in bits A single character indicating wheth...

Page 70: ... by appending the sub type the part after the slash onto CiscoIPPhone The content type can also include an optional version to indicate support for a particular SDK version of that object If a version is not specified then the x CiscoIPPhoneSDKVersion is implied The syntax of the version number may vary but in general will be as follows major version minor version maintenance version Here are some...

Page 71: ... debug and error messages where n is a model specific log number typically in the range 0 2 StreamingStatistics n StreamingStatisticsX n Current RTP streaming stats where n is model specific RTP stream identifier typically in the range 1 3 CGI Execute1 The target URL of a phone push HTTP POST request CGI Screenshot1 Returns an exact snapshot of the current phone display The size and format of the ...

Page 72: ...5 10 Cisco Unified IP Phone Services Application Development Notes OL 18696 01 Chapter 5 HTTP Requests and Header Settings Accessing IP Phone Information ...

Page 73: ...question with Microsoft Internet Explorer or download and verify with another web browser 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 Verify the object tags the object tags are...

Page 74: ...y the directory entry but there will be no Name associated with it CiscoIPPhoneInput Object The URL and QueryStringParam fields are mandatory The original parser would not report an error on the missing URL and on submit request would display a Host not Found message If the QueryStringParam field is missing the updated parser will report an error SoftKeyItem The Position field is mandatory If the ...

Page 75: ...ontact Cisco Developer Services to obtain the SDK at http developer cisco com web ipps These sections describe the Cisco IP Phone Services SDK SDK Components Sample Services Requirements SDK Components The following list contains the components that are included in the SDK Documentation Cisco IP Services Development Notes PDF format Cisco URL Proxy Guide Rich Text Format Cisco LDAP Programming Gui...

Page 76: ...0 Used for parsing XML data automatically installed 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 Communications Manager server Cisco Unified IP Phone XML Schema xsd file Used wi...

Page 77: ...y Microsoft IIS 4 0 or later for ASP sample services Sun J2SE 1 4 2 or later and Tomcat 4 0 or later for JSP sample services Internet Connection to external websites like Yahoo com Cnn com etc Cisco Unified Communications Manager 4 1 2 or later Cisco Unified IP Phones that supports XML services The setup program installs a CiscoServices web project to c CiscoIpServices directory The sample service...

Page 78: ...7 4 Cisco Unified IP Phone Services Application Development Notes OL 18696 01 Chapter 7 Cisco IP Phone Services Software Development Kit SDK Sample Services Requirements ...

Page 79: ...nager Administration Accessing Phone Service Administration Adding a Phone Service Defining IP Phone Service Parameters User Service Subscription Accessing Phone Service Administration To access phone service administration open Cisco Unified Communications Manager Administration and choose Device Device Settings Phone Services Phone services can have any number of parameters associated with them ...

Page 80: ...acters for the service name ASCII Service Name Enter the name of the service to display if the phone cannot display Unicode Service Description Enter a description of the content that the service provides Service URL Enter the URL of the server where the IP phone services application is located Make sure that this server remains independent of the servers in your Cisco Unified Communications Manag...

Page 81: ...when the service is created You cannot modify it Table 8 1 IP Phone Service Configuration Settings continued Field Description Table 8 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 di...

Page 82: ... Subscription End users can configure service subscriptions using the Cisco Unified CM User Options After users log in and choose a device a list of services that are assigned to the phone displays The user can then configure these services adding additional ones or removing un used services These password protected windows are authenticated via the LDAP directory Users can personalize their servi...

Page 83: ... the Real Time Information Service These sections provide details about the DeviceListX Report Benefits Restrictions Integration Considerations and Interoperability Performance and Scalability Security Related Features and Technologies Supported Platforms Prerequisites Message and Interface Definitions DeviceList XML Object Troubleshooting DeviceListX Reports Note DeviceListX does not support all ...

Page 84: ...actice the developer application should pull and cache the DeviceListX report refreshing only as often as required typically every few hours or daily Integration Considerations and Interoperability The interface allows HTTP 1 1 or HTTP 1 0 GET requests for the report The report returns data that is encapsulated by using XML version 1 0 Performance and Scalability You can run this report on the lar...

Page 85: ... Manager Administration reporting infrastructure The following releases support DeviceListX asp Cisco CallManager Release 3 2 3 SPB Cisco Unified CallManager Release 4 0 1 and later Prerequisites You can access this feature when devicelistX asp resides in the C ciscoWebs Admin reports directory of the Cisco Unified Communications Manager publisher server Message and Interface Definitions Use the f...

Page 86: ...c to this report interface follow Table 9 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 c Device Calling Search Space String value that is specified in the database p Device...

Page 87: ...s Note Cisco recommends that you wait longer than 60 seconds between requests Determining Problems With the Interface Use the following procedure to determine whether a problem exists with the interface and determine the root cause of the problem Procedure Step 1 Check the Windows NT Event Logs for error messages that pertain to the IIS server and the SQL server Start Programs Administrative Tools...

Page 88: ...9 6 Cisco Unified IP Phone Services Application Development Notes OL 18696 01 Chapter 9 DeviceListX Report Troubleshooting DeviceListX Reports ...

Page 89: ...mpt The prompt text goes here Prompt Text Text to display as the message body goes here Text CiscoIPPhoneText CiscoIPPhoneInput 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 input field to display DisplayName QueryStringParam The parameter to be added to the target U...

Page 90: ...honeGraphicMenu 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 ...

Page 91: ... 0 to 9 Index URL location of the PNG icon image URL IconItem CiscoIPPhoneIconFileMenu CiscoIPPhoneStatus CiscoIPPhoneStatus Text This is the text area Text Timer Timer seed value in seconds Timer LocationX Horizontal alignment LocationX LocationY Vertical alignment LocationY Width Pixel width of graphic Width Height Pixel height of graphic Height Depth Color depth in bits Depth Data Hex binary im...

Page 92: ...A 4 Cisco Unified IP Phone Services Application Development Notes OL 18696 01 Appendix A CiscoIPPhone XML Object Quick Reference ...

Page 93: ... 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 Cisco recommends that developers verify that their existing applications confo...

Page 94: ...6 xsd minLength value 1 xsd restriction xsd simpleType xsd attribute xsd complexType xsd complexType name CiscoIPPhoneResponseItemType xsd sequence xsd element name Status type xsd short xsd element name Data xsd simpleType xsd restriction base xsd string xsd maxLength value 32 xsd restriction xsd simpleType xsd element xsd element name URL xsd simpleType xsd restriction base xsd string xsd maxLen...

Page 95: ... base xsd string xsd maxLength value 32 xsd minLength value 0 xsd restriction xsd simpleType xsd element xsd sequence xsd complexType xsd complexType name CiscoIPPhoneInputItemType xsd sequence xsd element name DisplayName minOccurs 0 xsd simpleType xsd restriction base xsd string xsd maxLength value 32 xsd minLength value 0 xsd restriction xsd simpleType xsd element xsd element name QueryStringPa...

Page 96: ...n xsd simpleType xsd element xsd element name URL minOccurs 0 xsd simpleType xsd restriction base xsd string xsd maxLength value 256 xsd minLength value 0 xsd restriction xsd simpleType xsd element xsd sequence xsd complexType xsd complexType name CiscoIPPhoneIconItemType xsd sequence xsd element name Index type xsd unsignedShort xsd element name Width xsd simpleType xsd restriction base xsd unsig...

Page 97: ...Length value 0 xsd restriction xsd simpleType xsd element xsd element name IconIndex minOccurs 0 xsd simpleType xsd restriction base xsd short xsd minInclusive value 0 xsd maxInclusive value 9 xsd restriction xsd simpleType xsd element xsd sequence xsd complexType xsd complexType name CiscoIPPhoneIconFileItemType xsd sequence xsd element name Index xsd simpleType xsd restriction base xsd unsignedS...

Page 98: ...t name URL minOccurs 0 xsd simpleType xsd restriction base xsd string xsd minLength value 0 xsd maxLength value 256 xsd restriction xsd simpleType xsd element 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 CiscoIPPhoneSoftKe...

Page 99: ...ement xsd element name SoftKeyItem type CiscoIPPhoneSoftKeyType minOccurs 0 maxOccurs 8 xsd element name KeyItem type CiscoIPPhoneKeyType minOccurs 0 maxOccurs 32 xsd sequence xsd attribute name keypadTarget use optional default application xsd simpleType xsd restriction base xsd string xsd enumeration value application xsd enumeration value applicationCall xsd enumeration value activeCall xsd res...

Page 100: ...3 xsd sequence xsd complexType xsd element xsd element name CiscoIPhoneResponse xsd complexType xsd sequence xsd element name ResponseItem type CiscoIPPhoneResponseItemType maxOccurs 3 xsd sequence xsd complexType xsd element xsd element name CiscoIPPhoneError xsd complexType xsd attribute name Number type xsd unsignedShort use required xsd complexType xsd element xsd element name CiscoIPPhoneText...

Page 101: ...mplexType xsd element xsd element name CiscoIPPhoneImage xsd complexType xsd complexContent xsd extension base CiscoIPPhoneDisplayableType xsd sequence xsd element name LocationX default 0 minOccurs 0 xsd simpleType xsd restriction base xsd short xsd minInclusive value 1 xsd maxInclusive value 132 xsd restriction xsd simpleType xsd element xsd element name LocationY default 0 minOccurs 0 xsd simpl...

Page 102: ...ement name LocationX default 0 minOccurs 0 xsd simpleType xsd restriction base xsd short xsd minInclusive value 1 xsd maxInclusive value 297 xsd restriction xsd simpleType xsd element xsd element name LocationY default 0 minOccurs 0 xsd simpleType xsd restriction base xsd short xsd minInclusive value 1 xsd maxInclusive value 167 xsd restriction xsd simpleType xsd element xsd element name URL xsd s...

Page 103: ...PhoneIconFileItemType minOccurs 0 maxOccurs 10 xsd sequence xsd attribute name IconIndex type xsd unsignedShort use optional xsd extension xsd complexContent xsd complexType xsd element xsd element name CiscoIPPhoneGraphicMenu xsd complexType xsd complexContent xsd extension base CiscoIPPhoneDisplayableType xsd sequence xsd element name LocationX default 0 minOccurs 0 xsd simpleType xsd restrictio...

Page 104: ...nt xsd element name CiscoIPPhoneGraphicFileMenu xsd complexType xsd complexContent xsd extension base CiscoIPPhoneDisplayableType xsd sequence xsd element name LocationX default 0 minOccurs 0 xsd simpleType xsd restriction base xsd short xsd minInclusive value 1 xsd maxInclusive value 297 xsd restriction xsd simpleType xsd element xsd element name LocationY default 0 minOccurs 0 xsd simpleType xsd...

Page 105: ...ment xsd element name LocationY default 0 minOccurs 0 xsd simpleType xsd restriction base xsd short xsd minInclusive value 1 xsd maxInclusive value 20 xsd restriction xsd simpleType xsd element xsd element name Width xsd simpleType xsd restriction base xsd unsignedShort xsd minInclusive value 1 xsd maxInclusive value 106 xsd restriction xsd simpleType xsd element xsd element name Height xsd simple...

Page 106: ...restriction base xsd unsignedShort xsd minInclusive value 0 xsd restriction xsd simpleType xsd element xsd element name LocationX default 0 minOccurs 0 xsd simpleType xsd restriction base xsd short xsd minInclusive value 1 xsd maxInclusive value 261 xsd restriction xsd simpleType xsd element xsd element name LocationY default 0 minOccurs 0 xsd simpleType xsd restriction base xsd short xsd minInclu...

Page 107: ...IPPhoneImageFile 2 9 CiscoIPPhoneInput 2 4 CiscoIPPhoneMenu 2 3 CiscoIPPhoneResponse 2 17 CiscoIPPhoneStatus 2 14 CiscoIPPhoneStatusFile 2 16 CiscoIPPhoneText 2 4 supported phone models 2 2 understanding 2 1 Cisco Unified Communications Manager adding services 8 2 defining service parameters 8 3 subscribing to services 8 4 Cisco Unified IP Phone models accessing information about 5 8 supported dis...

Page 108: ...ttings for HTTP 5 2 HTML URL DeviceInformation 5 8 DeviceLog n 5 9 EthernetInformation 5 8 EthernetInformation n 5 9 NetworkConfiguration 5 8 StreamingStatistics n 5 9 HTTP client requests 5 1 header settings 5 2 accept 5 8 content expiration 5 4 MIME type 5 4 refresh setting 5 3 set cookie 5 5 x CiscoIPPhoneDisplay 5 7 x CiscoIPPhoneModelName 5 7 x CiscoIPPhoneSDKVersion 5 7 how used 5 1 server r...

Page 109: ... samples included with SDK 7 2 subscribing to in Cisco Unified Communications Manager 8 4 set cookie header setting 5 5 softkey 4 5 Cancel 4 5 Dial 4 5 EditDial 4 5 Exit 4 5 Next 4 5 Search 4 5 Select 4 5 Submit 4 5 Update 4 5 valid actions for object types 4 5 status displaying for applications 2 14 2 16 StreamingStatistics 5 9 Submit softkey 4 5 T text menus creating 2 3 text messages displaying...

Page 110: ...isco Unified IP Phone Services Application Development Notes OL 18696 01 DeviceInformationX 5 8 DeviceLogX n 5 9 EthernetInformationX 5 8 NetworkConfigurationX 5 8 PortInformationX nX 5 9 StreamingStatisticsX n 5 9 ...