Polycom SIP 3.1 manual

August, 2008 Edition 1725-17693-310 Rev. A SIP 3.1 W eb Application Developer’ s Guide for the Polycom ® SoundPoint ® IP/SoundStation ® IP Family SIP 3.1[...]

Polycom Inc. 4750 Willow Road Pleasanton, CA 94588-2708 USA No part of this document may be reproduce d or transmitted in any form or by any means, el ectronic or mechanical, for any purpose, without the express written permission of Polycom, Inc. Under the law, reprod ucing includ es translating into another language or format. As between the part[...]

iii About This Guide The Developer’s Guide for the SoundPoint IP / SoundStation IP family is for developers of applications which use the Web Server and the Microbrowser on SoundPoint IP / SoundStation IP phones. The following relat ed documents for Soun dPoint IP / SoundStation IP family are available: • Quick Start Guides, which describe how [...]

Developer’ s Guide SoundPoint IP / SoundStation IP iv[...]

v Contents About This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . iii 1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1–1 What is the Microbrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1–1 What is XHTML . . . . . . . . . . . . . . . . . . . [...]

Developer’ s Guide SoundPoint IP / SoundStation IP vi 3 Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–1 XML Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–1 A Appendix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . [...]

1 - 1 1 Over view This chapter provides an overview of the Web Serv er and the Microbrowser available on SoundPoint IP 330/32 0, 430, 501, 550 , 560, 60 0, 601, 650, and 67 0 desktop phones and SoundStation IP 4000, 6000, and 7000 co nference phones. It also provides an introduction to XHTML and guidelines for the application development. This chap[...]

Developer’ s Guide SoundPoint IP / SoundStation IP 1 - 2 The XHTML pages displayed on the Micr obrowser can contain static or dynamic information. Static XHTML. These pages are created us ing XHTML editors and hoste d by the Web server. These pages are accessed from the Microbrowser (usin g HTTP protocol) by entering the URL to a ccess the page. [...]

Over view 1 - 3 beyond a skeleton set were gro uped into individual modules . User agent (UA) developers could then d ecide which extensions to support. A s imple user agent can be considered a fully compli ant user agent by supporting only the Basic module, whereas a more powerful browser can support all the official modules, as well as those deve[...]

Developer’ s Guide SoundPoint IP / SoundStation IP 1 - 4 • Company directory • Stock ticker Dependin g on the type and complexity of the application, you might use one of the following tools for creation: • Text editor • XML editor • Microsoft Word When designing applicati ons, you migh t want to consider the following guidelines: 1. Sp[...]

Over view 1 - 5 New Features in SIP 3.1 The following new features were introduced in SIP 3.1: • SoundPoint IP/SoundStatio n IP XML API Application Interface —Expanded support in the Microb rowser for applications on the SoundPoint IP 320/330, 430 , 501, 550, 560, 650, and 670 desktop phones, and SoundStation IP 4000, 6000, and 7000 conference [...]

Developer’ s Guide SoundPoint IP / SoundStation IP 1 - 6[...]

2 - 1 2 Application Development This chapter presents step-by-step in structions on how to develop an XHTML application that can be run on the We b Server and Microbrowser of certain SoundPoint IP and SoundStation IP phones. It also describes the configuration parameters that can be found in the sip.cfg configuration file. This chapter contains inf[...]

Developer’ s Guide SoundPoint IP / SoundStation IP 2 - 2 • Meta Information Tags Unsupported elements and attributes are de scribed in Unsupported XHTML Elements on page A-1 . Basic T ags The following basic tags are supported: • <!DOCTYPE> —Defines the document type • <!--...--> —Defines a comment <!DOCTYPE> The <![...]

Application Development 2 - 3 <!--...--> The comment tag is used to insert a comment in the source code. A comment will be ignored by the browser. You can use comments to explain your code , which can help you when you edit the source code at a later date. This tag does not have any attributes. Link T ags The following link tag is supported: [...]

Developer’ s Guide SoundPoint IP / SoundStation IP 2 - 4 <form> The form element creates a form for user input. A form can contain text fields, check boxes, radio buttons and more. Forms are used to pass user d ata to a specified URL. The following attributes are supported: Note The Microbrowser supports both the GET and POST methods for su[...]

