NAME

EWS::Client::Contacts - Contact Entries from Microsoft Exchange Server

VERSION

version 1.143070

SYNOPSIS

First set up your Exchange Web Services client as per EWS::Client:

 use EWS::Client;
 
 my $ews = EWS::Client->new({
     server      => 'exchangeserver.example.com',
     username    => 'oliver',
     password    => 's3krit', # or set in $ENV{EWS_PASS}
 });

Then retrieve the contact entries:

 my $entries = $ews->contacts->retrieve;
 print "I retrieved ". $entries->count ." items\n";
 
 while ($entries->has_next) {
     print $entries->next->DisplayName, "\n";
 }

DESCRIPTION

This module allows you to retrieve the set of contact entries for a user on a Microsoft Exchange server. At present only read operations are supported. The results are available in an iterator and convenience methods exist to access the properties of each entry.

METHODS

CONSTRUCTOR

EWS::Client::Contacts->new( \%arguments )

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

Instantiates a new contacts reader. Note that the action of performing a query for a set of results is separated from this step, so you can perform multiple queries using this same object. Pass the following arguments in a hash ref:

client => EWS::Client object (required)

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

QUERY AND RESULT SET

$contacts->retrieve( \%arguments )

Query the Exchange server and retrieve contact entries. By default the retrieve() method will return contacts for the account under which you authenticated to the Exchange server (that is, the credentials passed to the EWS::Client constructor). The following arguments will change this behaviour:

email => String (optional)

Passing the primary SMTP address of another account will retrieve the contacts for that Exchange user instead using the Delegation feature, assuming you have rights to see their contacts (i.e. the user has shared their contacts). If you do not have rights, an error will be thrown.

If you pass one of the account's secondary SMTP addresses this module should be able to divine the primary SMTP address required.

impersonate => String (optional)

Passing the primary SMTP address of another account will retrieve the contacts for that Exchange user instead, assuming you have sufficient rights to Impersonate that account. If you do not have rights, an error will be thrown.

The returned object contains the collection of contact entries and is of type EWS::Contacts::ResultSet. It's an iterator, so you can walk through the list of entries (see the synposis, above). For example:

 my $entries = $contacts->retrieve({email => 'nobody@example.com'});

$entries->next

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

 while ($entries->has_next) {
     print $entries->next->DisplayName, "\n";
 }

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

$entries->has_next

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

$entries->reset

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

$entries->count

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

$entries->items

Returns an array ref containing all the entries returned by the retrieve server query. They are each objects of type EWS::Contacts::Item.

ITEM PROPERTIES

$item->DisplayName

The field you should use to describe this entry, being probably the person or business's name.

$item->JobTitle

The Job Title field of the contact.

$item->CompanyName

The Comany Name field of the contact.

$item->BusinessHomePage

The Business Home Page field within the contact.

$item->PhoneNumbers

This property comprises all the phone numbers associated with the contact.

An Exchange contact has a number of fields for storing numbers of different types, such as Mobile Phone, Business Line, and so on. Each of these may in turn store a free text field so people often put multiple numbers in, separated by a delimiter.

As a result of this freedom, this module makes no effort to interpret the content of the number fields, only to retrieve them. It's assumed you are familiar with your own number storage conventions, or can use a module such as Number::Phone::Normalize to parse the result.

In this property you'll find a hash ref of all this data, with keys being the number types (Mobile Phone, etc), and values being array refs of data. As explained above, the data might be single numbers or free text with several telephone numbers that you will need to parse yourself. For example:

 my $numbers = $entry->PhoneNumbers;
 
 foreach my $type (keys %{ $numbers }) {
 
     foreach my $extn (@{ $numbers->{$type} }) {
 
         print "$type : $extn \n";
     }
 }
 
 # might print something like:
 
 Mobile Phone : 73244
 Business Line : 88888

$item->EmailAddresses

This property comprises all the email addresses associated with the contact.

Similar to the PhoneNumbers property, this is a hash ref of all data, with keys being the email address type and values being array refs of data.

See PhoneNumbers, above for an example of how to process this property.

$item->PhysicalAddresses

This property comprises all the physical addresses associated with the contact.

Again, like the PhoneNumbers and EmailAddresses properties, this is a hash ref of array refs, where the hash keys are address identifiers, and the values are lists of addresses.

SEE ALSO

• http://msdn.microsoft.com/en-us/library/aa580675.aspx

AUTHOR

Oliver Gorwits <oliver@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2014 by University of Oxford.

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

cpanm EWS::Client

perl -MCPAN -e shell
install EWS::Client