Cisco::IPPhone - Package for creating Cisco IPPhone XML objects

NAME

Cisco::IPPhone - Package for creating Cisco IPPhone XML objects

SYNOPSIS

 use Cisco::IPPhone;

 $mytext = new Cisco::IPPhone;

 $mytext->Text({ Title => "My Title", Prompt => "My Prompt", 
                           Text => "My Text" });
 $mytext->AddSoftKeyItem( { Name => "Update", URL => "SoftKey:Update", 
                           Position => "1" });
 $mytext->AddSoftKeyItem( { Name => "Exit", URL => "SoftKey:Exit", 
                           Position => "2" });

 print $mytext->Content;

DESCRIPTION

Cisco::IPPhone - Package for creating Cisco IPPhone XML applications

This Cisco IPPhone module was created to provide a simple convenient method to display Cisco IP Phone objects and gather input from a Cisco 7940 or 7960 IP Phone. This module supports all known Cisco XML objects for 7940 and 7960 phones. Knowledge of Cisco XML syntax is not a requirement.

This Perl module gives the ability to use simple PERL objects to display XML on the IP Phone unlike to Cisco Software Development Kit (SDK) which uses Microsoft IIS Server, ASP's, JSP's, Javascript, COM Objects, and requires knowledge of XML syntax.

The following list gives typical services that might be supplied to a phone:

 - Weather
 - Stock information
 - Contact information
 - Company news
 - To-do lists
 - Real-time NFL scores
 - Daily schedule

Requirements

Developing Cisco IPPhone XML applications using the Cisco::IPPhone module requires the following: - Cisco CallManager Software or the CallManager Emulator Software - Any web server capable of running Perl CGI (Apache, etc) - A Cisco 7940 or 7960 IPPhone for testing the applications

Add services to Cisco CallManager:

 - Go to Feature -> Cisco IP Phone Services
 - Give the service a name and specify a URL such as:
       http://www.myorg.com/cgi-bin/menu.cgi
   Where menu.cgi is a Perl program that displays the menu
 - use the CCMUser URL to allow the user subscribe their phone to the service
   or have the Administrator assign the service to the phone using the 
   phone device configuration.

Methods

The following sections provide definitions and descriptions of each Cisco IP phone XML object: CiscoIPPhoneMenu, CiscoIPPhoneText, CiscoIPPhoneInput, CiscoIPPhoneDirectory, CiscoIPPhoneImage, CiscoIPPhoneGraphicMenu, CiscoIPPhoneIconMenu, CiscoIPPhoneExecute, CiscoIPPhoneError and CiscoIPPhoneResponse.

Examples

Example demonstrating Cisco IP Phone Text object

 #!/usr/bin/perl

 use IPPhone;
 $mytext = new IPPhone;

 $mytext->Text( { Title => "My Title", Prompt => "My Prompt",
                           Text => "My Text" });
 $mytext->AddSoftKeyItem( { Name => "Update", URL => "SoftKey:Update",
                           Position => "1" });
 $mytext->AddSoftKeyItem( { Name => "Exit", URL => "SoftKey:Exit",
                           Position => "2" });
 print $mytext->Content;
 __END__
 

 Generates the following:
 Content-Type: text/xml
 <CiscoIPPhoneText>
 <Title>My Title</Title>
 <Prompt>My Prompt</Prompt>
 <Text>My Text</Text>
 <SoftKeyItem>
   <Name>Update</Name>
   <URL>SoftKey:Update</URL>
   <Position>1</Position>
 </SoftKeyItem>
 <SoftKeyItem>
   <Name>Exit</Name>
   <URL>SoftKey:Exit</URL>
   <Position>2</Position>
 </SoftKeyItem>
 </CiscoIPPhoneText>

