XML for friends
The friends element in the Microsoft Outlook Social Connector (OSC) provider XML schema allows an OSC provider to specify information for a list of persons associated with an Outlook user in the social network. If the OSC provider supports cached synchronization, this list of person will contain only friends of the Outlook user on the social network. If the OSC supports on-demand or hybrid synchronization, this list may contain both friends and non-friends of the Outlook user.
Each person in the list is represented as a person element in the XML schema, which supports details such as first name, last name, and email addresses. OSC providers use the friends and person elements regardless of how they want the OSC to synchronize friend information from the social network. Note that the child elements of person are similar to some of the properties of an Outlook contact, which facilitates storing friends in an Outlook contacts folder specific to the social network, if the social network supports cached or hybrid synchronization of friends to an Outlook contacts folder.
Example scenarios
The following example scenarios show the OSC provider extensibility API calls that an OSC provider implements and the OSC makes to obtain friend information. Information is expressed in XML strings that conform to the OSC provider XML schema.
For an example of friends XML, see Friends XML Example. For more information about synchronizing friends' information, see Synchronizing Friends and Activities.
Scenario 1: get a list of friends
Scenario 1—OSC gets a list of friends, and an ISocialPerson object and a picture for each friend:
An OSC provider that supports showing friends from the social network site and allowing the OSC to cache friend information indicates that to the OSC by using the getFriends and cacheFriends elements, which are child elements of the capabilities element.
The OSC provider also implements the ISocialProvider::GetCapabilities, ISocialSession::GetPerson, ISocialPerson::GetFriendsAndColleagues, and ISocialPerson::GetPicture methods.
The OSC calls ISocialProvider::GetCapabilities to check the value of the following elements: getFriends to verify that the OSC provider supports showing friends from the social network, and cacheFriends to verify that the provider supports caching friends.
The OSC calls ISocialSession::GetPerson to get an ISocialPerson object for the Outlook user.
The OSC calls ISocialPerson::GetFriendsAndColleagues to get the Outlook user's friends list returned in the personCollection parameter string. The personCollection string complies with the XML schema definition for the friends element in the XML schema.
For each friend in the personCollection XML string, the OSC obtains value of the userID element to call ISocialSession::GetPerson to get an ISocialPerson object for that friend.
For each friend in the personCollection XML string, the OSC calls ISocialPerson::GetPicture to get a picture resource for that friend.
The OSC can make further calls on the ISocialPerson object to obtain activities and details (for example, email addresses) for that friend.
Scenario 2: synchronize friends
Scenario 2—OSC synchronizes friends dynamically:
An OSC provider that supports on-demand synchronization of friends and non-friends indicates that to the OSC by using the getFriends and dynamicContactsLookup elements. The OSC provider also sets the hashFunction element. All three elements are child elements of capabilities.
The OSC provider also implements the ISocialSession2::GetPeopleDetails method.
The OSC calls ISocialProvider::GetCapabilities to check the values of getFriends and dynamicContactsLookup to verify that the OSC provider supports friends and on-demand synchronization of friends and non-friends. The OSC also makes note of the value of hashFunction supported by the OSC provider.
For each user displayed in the People Pane, the OSC collects the user's email address and encrypts it by using the hash function specified in hashFunction. This forms an XML string that conforms to the XML schema definition for the hashedAddresses element.
The OSC calls ISocialSession2::GetPeopleDetails, providing this XML string of hashed addresses as the personAddresses parameter, to dynamically obtain updated details for persons in the personsCollection parameter. The personsCollection parameter string complies with the XML schema definition for the friends element in the XML schema.
Parent and child elements
The following are the two top-level elements in the friends schema.
| Element | Description |
|---|---|
| friends |
Represents the root element of a list of person elements. The ISocialPerson::GetFriendsAndColleagues, ISocialSession::FindPerson, and ISocialSession2::GetPeopleDetails return XML strings that conform to the schema definition of the friends element. |
| person |
Represents one person in a list of person elements. The ISocialPerson::GetDetails method returns an XML string that conforms to the schema definition of the person element. |
The following table describes each child element of the person element in the OSC provider XML schema.
For a complete definition of the OSC provider XML schema, including which elements are required or optional, see Outlook Social Connector Provider XML Schema.
| Element | Description |
|---|---|
| address |
Physical street address of the person. |
| anniversary |
Anniversary date for an event for the person. |
| askmeabout |
Topics of interest or expertise of the person. |
| birthday |
Date of birth for the person. |
| businessAddress |
Physical street address of the person's workplace. |
| businessCity |
City for the person's workplace. |
| businessCountryOrRegion |
Country or region of the person's workplace. |
| businessState |
State or province of the person's workplace. |
| businessZip |
Zip or postal code of the person's workplace. |
| cell |
Mobile telephone number for the person. |
| city |
City of the physical address for the person. |
| company |
Name of the company associated with the person. |
| countryOrRegion |
Country or region of the physical address of the person. |
| creationTime |
Creation time of the person's profile on the social network. |
| emailAddress |
Primary email address of the person. |
| emailAddress2 |
Secondary email address of the person. |
| emailAddress3 |
Tertiary email address of the person. |
| expirationTime |
Time that the person's profile data expires on the social network. |
| fileAs |
String by which the person is to be filed as a contact in an Outlook contacts file. |
| firstName |
First name or given name of the person. |
| friendStatus |
Friend status of this person with the logged on user on the social network. Must be one of the following values: friend, nonfriend, pending, pendingin, pendingout. |
| fullName |
Full name of the person. |
| gender |
Gender of the person. Must be one of the following values: male, female, unspecified. |
| homePhone |
Home telephone number for the person. |
| index |
Location of the person's hashed address in the personsAddresses string parameter passed to a call to the ISocialSession2::GetPeopleDetails method. It also indicates the person's person XML in the personsCollection string returned by GetPeopleDetails. |
| industries |
Industries that the person is engaged in. |
| interests |
Interests or hobbies of the person. |
| lastModificationTime |
Time that the person's profile was last modified on the social network. |
| lastName |
Last name or surname of the person. |
| location |
The location of the person. |
| nickname |
A shorter name or invented name of the person. |
| otherAddress |
Alternative street address of the person. |
| otherCity |
City of the person's alternative address. |
| otherCountryOrRegion |
Country or region of the person's alternative address. |
| otherState |
State or province of the person's alternative address. |
| otherZip |
Zip or postal code of the person's alternative address. |
| phone |
Primary contact telephone number for the person. |
| pictureUrl |
URL for a profile picture of the person. |
| relationship |
Relationship of this person with the logged on user. |
| schools |
The schools that the person goes or went to. |
| skills |
Personal skills of the person. |
| state |
State or province of the physical address of the person. |
| title |
Designation added to the person's name. |
| userID |
ID to identify the person on the social network. |
| webProfilePage |
Webpage address that contains a profile of the person. |
| website |
The person's web site. |
| workPhone |
Business telephone number for the person. |
| zip |
ZIP code or postal code of the physical address of the person. |