API Reference

Required
The DOM element (object) which hosts the Windows Live Contacts control. The control displays inside this element.  Note that the HTML attributes of this hostElement may be stripped or altered: to control style and placement, use script or CSS rather than inline HTML attributes.  The Windows Live Contacts control requires a minimum width of 172 pixels and minimum height of 232 pixels.  The control resizes as its container resizes, and will show more information in larger layouts.

Optional
Valid values are: list, tile, and tilelist. If omitted, the control defaults to list. 

Required
A URL to a document that describes how your web site will use the contact information the user is about to send to your web page. 

Optional for Tile View, not applicable for List View
Text string to be inserted into instant messages and emails from Tile View. If omitted, the control defaults to the URL of your web site. If you desire to have nothing filled in for your users, please specify an empty string ("") as the message.

Known Issue: Double byte characters are known to get corrupted in emails on Windows XP due to encoding limitations. This scenario functions properly for single byte characters, as well as for all characters on Windows Vista.

Optional
The relative path to the copy of channel.htm on your Web server or domain. If you get this wrong, you won't be able to receive any data from the control. If omitted, the control defaults to looking for "channel.htm" in the same URL directory as the host page.

Optional for List View, not applicable for Tile View
A string containing a comma delimited list of field names you wish to obtain for each contact that the user selects.  If omitted, the control defaults to name and email.

Valid values are:

name  (Name or nickname, or email address if no name is available.)
email  (Primary email address, or personal or business email if no primary is indicated.)
phone  (Primary phone number)
firstname, middlename, lastname, nickname, passportname (user's Passport ID or Windows Live ID), emailpersonal, emailbusiness, emailother, phonepersonal, phonebusiness, phonemobile, phonepager, phonefax, phoneother, personalstreet, personalcity, personalstate, personalcountry, personalpostalcode, businessname, businessstreet, businesscity, businessstate, businesscountry, businesspostalcode, websitepersonal, websitebusiness, spacesrssurl, spacesrsscontent

Optional
The market or language requested. Supported today

Chinese (simplified): zh-cn
Dutch: nl
English: en
French: fr
German: de
Italian: it
Japanese: ja (jp is deprecated)
Korean: ko
Portuguese (Brazil): pt-br
Spanish: sp
Swedish: sv

If no market is specified, the English control is displayed.

Sets the background color scheme of the internal area.
Color values:

Hex: #ffffff style
Rgb: rgb(255,255,255) style
W3C standard colors: aqua| black| blue| fuchsia| gray| green| lime| maroon| navy| olive| purple| red| silver| teal| white| yellow

If no color is specified, the default colors apply.

Sets the color scheme of the internal text. See above for supported color values.

Sets the color scheme of the outer background. See above for supported color values.

Sets the color scheme of the outer text. See above for supported color values.

Sets the color scheme of the URL hyperlinks. See above for supported color values.

Optional
This function receives notifications of when the user logs in. The event handler prototype is function ().

Optional
This function receives notifications of when the user logs out. The event handler prototype is function ().

Optional
This function receives notifications of when there is an error. The event handler prototype is function ().

Optional for List View, not supported in Tile View
This function receives notifications of when data is received from the contacts control. The event handler prototype is function (p_contacts), where p_contacts contains an array of objects, one per contact.  The contact information is provided in the properties of the object, in camel-capped case style, first letter lowercase.  For example, p_contacts[0].businessPostalCode.  Only the fields you request in the dataDesired parameter will be returned in these contact objects.

Optional
This function receives notifications when all contacts controls on the page are loaded. The event handler prototype is function ().

Definition

Required
An array of objects, where each object represents a contact to add. A maximum of 30 contacts can be passed in at one time.

Each object has the following fields:

• firstname
• middlename
• lastname
• nickname
• emailpersonal
• emailbusiness
• emailother
• phonepersonal
• phonebusiness
• phonemobile
• phonepager
• phonefax
• phoneother
• personalstreet
• personalcity
• personalstate
• personalcountry
• personalpostalcode
• businessname
• businessstreet
• businesscity
• businessstate
• businesscountry
• businesspostalcode
• websitepersonal
• websitebusiness

Definition

Message: “Invalid argument: <argument name>”
                 When the contacts is not an array.

Message: “An undefined argument was passed: <argument name>”
                 When the contacts is undefined.    

Message: "Only 30 Contacts can be passed in a single operation"
                 When more than 30 contacts are passed.

Definition

Required

An array of email addresses. A maximum of 30 contacts can be passed in. The passed in email addresses are compared with the primary email for match. Any contacts with a match are deleted.

The primary email is figured out based on the below order. Once an email is found, that is used as the primary email.

1. The preferred email if specified on the contact
2. passportname (user's Passport ID or Windows Live ID)
3. emailpersonal
4. emailbusiness
5. emailother

Definition

Message: “Invalid argument: <argument name>”
                 When the contacts are not an array

Message: “An undefined argument was passed: <argument name>”
                 When the contacts are undefined

Definition

Required

This function is called when the operation is complete. Only 1000 operations can be executed in each commit call.

The callback function prototype is function (p_description).

• p_description returns an array of failed contact object operations.
• The failed activity is defined on the contacts objects.
• The primary email is provided as a key field to provide context.

For example, a p_description may look like as follows:

{
    C1:{
        key:”someone@example.com”,
        activity:”delete”
        error:”ObjectNotFoundError”,
    },
    C2:{
        key:”someone2@e@xample.com”,
        activity:”create”
        error:” BadEmailError”
    }
};

Activities can be one of the following:

• create
• delete
• commit

Errors can be one of the following:

• AuthError: Implies the commit was initiated while the user was not logged in.
• UnknownError: Implies there was a critical failure in the operation not caused by issues in the data
• DuplicateError: Implies a contact record already existed for a primary email address in a create operation, or a delete operation for the same primary email was duplicated
• BadEmailError: Implies an email address was not well formatted
• ObjectNotFoundError: Implies a contact record was not found for a primary email address
• InvalidFieldError: Implies an invalid field was passed in on a contact object
• InvalidOperationError: Implies more than 30 contacts were passed in a single createContacts or deleteContacts call, or more than 1000 operations were queued for a 1 commitContacts call
• QuotaLimitReachedError: Implies the number of contacts reached the allowed quota in Windows Live Contacts
• UserRefuse: Implies the user refused to accept the modifications

Definition

Message: "An undefined argument was passed: <argument name>"
                 When resultCallback is undefined.

Message: "Only 1000 operations can be queued in a single commit operation"
                  When more than 1000 operations have been queued.