Application Development 2 - 5 <input> The <input> tag defines the start of an input field where the user can enter data. In XHTML the <input> tag must be properly closed. The following attributes are supported: Attribute Va l ue / s Description checked checked Indicates that the input elem ent should be checked when it first loads[...]

Developer’ s Guide SoundPoint IP / SoundStation IP 2 - 6 Image T ags The following image t ag is supported: • <img> —Defines an image The Microbrowser supports imag es stored in uncompressed .bmp format. While all BMP bit depths will be displayed to the best of the phone’s ability, it is recommended that the image format most suitable[...]

Application Development 2 - 7 Ta b l e Ta g s The following tabl e tags are supported: • <table> —Defines a table • <caption> —Defines a table caption • <th> —Defines a table header • <tr> —Defines a table row • <td> —Defines a table cell • <thead> —Defines a table header • <tbody>[...]

Developer’ s Guide SoundPoint IP / SoundStation IP 2 - 8 <caption> This element defines a table caption. The <caption> tag must be inserted immediately after the <table> tag. You can specify only one caption per table. Usually the caption will be centered above the table. The “align” attribute of the caption element is not s[...]

Application Development 2 - 9 bgcolor rgb(x,x,x) #xxxxxx colorname S pecifie s the background co lor of the table cell. Deprecated. Use styles instead. char character S pecifie s which character to align text on. Note: Only used if al ign="char"! charof f Pixels (num ber , EX: “30” ) % S pecifie s the alignmen t offset to the first ch[...]

Developer’ s Guide SoundPoint IP / SoundStation IP 2 - 10 <tr> This tag defines a row in a table. The following attributes are supported: <td> This tag defines a cell in a table. The following attributes are supported: class class_rule style_rule The class of the element title tooltip_text A text to display in a tool tip style style_d[...]

Application Development 2 - 11 <thead> This tag defines a table header. The thea d, tfoot and tbody elements enable you to group rows in a table. When you create a table, you might want to have a header row, some rows wi th data, and a row with totals at bottom. This division enables browsers to support sc rolling of table bod ies independent[...]

Developer’ s Guide SoundPoint IP / SoundStation IP 2 - 12 <tbody> This tag defines a table body. The thead, tfoot and tbody elements enable you to group rows in a tabl e. The following attributes are supported: <tfoot> This tag defines a table footer. The thea d, tfoot and tbody elements enable you to group rows in a tabl e. The follo[...]

Application Development 2 - 13 Meta Information T ags The following meta information tags are supported: • <head> —Defines information about the document <head> The head element can contain informat ion about the document. The browser does not display the “head information” to the user. The following tag can be in the head secti[...]

Developer’ s Guide SoundPoint IP / SoundStation IP 2 - 14 The SoundPoint IP/Sound Station IP XML API is intended to provide developers wit h flexibilit y in developi ng applications on SoundPoint IP and SoundStation IP phones, while tightly in tegrating into the phone’s telephony capabilities and functions. This expand ed support includ es: •[...]

Application Development 2 - 15 The supported actions are de scribed in the following table: Depending on the browser state, a number of predefined soft keys exist: Action Default Action Name Description SoftKey:Home Home Moves to configured h ome page Softkey:Back Back Move to previous page Softkey:Exit Exit Exits Microbrowser SoftKey:Refresh Refre[...]

Developer’ s Guide SoundPoint IP / SoundStation IP 2 - 16 The following should be noted with respect to softkey tags: • All actions are case insensitive. • If the soft key action name is empty, the soft key tag is ignored. • The Reset and Submit so ftkey tags must exis t inside the <form> tag that they are to act upon. • Indexes nee[...]

Application Development 2 - 17 The following format is supported: ActionType:Action where: • ActionType is a type of key or action to execute (Key, Softkey, Tel, or Play) • Action is the name of the action to be executed. The supported i nternal URIs are described in the following tabl e: Note Internal URI actions contained in a file with conte[...]

Developer’ s Guide SoundPoint IP / SoundStation IP 2 - 18 The following should be noted with respect to internal URIs: • The action name and key type are case insensitive. • For non-XHTML content containing only internal URIs, the internal URIs are executed in ascending order without any delay. • If any URI is inval id and it is in a file o[...]

