NAME

WWW::Live::Contacts - A Microsoft Live Contacts client

VERSION

1.0.1

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

SEE ALSO

WWW::Live::Auth

LWP::UserAgent

cpanm WWW::Live::Contacts

perl -MCPAN -e shell
install WWW::Live::Contacts