Welcome Sign in
Windows Live Developer Center
 Printer Friendly Version      Send     
Click to Rate and Give Feedback
MSDN
MSDN Library
Live Services SDK
 Contacts Control
Windows Live
Contacts Control

This topic describes the parameters and default values created when you add the Contacts control to enable Windows Live™ Contacts functionality on a Web page.

<live:Contacts 
      ID="id" 
      DataDesired="data" 
      Height="height" 
      PrivacyStatementURL="privacy_url" 
      View="view" 
      Width="width" 
/>

The parameters shown in the syntax section and in the beginning of the parameters table are the parameters created when dragging the control from the Toolbox and dropping it on a Web page. The default values in the description are also those created when dragging the control from the Toolbox and dropping it on a Web page.

Parameter Description

ID

Required. The unique identifier for the control on the Web page. The default value is Contacts1.

DataDesired

Optional for List view; ignored otherwise. A comma-separated list of contact information that the control returns. The valid values are name, email, phone, firstname, middlename, lastname, nickname, passportname, emailpersonal, emailbusiness, emailother, phonepersonal, phonebusiness, phonemobile, phonepager, phonefax, phoneother, personalstreet, personalcity, personalstate, personalcountry, personalpostalcode, businessname, businessstreet, businesscity, businessstate, businesscountry, businesspostalcode, websitepersonal, websitebusiness, spacesrssurl, spacesrsscontent. The default value is name,email.

Height

Optional. The height of the control on the Web page. The default value is 500px.

PrivacyStatementURL

Required. A URL to the Web site privacy statement. Dragging the control to a Web page creates an empty privacyPolicy.htm file in your project and sets this parameter to ~/privacyPolicy.htm.

View

Optional. The view presented by the control. The valid values are List, Tile, and TileList. The default value is TileList.

Width

Optional. The width of the control on the Web page. The default value is 250px.

Message

Optional for Tile view; ignored otherwise. A string that is inserted into instant messages and e-mails when in Tile view. If omitted, the control defaults to the URL of the Web site. This parameter can be an empty string ("").

Market

Optional. The market or language requested. The following values are supported:

zh-cn (simplified Chinese)

nl (Dutch)

en (English)

fr (French)

de (German)

it (Italian)

ja (Japanese)

ko (Korean)

