File Coverage

blib/lib/EWS/Client/Contacts.pm
Criterion Covered Total %
statement 7 7 100.0
branch n/a
condition n/a
subroutine 3 3 100.0
pod n/a
total 10 10 100.0


line stmt bran cond sub pod time code
1             package EWS::Client::Contacts;
2             BEGIN {
3 1     1   22 $EWS::Client::Contacts::VERSION = '1.143070';
4             }
5 1     1   5 use Moose;
  1         7  
  1         7  
6              
7             with 'EWS::Contacts::Role::Reader';
8             # could add future roles for updates, here
9              
10             has client => (
11             is => 'ro',
12             isa => 'EWS::Client',
13             required => 1,
14             weak_ref => 1,
15             );
16              
17             __PACKAGE__->meta->make_immutable;
18 1     1   6184 no Moose;
  1         2  
  1         4  
19             1;
20              
21             # ABSTRACT: Contact Entries from Microsoft Exchange Server
22              
23              
24             __END__
25             =pod
26              
27             =head1 NAME
28              
29             EWS::Client::Contacts - Contact Entries from Microsoft Exchange Server
30              
31             =head1 VERSION
32              
33             version 1.143070
34              
35             =head1 SYNOPSIS
36              
37             First set up your Exchange Web Services client as per L<EWS::Client>:
38              
39             use EWS::Client;
40            
41             my $ews = EWS::Client->new({
42             server => 'exchangeserver.example.com',
43             username => 'oliver',
44             password => 's3krit', # or set in $ENV{EWS_PASS}
45             });
46              
47             Then retrieve the contact entries:
48              
49             my $entries = $ews->contacts->retrieve;
50             print "I retrieved ". $entries->count ." items\n";
51            
52             while ($entries->has_next) {
53             print $entries->next->DisplayName, "\n";
54             }
55              
56             =head1 DESCRIPTION
57              
58             This module allows you to retrieve the set of contact entries for a user
59             on a Microsoft Exchange server. At present only read operations are supported.
60             The results are available in an iterator and convenience methods exist to
61             access the properties of each entry.
62              
63             =head1 METHODS
64              
65             =head2 CONSTRUCTOR
66              
67             =head2 EWS::Client::Contacts->new( \%arguments )
68              
69             You would not normally call this constructor. Use the L<EWS::Client>
70             constructor instead.
71              
72             Instantiates a new contacts reader. Note that the action of performing a query
73             for a set of results is separated from this step, so you can perform multiple
74             queries using this same object. Pass the following arguments in a hash ref:
75              
76             =over 4
77              
78             =item C<client> => C<EWS::Client> object (required)
79              
80             An instance of C<EWS::Client> which has been configured with your server
81             location, user credentials and SOAP APIs. This will be stored as a weak
82             reference.
83              
84             =back
85              
86             =head2 QUERY AND RESULT SET
87              
88             =head2 $contacts->retrieve( \%arguments )
89              
90             Query the Exchange server and retrieve contact entries. By default the
91             C<retrieve()> method will return contacts for the account under which you
92             authenticated to the Exchange server (that is, the credentials passed to the
93             L<EWS::Client> constructor). The following arguments will change this
94             behaviour:
95              
96             =over 4
97              
98             =item C<email> => String (optional)
99              
100             Passing the primary SMTP address of another account will retrieve the contacts
101             for that Exchange user instead using the I<Delegation> feature, assuming you
102             have rights to see their contacts (i.e. the user has shared their contacts).
103             If you do not have rights, an error will be thrown.
104              
105             If you pass one of the account's secondary SMTP addresses this module
106             I<should> be able to divine the primary SMTP address required.
107              
108             =item C<impersonate> => String (optional)
109              
110             Passing the primary SMTP address of another account will retrieve the contacts
111             for that Exchange user instead, assuming you have sufficient rights to
112             I<Impersonate> that account. If you do not have rights, an error will be
113             thrown.
114              
115             =back
116              
117             The returned object contains the collection of contact entries and is of type
118             C<EWS::Contacts::ResultSet>. It's an iterator, so you can walk through the
119             list of entries (see the synposis, above). For example:
120              
121             my $entries = $contacts->retrieve({email => 'nobody@example.com'});
122              
123             =head2 $entries->next
124              
125             Provides the next item in the collection of contact entries, or C<undef> if
126             there are no more items to return. Usually used in a loop along with
127             C<has_next> like so:
128              
129             while ($entries->has_next) {
130             print $entries->next->DisplayName, "\n";
131             }
132              
133             =head2 $entries->peek
134              
135             Returns the next item without moving the state of the iterator forward. It
136             returns C<undef> if it is at the end of the collection and there are no more
137             items to return.
138              
139             =head2 $entries->has_next
140              
141             Returns a true value if there is another entry in the collection after the
142             current item, otherwise returns a false value.
143              
144             =head2 $entries->reset
145              
146             Resets the iterator's cursor, so you can walk through the entries again from
147             the start.
148              
149             =head2 $entries->count
150              
151             Returns the number of entries returned by the C<retrieve> server query.
152              
153             =head2 $entries->items
154              
155             Returns an array ref containing all the entries returned by the C<retrieve>
156             server query. They are each objects of type C<EWS::Contacts::Item>.
157              
158             =head2 ITEM PROPERTIES
159              
160             =head2 $item->DisplayName
161              
162             The field you should use to describe this entry, being probably the person or
163             business's name.
164              
165             =head2 $item->JobTitle
166              
167             The Job Title field of the contact.
168              
169             =head2 $item->CompanyName
170              
171             The Comany Name field of the contact.
172              
173             =head2 $item->BusinessHomePage
174              
175             The Business Home Page field within the contact.
176              
177             =head2 $item->PhoneNumbers
178              
179             This property comprises all the phone numbers associated with the contact.
180              
181             An Exchange contact has a number of fields for storing numbers of different
182             types, such as Mobile Phone, Business Line, and so on. Each of these may in
183             turn store a free text field so people often put multiple numbers in,
184             separated by a delimiter.
185              
186             As a result of this freedom, this module makes no effort to interpret the
187             content of the number fields, only to retrieve them. It's assumed you are
188             familiar with your own number storage conventions, or can use a module such
189             as L<Number::Phone::Normalize> to parse the result.
190              
191             In this property you'll find a hash ref of all this data, with keys being the
192             number types (Mobile Phone, etc), and values being array refs of I<data>. As
193             explained above, the data might be single numbers or free text with several
194             telephone numbers that you will need to parse yourself. For example:
195              
196             my $numbers = $entry->PhoneNumbers;
197            
198             foreach my $type (keys %{ $numbers }) {
199            
200             foreach my $extn (@{ $numbers->{$type} }) {
201            
202             print "$type : $extn \n";
203             }
204             }
205            
206             # might print something like:
207            
208             Mobile Phone : 73244
209             Business Line : 88888
210              
211             =head2 $item->EmailAddresses
212              
213             This property comprises all the email addresses associated with the contact.
214              
215             Similar to the C<PhoneNumbers> property, this is a hash ref of all data, with
216             keys being the email address type and values being array refs of I<data>.
217              
218             See C<PhoneNumbers>, above for an example of how to process this property.
219              
220             =head2 $item->PhysicalAddresses
221              
222             This property comprises all the physical addresses associated with the
223             contact.
224              
225             Again, like the C<PhoneNumbers> and C<EmailAddresses> properties, this is a
226             hash ref of array refs, where the hash keys are address identifiers, and the
227             values are lists of addresses.
228              
229             =head1 SEE ALSO
230              
231             =over 4
232              
233             =item * L<http://msdn.microsoft.com/en-us/library/aa580675.aspx>
234              
235             =back
236              
237             =head1 AUTHOR
238              
239             Oliver Gorwits <oliver@cpan.org>
240              
241             =head1 COPYRIGHT AND LICENSE
242              
243             This software is copyright (c) 2014 by University of Oxford.
244              
245             This is free software; you can redistribute it and/or modify it under
246             the same terms as the Perl 5 programming language system itself.
247              
248             =cut
249