Section 13.9. Project 13.2. Build an Interactive Directory on a SIP Display Phone

13.9. Project 13.2. Build an Interactive Directory on a SIP Display Phone

13.9.1.1 What you need for this project:

• A Cisco SIP display phone (7940, 7960, etc.)

• Asterisk

• An HTTP server like Apache

Cisco's 7900-series SIP phones can access a web service to drive interactive menus and application frontends right on the phone. These applications use the phone's display and soft buttons and are often tied, via a web server, to a backend database or PBX system like Asterisk. In this project, we'll build a simple, static user directory that you can browse with a 7900-series SIP phone.

Ever wonder what the difference between a 7960 and a 7960G is? The G stands for global . G phones have icons instead of words printed on their buttons: a mail envelope instead of the word messages and so on.

Cisco's IP phones use XML markup to describe the user-interface elements the phone is capable of constructingsimple UI elements like images, button labels, and lists. The 7970G phone is even capable of displaying color graphics. (A fully functional web browser is a standard feature of the SCCP version of the 7970G.) The XML files are downloaded by the phone from a web server, so they can be static text files or CGI- or servlet-generated output.

On the 7960 phone, there is a Directories key that is used to trigger an XML application on the phone's display. Despite its label, this key can be programmed to do anything, because you control the XML file that it loads. The URL used to find the directories file is found in the directory_url setting of the phone's SIP configuration file, which is loaded by TFTP when the phone starts up.

TFTP and Cisco SIP Phones

All Cisco IP phones support the use of TFTP to load configuration files, and most Cisco IP phones also support configuration using the phone's built-in display and buttons. If your Ethernet segment has a DHCP server that can be used to get the phones on the IP network, then TFTP is the key to doing mass configurations at once. Your DHCP server can tell the SIP phones what your TFTP server's address is.

To mass-configure 7900-series phones, start with Cisco's default configuration file (there's an example at http://www.cisco.com/cgi-bin/tablebuild.pl/sip-ip-phone7960) and customize it as needed. Once you've got it set up the way you want, copy it to your TFTP server's root directory and rename it according to the convention:

 SIP  <mac address of the SIP phone>  .cnf 

Everything in the filename, including the MAC address of the SIP phone, should be uppercase, except for the extension .cnf . Make one copy for each of the phones you need to configure, until you've got a file for every SIP phone. At this point, when the phones boot up, they'll get their configuration from the TFTP server.

Once the config file is loaded by TFTP, the directory_url defines where the XML will be loaded from. The next step is to put that XML file at the path of the URL. Here's a sample of what a simple directory file might look like:

 <CiscoIPPhoneDirectory>      <Title>Phone Directory</Title>      <Prompt>Asterisk Extensions</Prompt>      <DirectoryEntry>      <Name>Wallingford, Ted</Name>      <Telephone>105</Telephone>      </DirectoryEntry>      <DirectoryEntry>      <Name>Wojtowicz, Susie</Name>      <Telephone>106</Telephone>      </DirectoryEntry>      <DirectoryEntry>      <Name>Gray, Sue</Name>      <Telephone>107</Telephone>      </DirectoryEntry>      <DirectoryEntry>      <Name>Wallingford, Jayne</Name>      <Telephone>108</Telephone>      </DirectoryEntry>      </CiscoIPPhoneDirectory> 

So, your directory URL could point to a static XML file, or it could point to a dynamic Perl, PHP, or VB script. In any event, make sure that the proper headers are sent to the SIP phone, or you won't have good results. Here are the headers the 7900-series phones need:

 Content-type: text/xml     Connection: close     Expires: -1 

If you're using PHP for your dynamic directory app, you should make a script with a name like 79xx-lib.php that lets you output these headers (and other 79xx-specific stuff) easily. A PHP header script for Cisco SIP phones would contain this:

 $header79xx="Content-type: text/xml\nConnection: close\nExpires: -1\n\n"; 

Now, the $header79xx PHP variable contains the headers, and you can place it at the start of your PHP directory script. The following script grabs a list of usernames and extensions from a fictitious MySQL database and outputs them as a 7900-series phone directory that can be accessed by pressing the Directories button.

 <?     include "79xx-lib.php";     print $header79xx;      $mysql_conn = mysql_connect("localhost","asterisk","");      mysql_select_db("directory",$mysql_conn);      $rowset = mysql_query("SELECT username,extension FROM extensions", $mysql_conn);      print("<CiscoIPPhoneDirectory>\n");      print("\t<Title>Giant Motor Corporation</Title>\n");      print("\t<Prompt>Office Phone Directory</Prompt>\n");      while($row = mysql_fetch_row($rowset))      {         print("\t<DirectoryEntry>\n");         print("\t\t<Name>");         print($row[0]);         print("</Name>\n");         print("\t\t<Telephone>");         print($row[1]);         print("</Telephone>\n");         print("\t</DirectoryEntry>\n");      }      print("</CiscoIPPhoneDirectory>\n");     ?> 

In the preceding PHP example, when the user presses the Directories button on the Cisco phone, the HTTP client downloads the output of the directory_url setting (which is driven by the PHP script), interpret it, and display the directory on the phone's LCD. The user can then place a call directly to any of the users in the directory.

Cisco IP Phone Hacks

Cisco's IP phones, through their XML Services firmware, allow you to use highly sophisticated web-based apps to enhance your telephony offerings. They are accessed via the Services button and from the URL stored in the services_url setting.

These apps can access a wider spectrum of functionality than those accessed as directories. You could have your OpenOffice or iCal calendar show up on your phone's display, or you could turn the phone into a data-collection device, a time clock, a stock ticker, or an instant messaging tool.

A host of commercial third-party applications have been created to take advantage of this functionality, too. Cisco publishes a developer's guide for IP phone XML Services. Once you've gotten your feet wet with XML Services, check out http://asterisk.edihost.co.uk/am-web, a site that offers an XML application that gives you administrative control over an Asterisk PBX from a Cisco 7960.