/ 
AXL-Client-Simple-0.02
River stage zero No dependents
/ AXL::Client::Simple::Phone

NAME

AXL::Client::Simple::Phone - Properties and Lines on a CUCM Handset

VERSION

This document refers to version 0.01 of AXL::Client::Simple::Phone

SYNOPSIS

First set up your CUCM AXL client as per AXL::Client::Simple:

use AXL::Client::Simple;

my $cucm = AXL::Client::Simple->new({
    server      => 'call-manager-server.example.com',
    username    => 'oliver',
    password    => 's3krit', # or set in $ENV{AXL_PASS}
});

Then perform simple queries on the Unified Communications server:

my $device = $cucm->get_phone('SEP001122334455');

my $lines = $device->lines;
printf "this device has %s lines.\n", $lines->count;

while ($lines->has_next) {
    my $l = $lines->next;
    print $l->alertingName, "\n";
    print $l->extn, "\n";
}

if ($device->has_active_em) {
    # extension mobility is active, so the lines are different

    my $profile = $device->currentProfile;

    my $profile_lines = $profile->lines;
    printf "this profile has %s lines.\n", $profile_lines->count;

    while ($profile_lines->has_next) {
        my $l = $profile_lines->next;
        print $l->alertingName, "\n";
        print $l->extn, "\n";
    }
}

DESCRIPTION

This module allows you to retrieve some properties of a device registered with a Cisco Unified Communications server, including its line numbers and extension mobility profile lines.

METHODS

CONSTRUCTOR

AXL::Client::Simple::Phone->new( \%arguments )

You would not normally call this constructor. Use the AXL::Client::Simple constructor instead.

client => AXL::Client::Simple object (required)

An instance of AXL::Client::Simple which has been configured with your server location, user credentials and SOAP APIs. This will be stored as a weak reference.

stash => Hash Ref (required)

This hash reference contains the raw data returned from the Unified Communications server when asked for properties of this device. From this stash are retrieved data to construct each property as listed below.

LINES QUERY AND RESULT SET

$device->lines

Query the Unified Communications server and retrieve phone line details for this device.

The returned object contains the ordered collection of phone lines and is of type AXL::Client::Simple::LineResultSet. It's an iterator, so you can walk through the list of lines (see the synposis, above). For example:

my $lines = $device->lines;

$lines->next

Provides the next item in the collection of lines, or undef if there are no more items to return. Usually used in a loop along with has_next like so:

while ($lines->has_next) {
    print $lines->next->alertingName, "\n";  # the alerting name field from CUCM
    print $lines->next->extn, "\n";          # the phone line extension number
}

$lines->peek

Returns the next item without moving the state of the iterator forward. It returns undef if it is at the end of the collection and there are no more items to return.

$lines->has_next

Returns a true value if there is another entry in the collection after the current item, otherwise returns a false value.

$lines->reset

Resets the iterator's cursor, so you can walk through the entries again from the start.

$lines->count

Returns the number of entries returned by the lines server query.

$lines->items

Returns an array ref containing all the entries returned by the lines server query. They are each objects of type AXL::Client::Simple::Line.

PHONE PROPERTIES

$device->currentProfileName

If the device has Extension Mobility enabled and an extension mobility profile is active, then its name will be returned by this accessor.

$device->loginUserId

When Extension Mobility is active, you can find out the username of the logged in user by querying this property.

$device->has_active_em

To easily find out whether Extension Mobility is active on a live handset, use this property which will return a true value if that is the case. Otherwise, it returns a false value.

$device->currentProfile

Assuming the device does have Extension Mobility active, then you can grab the extension mobility profile details from this property. In fact, what is returned is another instance of AXL::Client::Simple::Phone (this module) which in turn allows you to access the profile's line numers via lines as above.

SEE ALSO

AUTHOR

Oliver Gorwits <oliver.gorwits@oucs.ox.ac.uk>

COPYRIGHT & LICENSE

Copyright (c) University of Oxford 2010.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.