Class: Contacts::WindowsLive

Inherits:
Object
  • Object
show all
Defined in:
lib/contacts/windows_live.rb

Overview

How I can fetch Windows Live Contacts?

To gain access to a Windows Live user’s data in the Live Contacts service, a third-party developer first must ask the owner for permission. You must do that through Windows Live Delegated Authentication.

This library give you access to Windows Live Delegated Authentication System and Windows Live Contacts API. Just follow the steps below and be happy!

Registering your app

First of all, follow the steps in this page to register your app.

Configuring your Windows Live YAML

After registering your app, you will have an appid, a secret key and a return URL. Use their values to fill in the config/contacts.yml file. The policy URL field inside the YAML config file must contain the URL of the privacy policy of your Web site for Delegated Authentication.

Authenticating your user and fetching his contacts

wl = Contacts::WindowsLive.new
auth_url = wl.get_authentication_url

Use that auth_url to redirect your user to Windows Live. He will authenticate there and Windows Live will POST to your return URL. You have to get the body of that POST, let’s call it post_body. (if you’re using Rails, you can get the POST body through request.raw_post, in the context of an action inside ActionController)

Now, to fetch his contacts, just do this:

contacts = wl.contacts(post_body)
#-> [ ['Fitzgerald', '[email protected]', '[email protected]'],
      ['William Paginate', '[email protected]'], ...
    ]

– This class has two responsibilities:

  1. Access the Windows Live Contacts API through Delegated Authentication

  2. Import contacts from Windows Live and deliver it inside an Array

Constant Summary collapse

CONFIG_FILE = 
File.dirname(__FILE__) + '/../config/contacts.yml'

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(config_file = CONFIG_FILE) ⇒ WindowsLive

Initialize a new WindowsLive object.

Paramaters

  • config_file <String>

    The contacts YAML config file name

– You can check an example of a config file inside config/ directory



61
62
63
64
65
 
# File 'lib/contacts/windows_live.rb', line 61

def initialize(config_file=CONFIG_FILE)
  confs = YAML.load_file(config_file)['windows_live']
  @wll = WindowsLiveLogin.new(confs['appid'], confs['secret'], confs['security_algorithm'],
                              nil, confs['policy_url'], confs['return_url'])
end

Class Method Details

.parse_xml(xml) ⇒ Object

This method parses the XML Contacts document and returns the contacts inside an Array

Paramaters

  • xml <String>

    A string containing the XML contacts document



134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
 
# File 'lib/contacts/windows_live.rb', line 134

def self.parse_xml(xml)
  doc = Hpricot::XML(xml)

  contacts = []
  doc.search('/livecontacts/contacts/contact').each do |contact|
    email = contact.at('/preferredemail').inner_text
    email.strip!

    first_name = last_name = nil
    if first_name = contact.at('/profiles/personal/firstname')
      first_name = first_name.inner_text.strip
    end

    if last_name = contact.at('/profiles/personal/lastname')
      last_name = last_name.inner_text.strip
    end
    
    name = nil
    if !first_name.nil? || !last_name.nil?
      name = "#{first_name} #{last_name}"
      name.strip!
    end
    new_contact = Contact.new(email, name)
    contacts << new_contact
  end

  return contacts
end

Instance Method Details

#access_live_contacts_api ⇒ Object

This method access the Windows Live Contacts API Web Service to get the XML contacts document



115
116
117
118
119
120
121
122
123
124
125
126
 
# File 'lib/contacts/windows_live.rb', line 115

def access_live_contacts_api
  http = http = Net::HTTP.new('livecontacts.services.live.com', 443)
  http.use_ssl = true

  response = nil
  http.start do |http|
     request = Net::HTTP::Get.new("/users/@L@#{@consent_token.locationid}/rest/invitationsbyemail", {"Authorization" => "DelegatedToken dt=\"#{@consent_token.delegationtoken}\""})
     response = http.request(request)
  end

  return response.body
end

#contacts(consent) ⇒ Object

This method return the user’s contacts inside an Array in the following format:

[ 
  ['Brad Fitzgerald', '[email protected]'],
  [nil, '[email protected]'],
  ['William Paginate', '[email protected]']  ...
]

Paramaters

  • consent <String>

    A string containing the Consent given to you inside

the redirection POST from Windows Live



106
107
108
109
110
 
# File 'lib/contacts/windows_live.rb', line 106

def contacts(consent)
  process_consent(consent)
  contacts_xml = access_live_contacts_api()
  contacts_list = WindowsLive.parse_xml(contacts_xml)
end

#get_authentication_url ⇒ Object

Windows Live Contacts API need to authenticate the user that is giving you access to his contacts. To do that, you must give him a URL. That method generates that URL. The user must access that URL, and after he has done authentication, hi will be redirected to your application.



73
74
75
 
# File 'lib/contacts/windows_live.rb', line 73

def get_authentication_url
  @wll.getConsentUrl("Contacts.Invite")
end

#process_consent(consent) ⇒ Object

After the user has been authenticaded, Windows Live Delegated Authencation Service redirects to your application, through a POST HTTP method. Along with the POST, Windows Live send to you a Consent that you must process to access the user’s contacts. This method process the Consent to you.

Paramaters

  • consent <String>

    A string containing the Consent given to you inside

the redirection POST from Windows Live



87
88
89
90
91
 
# File 'lib/contacts/windows_live.rb', line 87

def process_consent(consent)
  consent.strip!
  consent = URI.unescape(consent)
  @consent_token = @wll.processConsent(consent)
end