view release on metacpan or  search on metacpan

lib/EWS/Client/Calendar.pm  view on Meta::CPAN

=head1 NAME

EWS::Client::Calendar - Calendar Entries from Microsoft Exchange Server

=head1 VERSION

version 1.143070

=head1 SYNOPSIS

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

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

Then perform operations on the calendar entries:

 my $entries = $ews->calendar->retrieve({
     start => DateTime->now(),
     end   => DateTime->now->add( months => 1 ),
 });
 
 print "I retrieved ". $entries->count ." items\n";
 
 while ($entries->has_next) {
     print $entries->next->Subject, "\n";
 }

=head1 DESCRIPTION

This module allows you to perform operations on the calendar entries in a
Microsoft Exchange server. At present only read operations are supported,
allowing you to retrieve calendar entries within a given time window. The
results are available in an iterator and convenience methods exist to access
the properties of each entry.

=head1 METHODS

=head2 CONSTRUCTOR

=head2 EWS::Client::Calendar->new( \%arguments )

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

Instantiates a new calendar 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:

=over 4

=item C<client> => C<EWS::Client> object (required)

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

=back

=head2 QUERY AND RESULT SET

=head2 $cal->retrieve( \%arguments )

Query the Exchange server and retrieve calendar entries between the given
timestamps. Pass the following arguments in a hash ref:

=over 4

=item C<start> => DateTime object (required)

Entries with an end date on or after this timestamp will be included in the
returned results.

=item C<end> => DateTime object (required)

Entries with a start date before this timestamp will be included in the
results.

=item C<email> => String (optional)

Passing the primary SMTP address of another account will retrieve the contacts
for that Exchange user instead using the I<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
I<should> be able to divine the primary SMTP address required.

=item C<impersonate> => String (optional)

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

=back

The returned object contains the collection of calendar entries which matched
the start and end criteria, and is of type C<EWS::Calendar::ResultSet>. It's
an iterator, so you can walk through the list of entries (see the synposis,
above). For example:

 my $entries = $cal->retrieve({start => '', end => ''});

=head2 $entries->next

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

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

=head2 $entries->peek