Application Development 2 - 19 For example, to create a link th at behaves as if you pressed the Do Not Disturb key: <html> <body> <br/> Click on the link to engage the DND feature <a href="Key:DoNotDisturb">DNDSe ttings</a> </body> <softkey index="1" label="Back" action="Sof[...]

Developer’ s Guide SoundPoint IP / SoundStation IP 2 - 20 The following table describes when to use a specific priorit y: The following should be noted with respect to HTTP URI push: • By default, a Back soft key is placed on the graphic display. • The phone can hold a maximum of 10 push requests at any time. • Push requests are displayed a[...]

Application Development 2 - 21 Data Push The data push allows you to send messages in XHTML format to a specific phone. The following format is supported: <Data priority=”X” >Y</Data> The following attributes are supported: For example, to push the display of an important message: <PolycomIPPhone> <Data priority=”critical[...]

Developer’ s Guide SoundPoint IP / SoundStation IP 2 - 22 • Set apps.push.password to the appropriate password. For example, apps.push.password =1234 T elephony Notification Events The phone can be configured to send information to a specific URI if one of the following telephony notif ication events occurs: • Incoming Call Event • Outgoing[...]

Application Development 2 - 23 CallingPartyName name The name displayed in phon e's "From" label in screen. • If the line is registered and the call is initiated from that line, then the registered l ine display name of the calling party is shown. For example, “SoundPoint IP” • If the line is not registered an d the call is i[...]

Developer’ s Guide SoundPoint IP / SoundStation IP 2 - 24 When the telephone notification URI is set and the incoming call event is enabled to gather information, the following example shows the transmitted data for a call between two registered lines: <PolycomIPPhone> <IncomingCallEvent> <PhoneIP>172.24.132.135</Phon eIP>[...]

Application Development 2 - 25 Offhook Event The following format is supported: <OffHookEvent> <PhoneIP> </PhoneIP> <MACAddress> </MACAddress> <TimeStamp> </TimeStamp> </OffHookEvent> CallingPartyNumber nu mber • If the line is registered and th e call is initiated from that line, the registered lin[...]

Developer’ s Guide SoundPoint IP / SoundStation IP 2 - 26 The following attributes are supported: Onhook Event The following format is supported: <OnHookEvent> <PhoneIP> </PhoneIP> <MACAddress> </MACAddress> <TimeStamp> </TimeStamp> </OnHookEvent> The following attributes are supported: T elephony E[...]

Application Development 2 - 27 • Set apps.telNotification.incomingE vent to 1 or 0 (for Enable or Disable respectively). For example, apps.telNotification.incomi ngEvent =1 • Set apps.telNotification.outgoingE vent to 1 or 0 (for Enable or Disable respectively). For example, apps.telNotification.outgoi ngEvent =1 • Set apps.telNotification.of[...]

Developer’ s Guide SoundPoint IP / SoundStation IP 2 - 28 Call Line Information The following format is supported: <CallLineInfo> <LineKeyNum> </LineKeyNum> <LineDirNum> </LineDirNum> <LineState>Active</LineState> <CallInfo> <CallState> </CallState> <CallType> </CallType> <[...]

Application Development 2 - 29 When the phone state polling URL is set and the phone receives a Call Processing Request, the following example shows the transmitted data: <PolycomIPPhone> <CallLineInfo> <LineKeyNum>1</LineKeyNum> <LineDirNum>10</LineDirNum> <LineState>Connected</LineSta te> <CallIn[...]

Developer’ s Guide SoundPoint IP / SoundStation IP 2 - 30 <LineState>NotConnected</Line State> </CallLineInfo> <CallLineInfo> <LineKeyNum>3</LineKeyNum> <LineDirNum>36</LineDirNum> <LineState>NotConnected</Line State> </CallLineInfo> </PolycomIPPhone> Device Information The f[...]

Application Development 2 - 31 Network Configuration The following format is supported: <NetworkConfiguration> <DHCPServer></DHCPServer> <MACAddress>0004f214b8e7</MACAdd ress> <DNSSuffix></DNSSuffix> <IPAddress>172.24.128.160</IPAdd ress> <SubnetMask>255.255.255.0</Subne tMask> <P[...]

