XML for Friends
Collapse the table of content
Expand the table of content

XML for Friends

Office 2013 and later

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.

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—OSC gets a list of friends, and an ISocialPerson object and a picture for each friend:

    1. 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.

    2. The OSC provider also implements the ISocialProvider::GetCapabilities, ISocialSession::GetPerson, ISocialPerson::GetFriendsAndColleagues, and ISocialPerson::GetPicture methods.

    3. 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.

    4. The OSC calls ISocialSession::GetPerson to get an ISocialPerson object for the Outlook user.

    5. 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.

    6. 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.

    7. 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—OSC synchronizes friends dynamically:

    1. 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.

    2. The OSC provider also implements the ISocialSession2::GetPeopleDetails method.

    3. 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.

    4. 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.

    5. 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.

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.

Show:
© 2016 Microsoft