NAME

Polycom::Contact::Directory - Module for parsing, modifying, and creating 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 some contacts
$dir->add(
  {   first_name => 'Jenny',
      last_name  => 'Xu',
      contact    => '2',
  },
  {   first_name => 'Jacky',
      last_name  => 'Cheng',
      contact    => '3',
  },
);

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

# Iterate through all of the contacts 
foreach my $contact ($dir->all)
{
  # ...
}

# Find only those contacts whose last name is "Smith"
my @smiths = $dir->search({ last_name => 'Smith' });

DESCRIPTION

This module parses Polycom VoIP phone local contact directory files, and can be used to read, modify, or create local contact directory files.

Polycom::Contact::Directory->new()

# 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(\*FILEHANDLE);

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:

my $xml = <<"END_XML";
  <directory>
   <item_list>
    <item>
     <fn>Bob</fn>
     <ct>1234</ct>
    </item>
   </item_list>
  </directory>
END_XML

my $dir = Polycom::Contact::Directory->new($xml);

$dir->add(@contacts)

$dir->add(
  {   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.

$directory->all

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

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

$directory->count

my $num_contacts = $dir->count;

Returns the number of contacts in the directory.

$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";
}

$directory->is_valid

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

Returns true if each contact has a contact number, there are no duplicate contact numbers, and there are no duplicate speed index numbers. Otherwise, it returns false.

$directory->save($filename_or_file_handle)

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

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.

$directory->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.

$directory->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 - Represents a contact in the local contact directory. Each Polycom::Contact::Directory contains zero or more Polycom::Contact objects.

AUTHOR

Zachary Blair, <zachary.blair@polycom.com>

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.