sp (Spanish

pt-br (Portuguese Brazlian)

sv (Swedish)

The default value is en (English).

InnerBackgroundColor

Optional. The background color of the inner area of the control. This means you can specify a color name, such as salmon, or a #ffffff value, such as #ff0000 for red.

If no color is specified, the default colors apply.

InnerTextColor

Optional. The color of the inner text. See InnerBackgroundColor parameter for values.

OuterBackgroundColor

Optional. The background color of the outer area of the control. See the InnerBackgroundColor parameter for values.

OuterTextColor

Optional. The color of the outer text. See the InnerBackgroundColor parameter for values.

LinkColor

Optional. The color of links in the control. See the InnerBackgroundColor parameter for values.
Note:
As with any control, the Contacts control parameters can be retrieved or set in server-side code and retrieved in client-side code. What makes the Contacts control special is that these parameters also can be set in client-side code. The only additional work required is if you update the look of the control, remember also to update the DOM.

The Contacts control can raise both server and client events. Server events occur after client events and are handled in server-side code that you write for the Web page. Client events are handled in client script, typically ECMAScript (JavaScript), and are raised before server events. The server-side events are triggered even if client-side events are not present.

Event Designation: Server or Client Description

OnClientSignIn

Client

Raised when the user signs in.

OnClientSignOut

Client

Raised when the user signs out.

OnClientData

Client

Raised when data about the contact is received.

OnClientCommit

Client

Raised when changes related to a user’s contacts are committed to the contacts store.

OnClientError

Client

Raised when an error is detected.

OnClientLoad

Client

Raised when the control is loaded.

OnServerSignIn

Server

Raised when the user signs in.

OnServerSignOut

Server

Raised when the user signs out.

OnServerData

Server

Raised when data about the contact is received.

OnServerCommit

Server

Raised when changes related to a user’s contacts are committed to the contacts store.

OnServerError

Server

Raised when an error is detected.

OnClientSignIn Event

A client event that is raised when the user signs in.

JavaScript Syntax

function OnClientSignInHandler (sender, args)

Parameters

Parameter Description

sender

The DOM element raising the event.

args

The event arguments object. This object has the methods get_cancel and set_cancel.

Remarks

Use the set_cancel method to cancel the execution of the associated server event.

OnClientSignOut Event

A client event that is raised when the user signs out.

JavaScript Syntax

function OnClientSignOutHandler(sender, args)

Parameters

Parameter Description

sender

The DOM element raising the event.

args

The event arguments object. This object has the methods get_cancel and set_cancel.

Remarks

Use the set_cancel method to cancel the execution of the associated server event.

OnClientData Event

A client event that is raised when data about the contact is received.

JavaScript Syntax

function OnClientDataHandler(sender, args)

Parameters

Parameter Description

sender

The DOM element raising the event.

args

The event arguments object. This object has the methods get_cancel and set_cancel.

Remarks

Use the set_cancel method to cancel the execution of the associated server event. Contact information is provided in the properties of the object, in camel-capped style, first letter lowercase. The contacts object contains only the fields requested in the DataDesired property.

Example

The following example demonstrates how to display the information returned when this event handler is called.

function OnClientData(sender, args)
{
   var c = args.contacts;
   var l = c.length;
   var s = l + " contacts records received\n";

   for(var i = 0; i < l; i++)
   {
      for (var j in c[i])
      {
         s += j + ": " + c[i][j] + "\n";
      }
   }
   
   alert(s);
}

OnClientCommit Event

A client event that is raised when changes related to a user’s contacts are committed to the contacts store.

JavaScript Syntax

function OnClientCommitHandler(sender, args)

Parameters

Parameter Description

sender

The DOM element raising the event.

args

The event arguments object. This object has the methods get_cancel, get_description, and set_cancel.

Remarks

Use the set_cancel method to cancel the execution of the associated server event. 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.

OnClientError Event

A client event that is raised when an error is detected.

JavaScript Syntax

function OnClientErrorHandler(sender, args)

Parameters

Parameter Description

sender

The DOM element raising the event.

args

The event arguments object. This object has the methods get_cancel and set_cancel.

Remarks

Use the set_cancel method to cancel the execution of the associated server event.

OnClientLoad Event

A client event that is raised when the control is loaded.

JavaScript Syntax

function OnClientLoadHandler(sender, args)

Parameters

Parameter Description

sender

The DOM element raising the event.

args

The event arguments object. This object has the methods get_cancel and set_cancel.

Remarks

Use the set_cancel method to cancel the execution of the associated server event.

OnServerSignIn Event

A server event that is raised when the user signs in.

C# Syntax

protected void OnServerSignInHandler(object sender, EventArgs e)

Parameters

Parameter Description

sender

The Contacts object.

e

The event arguments object.

OnServerSignOut Event

A server event that is raised when the user signs out.

C# Syntax

protected void OnServerSignOutHandler(object sender, EventArgs e)

Parameters

Parameter Description

sender

The Contacts object.

e

The event arguments object.

OnServerData Event

A server event that is raised when data about the contact is received.

C# Syntax

using Microsoft.Live.ServerControls;
…
protected void OnServerDataHandler(object sender, ServerDataEventArgs e)

Parameters

Parameter Description

sender

The Contacts object.

e

A ServerDataEventArgs object that contains a collection of Contact objects.

OnServerCommit Event

A server event that is raised when changes related to a user's contacts are committed to the contacts store.

C# Syntax

using Microsoft.Live.ServerControls;
…
protected void OnServerCommitHandler(object sender, ServerCommitEventArgs e)

Parameters

Parameter Description

sender

The Contacts object.

e

A ServerCommitEventArgs object that contains a collection of ServerCommitError objects.

Remarks

The ServerCommitError object provides information about errors during the commit phase. It has two properties, CommitActivity and CommitError.

CommitActivity can have any of the following values.

  • Commit means the activity was committed.
  • Create means the contact was created, but the creation has not yet been committed.
  • Delete means the contact was deleted, but the deletion has not yet been committed.

CommitError can have any of the following values.

  • AuthError means that the commit was initiated while the user was not logged in.
  • UnknownError means that there was a critical failure that was not caused by the data.
  • DuplicateError means that a contact record already existed for a primary e-mail address in a create operation, or that a delete operation for the same primary e-mail was duplicated.
  • BadEmailError means that an e-mail address was not well formatted.
  • ObjectNotFoundError means that a contact record was not found for a primary e-mail address.
  • InvalidFieldError means that an invalid field was passed in with a contact object.
  • InvalidOperationError means that more than 30 contacts were passed in a single CreateContacts or DeleteContacts call, or more than 1,000 operations were queued for a single CommitContacts call.
  • QuotaLimitReachedError means that the number of contacts reached the allowed quota in Windows Live Contacts.
  • UserRefuse means that the user refused to accept the modifications.

OnServerError Event

A server event that is raised when an error is detected.

C# Syntax

protected void OnServerErrorHandler(object sender, EventArgs e)

Parameters

Parameter Description

sender

The Contacts object.

e

The event arguments object.

The Contacts control has the following methods that you can use dynamically to manage contacts for a Web site visitor.

Method Description

AbortContacts

Aborts any pending changes to the control.

CommitContacts

Commits any changes to the control.

CreateContacts

Adds a collection of contacts to the control.

DeleteContacts

Deletes a collection of contacts from the control.

AbortContacts Method

Aborts any pending changes to the control.

C# Syntax

void ContactControl.AbortContacts();

CommitContacts Method

Commits any changes to the control.

C# Syntax

void ContactControl.CommitContacts();

CreateContacts

Adds a collection of contacts to the control.

C# Syntax

void ContactControl.CreateContacts(contacts);

Parameters

Parameter Description

contacts

A collection of Contact objects. Up to 30 Contact objects can be added at time.

Exceptions

Exception Description

ArgumentException

When the collection passed does not contain objects of Contact type.

ArgumentNullException

When the contacts argument is null.

InvalidOperationException

When there are more than 30 Contact objects in the contacts argument.

Remarks

You must call the CommitContacts method to save any changes to the control.

Example

The following example adds a contact with the e-mail address nobody@fabrikam.com to the control Contacts1.

List<Contact> myContacts = new List<Contact>();
Contact myContact = new Contact();
myContact.EmailPersonal = "nobody@fabrikam.com";
myContacts.Add(myContact);
Contacts1.CreateContacts(myContacts);
Contacts1.CommitContacts();

DeleteContacts

Deletes a collection of contacts from the control.

C# Syntax

void ContactControl.DeleteContacts(addresses);

Parameters

Parameter Description

addresses

A collection of String objects specifying the e-mail addresses of the contacts to delete.

Exceptions

Exception Description

ArgumentException

When the collection passed does not contain objects of String type.

ArgumentNullException

When the addresses argument is null.

InvalidOperationException

When there are more than 30 String objects in the addresses argument.

Example

The following example deletes a contact with the e-mail address nobody@fabrikam.com from the control Contacts1.

List<String> myContacts = new List<String>();
myContacts.Add("nobody@fabrikam.com");
Contacts1.DeleteContacts(myContacts);
Contacts1.CommitContacts();

Remarks

You must call the CommitContacts method to save any changes to the control.

© 2008 Microsoft Corporation. All rights reserved. Terms of Use  |  Trademarks  |  Privacy Statement
Page view tracker