CGI Execute

The phone can be commanded to execute an internal URI handler or fetch an external URL by sending a POST request to the phone's web-server using the URL http://x.x.x.x/CGI/Execute with a parameter named XML.

If an <authenticationURL> has been defined, requests need to include a Authorization header encoded using the basic method. The username and password will be passed on to the authentication URL for checking. See Phone Services for more information.

See the open_in_browser Cisco Unified IP Phone Services Application Development Notes a list of URIs the each phone model supports.

CiscoIPPhoneExecute

Root element of an execute request, may contain up to 3 <ExecuteItem> elements.

<CiscoIPPhoneExecute>

ExecuteItem

Specifies a URL to fetch or a URI to execute.

URL URL to fetch or execute. Must be ether one of the internal URIs (Dial, Key, SoftKey, Init, Play etc.), an http:// URL or an https:// URL.

Priority Priority of the request (optional)

Execute immediately (default)

Execute when idle

Execute only if idle

  <ExecuteItem URL="URL" Priority="PRIORITY" />
</CiscoIPPhoneExecute>

An example command line script that sends up to three CGI execute requests to a phone is below.

#!/usr/bin/perl
#
# Copyright (c) 2015 Gareth Palmer <gareth.palmer3@gmail.com>
# This program is free software, distributed under the terms of
# the GNU General Public License Version 2.

use strict;
use POSIX qw/EXIT_FAILURE EXIT_SUCCESS/;
use English qw/-no_match_vars/;
use Getopt::Long qw//;
use LWP::UserAgent;
use HTML::Entities;
use XML::LibXML;

eval {
    my $getopt = Getopt::Long->new;

    $getopt->configure ('no_ignore_case');

    my ($ip_address, $username, $password, $show_help);

    unless ($getopt->getoptions ('i|ip-address=s' => \$ip_address,
                                 'u|username=s'   => \$username,
                                 'p|password=s'   => \$password,
                                 'h|help'         => \$show_help)) {
        die 'Error parsing options';
    }

    if ($show_help) {
        print 'cgi-execute [OPTIONS] <URL> [URL] [URL]', "\n",
              'Send a CGI execute request to a Cisco IP Phone', "\n",
          "\n",
              '  -i --ip-address <address>    IP address of the phone', "\n",
              '  -u --username <username>     Authorization username', "\n",
              '  -i --password <password>     Authorization password', "\n",
              "\n",
              'Valid URIs are Dial:, Key: SoftKey:, Init:, Play:, http: and https:', "\n",
              "\n";

        return;
    }

    my $urls = [];

    while (length (my $url = shift)) {
        die 'Invalid URL ' . $url unless ($url =~ m/^(Dial:\d+|Key:\w+|SoftKey:\w+|Init:\w+|Play:\w+|https?:\S+)$/);
        die 'Too many URLs specified' unless (scalar (@{$urls}) < 3);

        push (@{$urls}, $url);
    }

    die 'Invalid IP address: ' . $ip_address unless ($ip_address =~ m/^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$/);
    die 'No URLs specified' unless (scalar @{$urls});

    my $useragent = LWP::UserAgent->new;

    my $request = HTTP::Request->new (POST => 'http://' . $ip_address . '/CGI/Execute');

    $request->authorization_basic ($username, $password) if (length $username);

    $request->content_type ('application/x-www-form-urlencoded');
    $request->content ('XML=<CiscoIPPhoneExecute>');

    foreach my $url (@{$urls}) {
        $request->add_content ('<ExecuteItem URL="' . encode_entities ($url) . '" Priority="0" />');
    }

    $request->add_content ('</CiscoIPPhoneExecute>');

    my $response = $useragent->request ($request);

    die $response->content unless ($response->is_success);
    die 'Response was not XML' unless ($response->content_is_xml);

    my $document = XML::LibXML->load_xml (string => $response->content);

    if ((my $error, undef) = $document->findnodes ('/CiscoIPPhoneError')) {
        my $reasons = ['Error parsing CiscoIPPhoneExecute object',
                       'Error framing CiscoIPPhoneResponse object',
                       'Internal file error',
                       'Authentication error'];

        die ($reasons->[$error->getAttribute ('Number') - 1] || 'Error ' . $error->getAttribute ('Number'))
            . ': ' . decode_entities ($error->textContent);
    }
};

if (length $EVAL_ERROR) {
    warn $EVAL_ERROR;
    exit EXIT_FAILURE;
}

exit EXIT_SUCCESS;

setBackground

Sets the background on the phone, both URLs must be http://. Send to the phone using the same method as <CiscoIPPhoneExecute> with the XML parameter as follows. See Background Images for more information.

<setBackground>
  <background>
    <icon>ICON URL</icon>
    <image>IMAGE URL</image>
  </background>
</setBackground>

setRingTone

Sets the ring-tone on the phone, the URLs must be http://. Send to the phone using the same method as <CiscoIPPhoneExecute> with the XML parameter as follows. See Ring Tones for more information.

<setRingTone>
  <ringTone>RINGTONE URL</ringTone>
</setRingTone>

<proxy>

USECALLMANAGER.nz

</proxy>

CGI Execute

CiscoIPPhoneExecute

ExecuteItem

setBackground

setRingTone