Example showing IP Phone Menu

 #!/usr/bin/perl
 use IPPhone;
 $mymenu = new IPPhone;
 $mymenuitem = new IPPhone;

 # Create Menu Object
 $mymenu->Menu( { Title => "My Title", 
                  Prompt => "My Prompt", 
                  Text => "My Text" });

 # Add Menu Items to Menu Object
 $mymenuitem->MenuItem( { Name => "Item1",  
                          URL => "http://www.mydomain.com" } );

 # Add Menu Item Object to the Menu
 $mymenu->AddMenuItemObject( { MenuItem => $mymenuitem });

 # Instead of creating a separate menu item object using MenuItem and
 # adding the object to the menu using AddMenuItemObject, 
 # you can simply use AddMenuItem to do it in one step

 $mymenu->AddMenuItem({ Name => "Item 2", 
                        URL => "http://www.mydomain.com" });
 
 $mymenu->AddSoftKeyItem({ Name => "Select", URL => "SoftKey:Select", 
                           Position => "1" });
 $mymenu->AddSoftKeyItem({ Name => "Exit", URL => "SoftKey:Exit", 
                           Position => "2" });
 
 # Print the Menu Object to the Phone
 print $mymenu->Content;

 
 Content-Type: text/xml
 <CiscoIPPhoneMenu>
 <Title>My Title</Title>
 <Prompt>My Prompt</Prompt>
 <MenuItem>
   <Name>Item1</Name>
   <URL>http://www.mydomain.com</URL>;
 </MenuItem>
 <MenuItem>
   <Name>Item 2</Name>
   <URL>http://www.mydomain.com</URL>;
 </MenuItem>
 <SoftKeyItem>
   <Name>Select</Name>
   <URL>SoftKey:Select</URL>
   <Position>1</Position>
 </SoftKeyItem>
 <SoftKeyItem>
   <Name>Exit</Name>
   <URL>SoftKey:Exit</URL>
   <Position>2</Position>
 </SoftKeyItem>
 </CiscoIPPhoneMenu>

Example using Execute object to push messages to the phone

 #!/usr/bin/perl
 # Mark Palmer - markpalmer@us.ibm.com
 # Must use authentication when POSTING an object to a Cisco IPPhone.
 # User should be a user in the global directory associated with the phone
 # Can use this script to send messages to IPPhones
 
 use Cisco::IPPhone;
 use LWP::UserAgent;
 use URI;
 $ua = LWP::UserAgent->new;
 $myexecute = new Cisco::IPPhone;
 
 $SERVER = "192.168.250.17";
 $IPPHONE = "192.168.250.7";
 $USER = 'myname';
 $PASSWORD = 'mypassword';
 $POSTURL = "http://${IPPHONE}/CGI/Execute";
 
 # URL that phone will fetch
 $URL1 = "http://$SERVER/cgi-bin/nfl.cgi";
 
 # Build Execute Object with up to 3 Execute Items
 $myexecute->Execute;
 $myexecute->AddExecuteItem( { ExecuteItem => "$URL1" });
 my $xml = $myexecute->Content_Noheader;
 
 # Translate non-alpha chars into hex
 $xml = URI::Escape::uri_escape("$xml"); 
 
 my $request = new HTTP::Request POST => "$POSTURL";
 $request->authorization_basic($USER, $PASSWORD);
 $request->content("XML=$xml"); # Phone requires parameter named XML
 my $response = $ua->request($request); # Send the POST
 
 if ($response->is_success) {
   $result = $response->content;
   if ($result =~ /CiscoIPPhoneError Number="(\d+)"/) {
      $errno = $1;
      if ($errno == 4) {
          print "Authentication error\n";
      } elsif ($errno == 3) {
          print "Internal file error\n"; 
      } elsif ($errno == 2) {
          print "Error framing CiscoIPPhoneResponse object\n"; 
      } elsif ($errno == 1) {
          print "Error parsing CiscoIPPhoneExecute object\n"; 
      } else {
          print "Unknown Error\n";
          print $result;
      }
   }
 } else {
   print "Failure: Unable to POST XML object to phone $IPPHONE\n";
   print $response->status_line;
 }

EXPORT

None by default.

AUTHOR

Mark Palmer, markpalmer@us.ibm.com, 7/13/2002

SEE ALSO

perl(1).