EWS::Client::Calendar - Calendar Entries from Microsoft Exchange Server
version 1.143070
First set up your Exchange Web Services client as per 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"; }
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.
You would not normally call this constructor. Use the 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:
client
EWS::Client
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 the Exchange server and retrieve calendar entries between the given timestamps. Pass the following arguments in a hash ref:
start
Entries with an end date on or after this timestamp will be included in the returned results.
end
Entries with a start date before this timestamp will be included in the results.
email
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
Passing the primary SMTP address of another account will retrieve the entries 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 calendar entries which matched the start and end criteria, and is of type EWS::Calendar::ResultSet. It's an iterator, so you can walk through the list of entries (see the synposis, above). For example:
EWS::Calendar::ResultSet
my $entries = $cal->retrieve({start => '', end => ''});
Provides the next item in the collection of calendar entries, or undef if there are no more items to return. Usually used in a loop along with has_next like so:
undef
has_next
while ($entries->has_next) { print $entries->next->Subject, "\n"; }
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.
Returns a true value if there is another entry in the collection after the current item, otherwise returns a false value.
Resets the iterator's cursor, so you can walk through the entries again from the start.
Returns the number of entries returned by the retrieve server query.
retrieve
Returns an array ref containing all the entries returned by the retrieve server query. They are each objects of type EWS::Calendar::Item.
EWS::Calendar::Item
These descriptions are taken from Microsoft's on-line documentation.
A DateTime object representing the starting date and time for a calendar item.
A DateTime object representing the ending date and time for a calendar item.
A human readable description of the time span of the event, for example:
25 Feb 2010
Feb 16 - 19, 2010
24 Feb 2010 15:00 - 16:00
Represents the subject of a calendar item.
Text attachment to the calendar entry which the user may have entered content into.
Will return true if the event item has content in its Body property, otherwise returns false. Actually returns the length of the Body text content.
Friendly name for where a calendar item pertains to (e.g., a physical address or "My Office").
Will return true if the event item has content in its Location property, otherwise returns false. Actually returns the length of the Location text content.
The type of calendar item indicating its relationship to a recurrence, if any. This will be a string value of one of the following, only:
Single
Occurrence
Exception
This is an alias (the native name, in fact) for the $item->Type property.
$item->Type
True if the event is of Type Occurrence or Exception, which means that it is a recurring event, otherwise returns false.
Indicates the sensitivity of the item, which can be used to filter information your user sees. Will be a string and one of the following four values, only:
Normal
Personal
Private
Confidential
When a client creates a calendar entry, there can be other people invited to the event (usually via the To: box in Outlook, or similar). This property contains an array ref of the display names ("Firstname Lastname") or the parties invited to the event.
Will return true if there are entries in the $item->DisplayTo property, in other words there were invitees on this event, otherwise returns false. Actually returns the number of entries in that list, which may be useful.
$item->DisplayTo
The display name (probably "Firstname Lastname") of the party responsible for creating the entry.
True if the calendar item has been cancelled, otherwise false.
Contains a bitmask of flags on the entry, but you probably want to use IsCancelled instead.
IsCancelled
Free/busy status for a calendar item, which can actually be one of the following four string values:
Free
Tentative
Busy
OOF (means Out Of Office)
NoData (means something went wrong)
If not provided the property will default to NoData.
NoData
This is an alias (the native name, in fact) for the $item->Status property.
$item->Status
Indicates whether an item has not yet been sent.
True if a calendar item is to be interpreted as lasting all day, otherwise false.
There is currently no handling of time zone information whatsoever. I'm waiting for my timezone to shift to UTC+1 in March before working on this, as I don't really want to read the Exchange API docs. Patches are welcome if you want to help out.
http://msdn.microsoft.com/en-us/library/aa580675.aspx
Oliver Gorwits <oliver@cpan.org>
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.
To install EWS::Client, copy and paste the appropriate command in to your terminal.
cpanm
cpanm EWS::Client
CPAN shell
perl -MCPAN -e shell install EWS::Client
For more information on module installation, please visit the detailed CPAN module installation guide.