Developer’ s Guide SoundPoint IP / SoundStation IP 2 - 32 Phone State Polling Configuration Parameters The phone state polling conf iguration parameters in sip.cfg must be set as followed: • Set apps.statePolling.URL to the location where requested information should be sent. For example, apps.statePolling.URL =http://172.24.128.85:8080 If this[...]

Application Development 2 - 33 HTTP Suppor t The Microbrowser is a fully compliant HTTP/1.1 user agent: • It supports: — Cookies — Refresh headers — HTTP proxies — HTTP over SSL/TLS — Self-signed or custom CA certificates • There are the following exception s: — There is no sophisticated caching. The HTML cache refresh META tag is n[...]

Developer’ s Guide SoundPoint IP / SoundStation IP 2 - 34 • A n i n s t a n c e t h a t d o e s n o t s u p p o r t u s er input, but appears in a window on the idle display Launching the Microbrowser The first time the Applications ke y is press ed, the main Mic robrowser loads the home page specified in the mb.main.home configuration paramete[...]

Application Development 2 - 35 Whenever there is an event in the telephony application that requires the user's attention, the telephony applic ation is brought to the foreground automatically. The Microbrowser can be displaye d again by simply pushing the Applications key. While the Microb rowser application is not display ed, it is still act[...]

Developer’ s Guide SoundPoint IP / SoundStation IP 2 - 36 Developing an XHTML Application Changing Configuration Parameters Create a new configuration file in the style of sip.cfg so that users will connect to your application when they press the App licatio n key (or select the Application feature item). T o allow an application to be r un from [...]

Application Development 2 - 37 a Set apps.push.messageType to the appropriate display priority. For example, apps.push.messageType =3 b Set apps.push.serverRootURL to the application server root URL. For example, apps.push.serverRootURL =http://172.24.128.85:8080/sampleapps c Set apps.push.username to the appropriate username. For example, apps.pus[...]

Developer’ s Guide SoundPoint IP / SoundStation IP 2 - 38 b Set apps.statePolling.username to the appropriate username. For example, apps.statePolling.username =bob The username and password are requ ired to a uthentica te incoming polling requests to the phone. c Set apps.statePolling.password to the appropriate password. For example, apps.state[...]

Application Development 2 - 39 2. Configure the Web server to serve the above XHTML file. For example, if you are using Apache To mcat to try this example, then put this file into the webappsPLCM folder of Tomcat. 3. Configure SoundPoint IP and SoundStation IP phones to point to the XHTML file in the sip.cfg configuration file. For this example, c[...]

Developer’ s Guide SoundPoint IP / SoundStation IP 2 - 40 3. Write an application that is going to retrieve the stock informa tion from a data service provider. For this example, this a pplication will be retrieving stock information from Yahoo and will send it to the Microb rowser. This application is written using a Java Serv er Page (JSP). <[...]

Application Development 2 - 41 4. Configure the Web server to deploy the above JSP file. For example, if you are using Apache To mcat to try this example, put this file into the webappsPLCM folder of Tomcat. 5. Configure SoundPoint IP and SoundStation IP phones to point to the XHTML file in the sip.cfg configuration file. For this example, change [...]

Developer’ s Guide SoundPoint IP / SoundStation IP 2 - 42 • After the customer clicks Send Requ est , the page shown belo w is pushed to the customer support agent’s phone. The customer support agent can call the customer by just pressing the Select key, because the highlighted link contai ns a Tel URI with the customer’s phone number. T o [...]

Application Development 2 - 43 </body> </html> 2. Using Microsoft Vi sual Studio, create a file cal led webcallback.aspx.cs . using System; using System.IO; using System.Text; using System.Data; using System.Configuration; using System.Net; using System.Web; using System.Web.Security; using System.Web.UI; using System.Web.UI.WebContr ol[...]

Developer’ s Guide SoundPoint IP / SoundStation IP 2 - 44 string result = ""; // Create the web re quest HttpWebRequest reque st = (HttpWebRequest)WebRequest.C reate(strLoc); WebRequestState myRe questState = new WebRequestState (); myRequestState.reque st = request; request.Method = "PO ST"; request.Credentials = myCache; myR[...]

