NAME

Polycom::Contact::Directory - Parser for Polycom VoIP phone local contact directory files.

SYNOPSIS

  use Polycom::Contact::Directory;

  # Load an existing contact directory file
  my $dir = Polycom::Contact::Directory->new('0004f21ac123-directory.xml');  

  # Add a contact
  $dir->insert(
    {   first_name => 'Jenny',
        last_name  => 'Xu',
        contact    => '2',
    },
  );
  
  # Find some contacts
  my @all    = $dir->all;
  my @smiths = $dir->search({ last_name => 'Smith' });
  
  # Modify a contact in the directory
  $smiths[0]->last_name('Johnson');
  
  # Remove a contact
  $smiths[1]->delete;

  # Save the directory to an XML file suitable for being read by the phone
  $dir->save('0004f21ac123-directory.xml');

DESCRIPTION

Polycom SoundPoint IP, SoundStation IP, and VVX VoIP phones maintain a local contact directory that is stored on their configured boot server. Upon boot-up, each phone looks for a file named <Ethernet address>-directory.xml on their boot server, and if found, downloads and parses the file to build up its local contact directory. In addition to basic contact information such first/last name and phone number, each contact in the local contact directory can also include information about speed-dialing, distinctive ring tones, presence, and instant messaging.

Each <Ethernet address>-directory.xml contains fairly straightforward XML:

  <?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
  <directory>
   <item_list>
    <item>
     <ln>Doe</ln>
     <fn>John</fn>
     <ct>1001</ct>
     <sd>1</sd>
     <rt>1</rt>
     <dc/>
     <ad>0</ad>
     <ar>0</ar>
     <bw>0</bw>
     <bb>0</bb>
    </item>
      ...
   </item_list>
  </directory>

This module parses Polycom VoIP phone local contact directory files, and can be used to read, modify, or create local contact directory files. It also provides a is_valid method that can be used to perform some basic integrity checks on contact directory files.

For more information about administering the Local Contact Directory on Polycom SoundPoint IP phones, see the "SoundPoint IP, SoundStation IP and Polycom VVX Administrator's Guide" at http://www.polycom.com/support/voice/soundpoint_ip/soundpoint_ip670.html.

CONSTRUCTOR

new ( $filename | $file_handle | $xml_contents )

  # Create a new empty directory
  my $dir = Polycom::Contact::Directory->new();

  # Load a directory from a filename or file handle
  my $dir2 = Polycom::Contact::Directory->new('directory.xml');
  my $dir3 = Polycom::Contact::Directory->new($fh);

If you have already slurped the contents of a contact directory file into a scalar, you can also pass that scalar to new to parse those XML contents.

METHODS

insert ( @contacts )

  $dir->insert(
    {   first_name => 'Jenny',
        last_name  => 'Xu',
        contact    => '2',
        speed_index => 1,
        ring_type   => 5,
    },
    {   first_name => 'Jacky',
        last_name  => 'Cheng',
        contact    => '3',
        speed_index => 2,
        ring_type   => 10,
    },
  );

Adds the specified @contacts contacts, if any, to the directory. @contacts may be an array of hash references containing keys like "first_name", "last_name", and "contact", or it can be an array of Polycom::Contact objects.

all

  my @contacts = $dir->all;
  foreach my $contact (@contacts)
  {
    # ...
  }

Returns an array of all of the Polycom::Contact objects in the contact directory.

count

  my $num_contacts = $dir->count;

Returns the number of contacts in the directory.

equals ( $directory2 )

  if ($dir1->equals($dir2))
  {
    print "The contact directories are equal\n";
  }

Returns true if both contact directories are equal (i.e. they contain the same contacts).

Because the == and != operators have also been overloaded for both Polycom::Contact and Polycom::Contact::Directory objects, it is equivalent to compare two contact directories using:

  if ($dir1 == $dir2)
  {
    print "The contact directories are equal\n";
  }

is_valid

  if (!$dir->is_valid)
  {
    print "$dir is invalid.\n";
  }

Returns true if each contact is valid (e.g. has a contact number, name is < 40 bytes long, etc), there are no duplicate contact numbers, and there are no duplicate speed index numbers. Otherwise, it returns false.

save ( $filename )

  $dir->save('0004f21acabf-directory.xml');
  # or
  $dir->save()

Writes the contents of the contact directory object to the specified file such that a phone should be able to read those contacts from the file if the file is placed on the phone's boot server.

If $filename is not specified, the default filename used is "000000000000-directory.xml", which is the filename the phones look for if a directory file whose name contains their MAC address is not found.

search ( $condition )

  my @smiths = $dir->search({ last_name => 'Smith' });

Returns an array of the contacts that match the specified condition. $condition must be a hash reference whose keys are field names of Polycom::Contact fields (e.g. first_name, last_name, contact, ring_type, etc). All of the specified conditions must hold in order for a contact to be present in the array returned.

to_xml

  my $xml = $directory->to_xml;

Returns the XML representation of the contact directory. It is exactly this XML representation that the save method writes to the local contact directory file.

SEE ALSO

Polycom::Contact - A contact in the local contact directory. Each Polycom::Contact::Directory object contains zero or more Polycom::Contact objects.

SoundPoint IP Admin Guide - http://www.polycom.com/global/documents/support/setup_maintenance/products/voice/spip_ssip_vvx_Admin_Guide_SIP_3_2_2_eng.pdf

AUTHOR

Zachary Blair, <zblair@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2010 by Polycom Canada

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.

cpanm Polycom::Contact::Directory

perl -MCPAN -e shell
install Polycom::Contact::Directory