NAME
WWW::Live::Contacts - A Microsoft Live Contacts client
VERSION
1.0.0
DESCRIPTION
Provides access to the Microsoft Live Contacts web services API.
SYNOPSIS
# Construct a client object
my $client = WWW::Live::Contacts->new(
consent_token => $token, # See WWW::Live::Auth
%lwp_params # Constructor parameters for LWP::UserAgent
);
# Set the proxy (if necessary)
$client->proxy( 'http', 'http://proxy.mycompany.com' );
# Retrieve contacts
for my $contact ( $client->get_contacts()->entries() ) {
print $contact->full_name();
}
# Add contacts
my $contact = WWW::Live::Contacts::Contact->new();
$contact->first( 'Andrew' );
$contact->last ( 'Jenkinson' );
$client->write_contacts( $contact );
# Update contacts
$contact->work_email()->address( 'foo@bar.com' );
$contact->add_address( $address );
$contact->home_phone()->mark_deleted();
$client->write_contacts( $contact );
# Delete contacts
$client->delete_contacts( $contact->id );
# OR
$contact->mark_deleted();
$client->write_contacts( $contact );METHODS
new
Constructs a new client object representing the address book of a single user.
Requires a consent token, and optionally accepts LWP::UserAgent parameters.
my $client = WWW::Live::Contacts->new(
consent_token => $token,
%lwp_params
);proxy
Passes proxy settings through to LWP::UserAgent. Note the proxy must accept
HTTPS connections.
$client->proxy( 'http://proxy.mycompany.com' );get_contacts
Gets the full set of contacts.
my $collection = $client->get_contacts(
filter => 'LiveContacts(Contact(ID))', # fields to populate
modified_since => $date # string or unix time
);
if ( $collection->is_modified ) {
# ... do something with the contacts
}
Contacts are populated with data according to a given filter. If the filter is
not specified, the API default is used. If some data has changed since the
'modified_since' parameter, or no such parameter is specified, all contacts
are returned. Otherwise no contacts are returned. This behaviour makes it
possible to deduce if deletes have taken place.
This method returns a WWW::Live::Contacts::Collection object holding the
contacts and the last modified date of the collection.get_contact
Gets a single contact by its ID, with all available data.
my $contact = $client->get_contact( $contact_ID );write_contacts
Inserts/updates/deletes the given contacts, according to their states.
$client->write_contacts( $new_contact, $updated_contact );
Each contact is processed in full, including all its children (emails etc).write_emails
Inserts/updates/deletes the given email addresses, according to their states.
$client->write_emails( $contact_ID, @emails );write_phones
Inserts/updates/deletes the given phone numbers, according to their states.
$client->write_phones( $contact_ID, @phones );write_addresses
Inserts/updates/deletes the given addresses, according to their states.
$client->write_addresses( $contact_ID, @addresses );delete_contacts
Deletes one or more contacts.
$client->delete_contacts( @contact_IDs );delete_emails
Deletes one or more email addresses.
$client->delete_emails( $contact_ID, @email_IDs );delete_phones
Deletes one or more phone numbers.
$client->delete_phones( $contact_ID, @phone_IDs );delete_addresses
Deletes one or more addresses.
$client->delete_addresses( $contact_ID, @address_IDs );AUTHOR
Andrew M. Jenkinson <jenkinson@cpan.org>
LICENSE AND COPYRIGHT
Copyright 2008-2011 Andrew M. Jenkinson.
This program is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.
LIMITATIONS
The Windows Live Contacts API does not support inserting or updating multiple "collection" entities in the same request. A collection entity is a data type of which there can be more than one (e.g. contacts, emails, phones, addresses). As a result, calls to the write_* methods are performed using several requests and thus are NOT atomic. A delete of a single contact is an atomic action, however.
DEPENDENCIES
WWW::Live::Auth LWP::UserAgent HTTP::Date Carp