Contacts Control Reference

Description

Required

A URL to your Web site’s privacy statement.

When you drag and drop the Contacts control from the toolbox to your Web page in markup view, a blank privacyPolicy.htm file is added to your project. You can either add your privacy statement into this file or change this property setting to link to a URL to your Web site’s privacy statement.

Required

The Windows Live Contact control uses a communication channel technique to send data between pages from different domains within the browser.

When you drag and drop the Contacts control from  the toolbox to your Web page in markup view, a channel.htm file is added to your project. This file is required for the Contacts control to work properly.

Optional for List View, not applicable to Tile View

A comma delimited list of fields you’d like returned. The Control sets name and email fields by default.

Valid values are: name (name or nickname , or email if no name is available), email (primary e-mail address, or personal or business email is not primary is indicated), phone (primary phone number), firstname, middlename, lastname, nickname, passportname (user’s 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

Sets the view of the control. Valid values are: List, Tile and TileList. If omitted, the control defaults to TileList.

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 yours, 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 market or language requested. Supported today:

Chinese (simplified): zh-cn

Dutch: nl

English: en

French: fr

German: de

Italian: it

Japanese: ja

Korean: ko

Spanish: sp

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

Optional

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.

Optional

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

Optional

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

Optional

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

Optional

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

Description

A client-side event handler called when a user signs in.

Event handler signature (in JavaScript):

   function (sender, args)

where

• sender is the DOM element raising the event.
• args is the event arguments and has methods get_cancel() and set_cancel().

Use the set_cancel method to cancel the execution of the server event associated with a user sign-in action.

The following example shows the declaration of the contacts control and the OnClientSignIn event handler which executes when a user signs in and cancels the server signin event.

        < live:Contacts ID="Contacts1" runat="server" 
            ChannelEndpointURL="~/channel.htm" 
            DataDesired="name,email" 
            Height="500px" 
            OnClientSignIn="OnClientSignIn" 
            OnServerSignIn="Contacts1_OnServerSignIn"
            PrivacyStatementURL="~/privacyPolicy.htm" 
            View="List" 
            Width="250px"/> 

        function OnClientSignIn(sender, args){
         //add client side logic signin event here
         args.set_cancel(true); //cancels the server event
        }
                

A client-side event handler called when a user signs in.

Event handler signature (in JavaScript):

   function (sender, args)

where

• sender is the DOM element raising the event.
• args is the event arguments and has methods get_cancel() and set_cancel().

Use the set_cancel method to cancel the execution of the server event associated with a user sign-in action.

A client-side event handler called when data is received from a user’s contacts store.

Event handler signature (in JavaScript):

   function (sender, args)

where

• sender is the DOM element raising the event.
• args is the event arguments and has methods get_cancel() and set_cancel() and an array of objects, one per contact.

Use the set_cancel method to cancel the execution of a server event associated with a user sign-out action. The contact information is provided in the properties of the object, in camel-capped style, first letter lowercase. The contacts object contains only the fields you requested in the DataDesired property.

The following example shows the data processing when the OnClientData event is raised.

 < live:Contacts ID="Contacts1" runat="server" 
            ChannelEndpointURL="~/channel.htm" 
            DataDesired="name,email" 
            Height="500px" 
            OnClientData="OnClientData"
            PrivacyStatementURL="~/privacyPolicy.htm" 
            View="List" 
            Width="250px"/ >

function OnClientData(sender, args){
  var s = "Contacts: " + args.contacts.length + " records received \r\n";
  for (var i = 0; i < args.contacts.length; i++) {
     for (var j in args.contacts[i]) {
         s += j + ": " + args.contacts[i][j] + " \r\n";
     }
  }
  alert(s);
}        

A client-side event handler called when changes related to a user’s contacts are committed to the contacts store.

Event handler signature (in JavaScript):

   function (sender, args)

where

• sender is the DOM element raising the event.
• args is the event arguments and has methods get_description(), get_cancel() and set_cancel().

Use the set_cancel method to cancel the execution of the server event associated with a user sign-out action.

Use the get_description() method to access an array of failed contact objects. The returned array has a description of each failed contact, describing what activity failed and the key of the contact object that failed.

A client-side event handler called when an error is detected.

Event handler signature (in JavaScript):

   function (sender, args)

where

• sender is the DOM element raising the event.
• args is the event arguments and has methods get_cancel() and set_cancel().

You can use set_cancel method to cancel the execution of the server event associated with a user sign-out action.

A server-side event handler called when a user signs in.

Event handler signature (in C#):

protected void (object sender, EventArgs e)

where

• sender is the Contacts object.
• e is the event arguments.

A server-side event handler that gets called when user signs out

Event handler signature (in C#):

protected void (object sender, EventArgs e)

where

• sender is the Contacts object.
• e is the event arguments.

A server-side event handler that gets called data is received from user’s contacts store

Event handler signature (in C#):

protected void (object sender, ServerDataEventArgs e)

where

• sender is the Contacts object.
• e is the ServerDataEventArgs that contains the collection of Microsoft.Live.ServerControls.Contact.

Microsoft.Live.ServerControls.Contact is a class that contains all the fields for the contact.

A server-side event handler called when changes related to a user’s contacts are committed to the contacts store.

Event handler signature (in c#):

protected void Contacts_OnServerCommit(object sender, ServerCommitEventArgs e)

Where

• sender is the Contacts object.
• e is the ServerCommitEventArgs that contains collection of Microsoft.Live.ServerControls.ServerCommitError.

Microsoft.Live.ServerControls.ServerCommitError is a class that provides information on the type of Microsoft.Live.ServerControls.CommitError thrown while processing Microsoft.Live.ServerControls.CommitActivity.

Microsoft.Live.ServerControls.CommitError can be of the following types:

• 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 single 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

Microsoft.Live.ServerControls.CommitActivity can be of following types:

• Commit
• Create
• Delete

A server-side event handler that gets called when an error is detected

Event handler signature (in C#):

protected void (object sender, EventArgs e)

Description

Required.

Specifies the contacts to be created.

A collection of contacts to be created is specified where each contact is an instance of class Microsoft.Live.ServerControls.Contact. A maximum of 30 contacts can be specified at any time.

Each contact 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

Description

When the collection passed does not contain objects of Contact type

When the contacts argument passed is null

When the number of contacts specified in the contacts collection passed is more than 30

Description

Required.

Specifies the email addresses of the contacts to be deleted.

A collection of email addresses. A maximum of 30 contacts can be specified. The specified email addresses are compared with the primary email for a match. Any contacts with a match is deleted.

The primary email is determined by the following order.

1. The preferred email is specified on the contact
2. Passportname (User’s Passport ID or Windows Live ID)
3. EmailPersonal
4. EmailBusiness
5. EmailOther

Description

When a collection passed does not contain objects of Contact type

When a contacts argument passed is null

When a number of contacts specified in the contacts collection passed is more than 30

Description

When operation count exceeds 1000