Cisco IP Phone Services Software Development Kit (SDK) User Manual

Cisco IP Phone Services SDK Overview
Page 1 of 9
The Cisco IP Phone Services SDK provides software libraries, API documentation, and
sample applications for developers of IP Telephony Applications. This SDK contains
sample ASP/Javascript and JSP/Java programs that serve as templates for a variety of
applications including web content delivery, Computer-Telephony Integration (CTI),
voice streaming, and CallManager API access.
For more information on Cisco IP Telephony Applications and partners, visit the
Applications Central website at
http://www.cisco.com/go/apps
Requirements:
Microsoft IIS 4.0 or later (for ASP sample services)
See Installing ASP Samples for additional information
Sun J2SE 1.4.2 or later and Tomcat 4.0 or later (for JSP sample services)
See Installing JSP Samples for additional information
Internet Connection to external websites like Yahoo.com, Cnn.com etc.
Cisco Call Manager 4.1(1) or later.
Cisco 7905, 7912, 7920, 7940, 7960, 7970 or other XML services-enabled IP
Phone
Contents:
I. Documentation
a. Cisco IP Services Development Notes (in pdf format)
b. Cisco URL Proxy Guide (Rich Text Format)
c. Cisco LDAP Programming Guide (Word format)
d. Cisco CIP Image Release Notes (Word format)
file://C:\CiscoIPServices\Documentation\Cisco_IP_Phone_Services_SDK_Overview.htm
9/12/2005
Cisco IP Phone Services SDK Overview
Page 2 of 9
e. Cisco IP Applications Samples (Word format)
II. Development Tools
a. Cip.8bi - Photoshop plug-in that allows .cip extensions to be veiwed and saved
b. Cip2Gif.exe - DOS based program which converts cip files to gif
c. Gif2Cip.exe - DOS based program which converts gif files to cip
d. ImageViewer.exe - Windows application that displays cip graphic files
e. Cisco CIPImage - used for converting images to/from CIP images (automatically
installed)
f. Cisco URL Proxy - Proxy server needed to use the sample services (automatically
installed)
g. Cisco LDAP Search - Service installed to do LDAP searches (automatically
installed)
h. Microsoft XML Parser (MXSML) 3.0 - used for parsing XML data (automatically
installed)
i. Cisco IP Phone Services ASP/Javascript Library (automatically installed)
j. Cisco IP Phone Services Java Library - used by the JSP apps (manually installed see JSP Install readme)
k. CallManager Simulator - used for developing Phone Services without a
CallManager server
l. Cisco IP Phone XML Schema (.xsd) file - used with an XML editor to validate XML
syntax
III. Sample Applications
1. Weather forecast lookup for any city (ASP)
This service will enable user to enter a city, state, or zip code, and get weekly weather forecast. The
current, low and high temperatures for the day and summary of the forecast will be displayed.
Here service retrieves the weather information from CNN weather website
http://weather.cnnaudience.com/cgi-bin/weather/redirect for given city zip code. If user provides city
name and state then corresponding city zip code is obtained from website
http://generalsearch.com/AreaCode/index.php.
2. Currency Exchange Rates and Converter (ASP)
This service will allow users to select a currency and view its exchange rate and perform conversions
with it. The currency type is entered by specific currency codes ( ex: USD for US Dollar, JPY Japanese
Yen etc.).
Here Service retrieves the currency Exchange information form Yahoo finance page:
http://finance.yahoo.com/q
3. UPS Rates & tracking (ASP)
This service will display the current UPS rates depending upon the specified Source - destination zip
file://C:\CiscoIPServices\Documentation\Cisco_IP_Phone_Services_SDK_Overview.htm
9/12/2005
Cisco IP Phone Services SDK Overview
Page 3 of 9
code, package type, package weight and type of UPS Services. The Package type can be of: Your
Packaging, UPS letter envelope, UPS Express box, UPS tube etc. The Service type can be: Regular
daily pickup, on call air, on time pickup, Drop box letter center, Custom counter etc. The Service for
tracking for package is also included in this sample.
The UPS rate information is obtained from UPS web site:
http://ups.com/using/services/rave/qcosthtm.cgi.
4. World Clock (ASP)
This service will show the current time for given city.
The current time information is obtained from web site: http://timeanddate.com/worldclock/results.html?
query=+query_str.
6. Measurement conversions (ASP)
This service will provide conversion of various measurements like distance, volume, and temperature
between English and Metric systems..
7. US White pages/Yellow Pages search (ASP)
This service will enable users to search for businesses by category, city/state or Company by Name ,
city/state.
This service uses the Yellow pages service given by Mapquest web site: http://www.mapquest.com/cgibin/database
8. Calendar (ASP)
This service enables the user to see a calendar on the graphic display of their phone.
9. Stock Ticker (ASP)
This service uses www.yahoo.com to display the current stock price of CSCO.
10. Stock Chart (ASP)
This service uses www.yahoo.com to display a graphic of the CSCO stock price over the past fiscal
year.
11. Push2Phone (ASP and JSP)
Push2Phone provides a form to enter a message to be sent to a group of
phones.
A text message is entered, a group of phones are selected from a list, and Send
send's the message. The list of phones is generated by querying the
CallManager database via the AVVID XML-Layer Database API (AXL).
file://C:\CiscoIPServices\Documentation\Cisco_IP_Phone_Services_SDK_Overview.htm
9/12/2005
Cisco IP Phone Services SDK Overview
Page 4 of 9
12. Click2Dial (ASP and JSP)
Click2Dial provides a web-based directory with Click-To-Dial capabilities.
Click2Dial accesses an LDAP directory and generates a table of users with their directory information.
The page returns the directory numbers as hyperlinks which allows you to click on a users phone
number and your phone automatically goes off-hook (speakerphone) and dials the number.
13. IdleURL (ASP)
As the name implies, IdleURL is intended to be called when the phone is idle.
IdleURL provides a dashboard display of important information. IdleURL
combines the extensions and speed dials on the phone along with a logo file
and some current stock quotes - this provides an Idle URL service which
combines text and graphics and does NOT obscure the extension and speed
dial labels.
14. MConference (JSP)
MConference is a sample application which allows users to create, join, and
control IP multicast conferences
from an XML phone service. It's a good example of the power of XML
services and IP multicast - providing a large-scale (thousands of participants),
arbitrated conference using a simple web application.
Conference arbitration can be enabled/disabled by the conference owner.
When arbitration is enabled participants must request permission which is then
granted by the conference owner. When conference arbitration is disabled,
participants can simply push-to-talk, similar to a hoot-and-holler network.
15. Hootie (ASP)
Hootie is a simple Hoot-and-Holler application utilizing the IP multicast streaming and mixing
capabilities of Cisco IP Phones.
16. InterCom (ASP)
Intercom allows a direct intercom feature between to IP phones. It is a simple example of how to use the
RTP streaming URIs to stream voice.
file://C:\CiscoIPServices\Documentation\Cisco_IP_Phone_Services_SDK_Overview.htm
9/12/2005
Cisco IP Phone Services SDK Overview
Page 5 of 9
17. JPEGViewer (ASP)
JPEGViewer is a slide-show application for IP Phones. It will look for all
JPEG files in a specified directory and automatically convert the JPEG images
to CIP format and return it to the phone for display.
18. Logo (ASP)
Logo provides a quick and easy method to get company logos or other graphics
to display on a Cisco IP Phone. It would typically be used as an Idle URL
service.
19. Clock (ASP)
Creates a large, 7-segment clock on the IP phone display - perfect for
conference rooms and shared areas where you always want a clock handy.
Typically used as an Idle URL Service.
20. Personal Service (ASP)
Personal Service is a Service which allows users to define there own custom service URL. This is
particularly useful for developers since they can point to their own Service or menu of Services without
needing CallManager admin access to define new IP Phone Services. Also useful for users who may
want to point to the Internet for their own personal XML services.
20. WaterMark (ASP)
Watermark is a simple service which overlays Text on top of an image for a
'watermarked' affect. Provides an example of how to use the SDK's
Javascript/ASP Library methods for combining graphics and text.
file://C:\CiscoIPServices\Documentation\Cisco_IP_Phone_Services_SDK_Overview.htm
9/12/2005
Cisco IP Phone Services SDK Overview
Page 6 of 9
21. Extension Mobility Controller (JSP)
This sample illustrates the basics of accessing the Extension Mobility API via the Java Library
EMProvider class.
Call this page from a standard web browser (not from an IP Phone) and you can query and control
Extension Mobility login status for users and phones.
22. Speed Dials (JSP)
SpeedDials allows users to configure their personal SpeedDials (not FastDials)
directly from their phone (via a phone service). Personal SpeedDials are
normally only accessible thru the CallManager user pages (from an HTML
browser).
23. Group MWI (JSP)
GroupMWI accepts a list of vmail extensions and their partition and returns a
list extensions/users who have voicemails waiting (MWI status is On).
GroupMWI works by querying the CallManager AXL interface using
SOAP/XML to retrieve the MWI status from the CallManager database. It
could be used for shared-area phones where roaming users (often away from
their desk) can quickly check to see if they have new voicemails - possibly
used as an Idle URL.
24. AutoDialer (JSP)
AutoDialer is a simple example of how a custom phone service can be used to dial numbers which
require pauses in the dialing sequence - account codes, long distance services, calling cards, voicemail
access, etc. When the user subscribes to the AutoDialer Phone Service, they will be required to enter a
dial string. When the user invokes the AutoDialer service from their phone, their specified dial string
will be dialed.
25. PhotoDirectory (JSP)
PhotoDirectory is an LDAP directory search service with advanced capabilities
beyond those of the standard, embedded directories on CallManager.
PhotoDirectory, as the name implies, retrieves a photo of the user (if available)
along with other more detailed LDAP information such as userID, department,
file://C:\CiscoIPServices\Documentation\Cisco_IP_Phone_Services_SDK_Overview.htm
9/12/2005
Cisco IP Phone Services SDK Overview
Page 7 of 9
and manager. It also provides a Manager softkey which allows you retrieve
directory info for a user's manager and "step up" thru the management chain.
26. CallerInfo (JSP)
CallerInfo is an example of an integrated CTI (JTAPI) and XML services
application. CallerInfo works with PhotoDirectory to provide call party
information for active calls on IP phones. CallerInfo works both in "pull" and
"push" mode. In "pull" mode, the user invokes the CallerInfo service from the
Services menu and CallerInfo redirects the request to PhotoDirectory and
supplies the identity of the user at the other end of the current active call.
In "push" mode, the CallerInfoServer application pushes the PhotoDirectory
URL to the phone as soon as an inbound call is answered by the user.
26. PushAuthenticate (ASP)
PushAuthenticate is NOT is an IP Phone Service. PushAuthenticate is a sample script which can be used
to offload authentication requests from the CallManager server. Many IP Phones Services (such as
Push2Phone in this SDK) take advantage of the IP phone's HTTP server to PUSH information and
commands. For large-scale applications, PUSHing to hundreds or thousands of devices, this can cause
performance problems with the authenticate.asp script running on CallManager. The problem arises
from the fact that all of these devices (phones) must be associated to a single userID/password (known
by the PUSH application) so that the application can PUSH to all phones - this causes considerable
overhead when processing the authenticate.asp script on CallManager.
A better approach is to change the Authentication URL in CallManager Admin to point to an external
authentication script, such as this one, which first checks for a specific userID/password (used by the
PUSH application) and returns AUTHORIZED if it matches. If the userID/password is not matched by
the PushAuthenticate script, it calls the authenticate.asp script on CallManager and "proxies" the
authentication request from the phone. This allows you to offload the PUSH authentication to an
external webserver while still using standard CallManager authentication for all other purposes.
27. ScreenShot (ASP)
Screenshot retrieves the current image from an IP Phone display, converts the XML to GIF format, and
returns it back to the requesting HTML browser for display.
Quick and easy way to capture a screenshot of what's happening on an IP Phone for troubleshooting or
documentation purposes.
file://C:\CiscoIPServices\Documentation\Cisco_IP_Phone_Services_SDK_Overview.htm
9/12/2005
Cisco IP Phone Services SDK Overview
Page 8 of 9
28. Integrating RS-232 devices with IP Telephony Applications (OtherApps)
Code and documentation is provided for using the Lantronix UDS100 device server to connect RS-232
devices to the network and integrate serial endpoints with IP Telephony applications. Example scenario
uses a Magtek mini card-swipe reader, but could be easily extended to any serial device - bar code
scanner, authentication devices (fingerprint, retinal scan), security sensors/systems, etc.
See the Lantronix Application Extension SDK for Cisco IP Phones for more details.
29. PNGViewer (ASP)
A slideshow viewer app based on the previous JPEGViewer sample
app. PNGViewer provides color PNG images to the new IP Phones
capable of displaying PNG images, like the 7970.
30. Keyboard (ASP)
Keyboard is a sample app which uses the new
CiscoIPPhoneGraphicFileMenu object to provide an on-screen
keyboard. This app will only run on the new touchscreen-enabled IP
phones, like the 7970.
31. MultiDirectory (ASP)
MultiDirectory uses the LDAPSearch COM server to query against multiple LDAP directories and
consolidate the response. The primary use of this app would be for LDAP searches across multiple
CallManager clusters or any installation where a single, consolidated LDAP directory does not exist.
32. Localized Directory (ASP)
LocalizedDirectory uses the LDAPSearch COM server to access a generic LDAP directory and takes
advantage of the new capabilities in LDAPSearch 2.0 to create localized, multi-lingual XML directory
objects.
33. Phone Push Step and Subsystem (IPCC Express / CRS)
The Phone Push Step and Subsystem can be added to an IPCC Express/CRS server to provide a
mechanism for pushing XML objects to an IP Phone from within a script. The Phone Push Step is
completely integrated with script editor and engine, so it provides the same drag-and-drop editing
file://C:\CiscoIPServices\Documentation\Cisco_IP_Phone_Services_SDK_Overview.htm
9/12/2005
Cisco IP Phone Services SDK Overview
Page 9 of 9
capability as the rest of the built-in Steps, as well as Subsystem control and debugging from the
standard server admin pages.
WARRANTY DISCLAIMER
THESE SAMPLE APPLICATIONS AND INFORMATION ARE PROVIDED "AS IS" WITHOUT
WARRANTY OF ANY KIND BY CISCO, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT
NOT LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY FITNESS FOR A
PARTICULAR PURPOSE, NONINFRINGEMENT, SATISFACTORY QUALITY OR ARISING
FROM A COURSE OF DEALING, LAW, USAGE, OR TRADE PRACTICE. CISCO TAKES NO
RESPONSIBILITY REGARDING ITS USAGE IN AN APPLICATION., THESE APPLICATIONS
ARE PROVIDED AS EXAMPLES ONLY, THEREFORE CISCO DOES NOT MAKE ANY
REPRESENTATIONS REGARDING THEIR RELIABILITY, SERVICEABILITY, OR FUNCTION.
IN NO EVENT DOES CISCO WARRANT THAT THE SOFTWARE IS ERROR FREE OR THAT
CUSTOMER WILL BE ABLE TO OPERATE THE SOFTWARE WITHOUT PROBLEMS OR
INTERRUPTIONS. NOR DOES CISCO WARRANT THAT THE SOFTWARE OR ANY
EQUIPMENT ON WHICH THE SOFTWARE IS USED WILL BE FREE OF VULNERABILITY TO
INTRUSION OR ATTACK. THESE SAMPLE APPLICATIONS ARE NOT SUPPORTED BY CISCO
IN ANY MANNER. CISCO DOES NOT ASSUME ANY LIABILITY ARISING FROM THE USE OF
THE APPLICATIONS. FURTHERMORE, IN NO EVENT SHALL CISCO OR ITS SUPPLIERS BE
LIABLE FOR ANY INCIDENTAL OR CONSEQUENTIAL DAMAGES, LOST PROFITS, OR LOST
DATA, OR ANY OTHER INDIRECT DAMAGES EVEN IF CISCO OR ITS SUPPLIERS HAVE
BEEN INFORMED OF THE POSSIBILITY THEREOF.
file://C:\CiscoIPServices\Documentation\Cisco_IP_Phone_Services_SDK_Overview.htm
9/12/2005
">