Application Development 2 - 45 // Write the data to the stream. streamResponse.Write (byteArray, 0, byteArray.Length) ; streamResponse.Close (); allDone.Set(); } } public class WebRequestState { public String postData = null; public WebRequest reques t; public WebRequestState() { request = null; } public String getPostDat a() { return postData; } p[...]

Developer’ s Guide SoundPoint IP / SoundStation IP 2 - 46[...]

3 - 1 3 T roubleshooting This chapter presents problems, li kely causes, and corrective actions. Problems are grouped as follows: • XML Errors If you still need as sistance, c ontact your system administrator. XML Errors Symptom Problem Corrective Action Improperly formatted tables could cause the phone to stop and restart or display the error ?[...]

Developer’ s Guide SoundPoint IP / SoundStation IP 3 - 2[...]

A - 1 A Appendix This appendix provides information on unsupported XHTML elements. Unsuppor ted XHTML Elements The unsupported elements and attributes are: Ta g Ty p e T a g Description Basic T ags <html>—Defines HTML document. <body>—Defines docu me nts’ body . <h1> to <h6>—Defines header 1 to header 6. <p>—[...]

Developer’ s Guide SoundPoint IP / SoundStation IP A - 2 Output T ags <pre>—Defines preformatted text. <code>—Defines computer code text. <tt>—Defines teletype text. <kbd>—Defines keyboard text. <var>—Defin es a va ri ab l e. <dfn>—De fi ne s a de fi n i ti on te rm. <samp>—Defines sample co[...]

Appendix A - 3 Input T ags <form>—Defines a form. The following attributes ar e not supp orte d: accept, accept charset, enctype, target, class, id, style, title, dir , lang, and accesskey . <input>—Defines an input field. The following attributes are not su pported: accept, align, alt, disabled, maxlength , readonly , size, arc, ty[...]

Developer’ s Guide SoundPoint IP / SoundStation IP A - 4 Ta b l e Ta g s <table>—Defines a table. The following atrribu te s are not supported: bgcolo r , frame, rules, summary , id, cla ss, title, style, dir , lang, and xml:lang. <col>—Defines attributes for table columns. <tr>—Defines a table row . The following attribut[...]

Index – 1 Index A application development process 2–36 B basic tags supported 2–2 unsupported A–1 block tags unsupported A–2 C character format tags unsupported A–1 configuration parameters, changes t o 2–36 F frame tags unsupported A–2 H HTTP support 2–33 I image tags supported 2–6 unsupported A–3 input tags supported 2–3 u[...]

Developer’ s Guide SoundPoint IP / SoundStation IP Index – 2 U unsupporte d attributes A–1 unsupported elements A–1 X XHTML, definition 1–2[...]

POLYCOM, INC. APPLICATION PROGRAMMING INTERF ACE LICENSE (“API”) FOR SOUNDPOINT IP AND SOUNDSTATION IP PRODUCTS (“Product” or “Products”). 1. Agreement . You understand and agree t hat by usi ng the API you will be bound by the terms of the End User License and Warranty Terms included with the Product(s) and this docu ment (together, th[...]

By downloading the following Sample Applic ations, you agree to the below end user license agreement. LICENSE AGREEMENT FOR DEVELOPMENT P URPOSES This License Agreement for Development Purposes (the "A greement") is a legal agreement between you and Polycom, Inc., a Delaware corporation ("Polycom "). The software you are about t[...]

2.3. Reservation. Polycom reserves all rights in the Software not expressly granted to you in this Agreement. 3. SUPPORT SERVICES. 3.1. No Support Services. Polycom provides no support services fo r the Software. 4. TERMINATION. 4.1. Termination. Without prejudice to any ot her rights, Polycom may term inate this Agreement if you fail to comply wit[...]

for certain products supplied to consumers or the limitation of liability for personal injury, so the above limitations and exclusions may be limited in thei r application to you. 8. EXPORT CONTROLS. 8.1. Export Controls. The Software may not be downloaded or otherwise exported or re- exported (i) into (or to a national or resident of) C uba, Iraq,[...]

agreement shall be construed to limit eithe r party's right to inde pendently develop or distribute software that is f unctionally similar to the other party's products, so long as proprietary information of the other part y is not included in such software. 9.5. Entire Agreement. This Agreement repres ents the complete agreem ent concern[...]