Developing an Outlook Social Connector Provider for Outlook 2010, Outlook 2007, and Outlook 2003

Summary: The Microsoft Outlook Social Connector (OSC) is a Microsoft Outlook add-in that connects to social and business networks, including Microsoft SharePoint or other popular third-party sites, so users can stay in touch with the people in their networks without leaving Outlook. Learn about the OSC provider model, which provides an abstraction layer between the OSC and the APIs offered by social networks, and the interfaces that an Outlook Social Connector provider must implement. (40 printed pages)

Applies to:  Microsoft Outlook 2010 | Microsoft Office Outlook 2007 | Microsoft Office Outlook 2003 | Microsoft Outlook Social Connector Beta (version February 2010)
Provided by:  Randy Byrne, Microsoft Corporation

  Outlook Social Connector V1 32-Bit Beta

  Outlook Sample: Outlook Social Connector Provider

Contents

• Overview

• Technical Requirements

• Changes from the Previous Version of OSC Provider Extensibility

• Interface Reference

• XML Schema Reference

• Error Codes

• Provider Calling Sequence

• Provider Debugging

• Provider Deployment

• Best Practices for Developing an OSC Provider

• Sample OSC Provider

• Using the TestProvider Project

• Sample OSC Provider Templates

• Conclusion

• Additional Resources

Overview

This document discusses the interfaces that a Microsoft Outlook Social Connector provider (OSC provider) must implement. If the provider implements these interfaces and is installed on a supporting version of Outlook, the data from the social network becomes available to Outlook so that an end user can view social data in the context of the Outlook user interface.

The OSC shows activities in a pane that appears below the Reading Pane in the Outlook explorer window, as shown in Figure 1. The OSC is built on an open provider model, encouraging social network sites to build providers to work with the OSC to display social network data (such as friends, profiles, activities, and relationship information) in Outlook.

Figure 1. Outlook Social Connector pane

 

An OSC provider is a Component Object Model (COM) DLL that allows the OSC to access social network data in a way that is independent of the APIs of each social network. An OSC provider DLL must be installed locally on a client computer. It is not possible to connect the OSC directly to a social network on the Internet. An OSC provider must implement a set of interfaces, defined as part of the OSC provider extensibility, to communicate with the OSC.

The provider architecture of the OSC enables multiple providers to work with the OSC core engine and aggregate social information such as friends and activities. Figure 2 illustrates the OSC provider architecture.

Figure 2. Outlook Social Connector provider architecture

Technical Requirements

You can create an OSC provider by using managed languages such as Microsoft Visual C# or Microsoft Visual Basic, or unmanaged languages such as Microsoft Visual C++. You can use any tool that can create a COM-visible DLL component to develop an OSC provider. The decision to use a managed or unmanaged language to develop a provider should take into account the download size and dependencies of the provider installation package.

An OSC provider must be COM-visible as defined by the following:

• After installation, an OSC provider must be registered by using COM self-registration or regsvr32.

• COM registration of an OSC provider DLL registers the provider under HKCU or HKLM.

• A provider’s ProgID is registered under HKCU\Software\Microsoft\Office\Outlook\SocialConnector\SocialProviders.

• An OSC provider developed in a managed language (that is, a managed OSC provider) is COM-visible.

• An OSC provider should add values to the Windows registry that indicate that the provider DLL supports both single-threaded apartment (STA) and multithreaded apartment (MTA) threading models. For more information about COM threading models, see Descriptions and Workings of OLE Threading Models.

Methods in OSC provider extensibility must return primitive types such as string or bool. Certain string return values must comply with the schema definition for OSC provider extensibility. Only XML is supported as a return value.

JavaScript Object Notation (JSON) is not supported in version 1.0 of the provider extensibility model.

There are no dependencies on an XML parser. The OSC provider can use an XML parser that is included with Microsoft Office, such as Microsoft XML Core Services (MSXML), use the XML parsing capabilities built into the Microsoft .NET Framework, or use a third-party XML parser.

The assembly that supports OSC provider extensibility is the OSC provider extensibility DLL. This assembly is included with OSC version 1.0. Third-party developers can build OSC provider DLLs by using these extensibility interfaces. The following list shows the details of the OSC provider extensibility DLL:

• Extensibility DLL file name: socialprovider.dll

• Extensibility DLL friendly name: Microsoft Outlook Social Provider Extensibility

• Extensibility DLL major version: 14.0

• Extensibiilty DLL TypeLib version: 1.0

The developer selects the DLL friendly name when setting a reference to Socialprovider.dll in the Visual Studio 2008 Tools for Office Add Reference dialog box, shown in Figure 3.

Figure 3. Visual Studio 2008 Add Reference dialog box

Changes from the Previous Version of OSC Provider Extensibility

The following table shows the members that have been added to or removed from the corresponding provider interface.

Interface and member	Comment
ISocialPerson::DoNotFollowThisPerson	Removed after OSC build 14.0.4612.1000.
ISocialPerson::FollowThisPerson	Removed after OSC build 14.0.4612.1000.
ISocialProvider::SocialNetworkGuid	Added after OSC build 14.0.4730.1003.
ISocialSession::FollowPerson	Added after OSC build 14.0.4612.1000.
ISocialSession::GetActivities	Added after OSC build 14.0.4612.1000.
ISocialSession::InviteToNetworks	Removed after OSC build 14.0.4612.1000.
ISocialSession::UnFollowPerson	Added after OSC build 14.0.4612.1000.

 

The following table shows the schema elements that have changed.

Schema element	Comment
capabilities	Modified after OSC build 14.0.4612.1000; removed the activitiesTTL, friendsTTL, addFriendOrColleague, and provideUserSMTPAddress elements. Modified after OSC build 14.0.4730.1003; added the contactSyncRestartInterval element.
friends	Modified after OSC build 14.0.4730.1003; added the emailAddress2 and emailAddress3 elements.

Interface Reference

An OSC provider must implement all of the following interfaces: ISocialProvider, ISocialSession, ISocialProfile, and ISocialPerson.

ISocialProvider

interface ISocialProvider : IUnknown

Represents an instance of an OSC provider.

The following table shows the members that are available on the ISocialProvider interface.

Name	Member type
DefaultSiteUrls	Property
GetAutoConfiguredSession	Method
GetCapabilities	Method
GetSession	Method
GetStatusSettings	Method
Load	Method
SocialNetworkGuid	Property
SocialNetworkIcon	Property
SocialNetworkName	Property
Version	Property

DefaultSiteUrls

Syntax	[propget] HRESULT _stdcall DefaultSiteUrls([out, retval] SAFEARRAY(BSTR)* siteUrls);
Description	Returns an array of strings that specify site URLs for the provider. Read-only.
Remarks	One provider can support multiple site URLs. The OSC sets the SiteUrl property to inform the provider of the selected site URL. The first element of the array is used as the default site URL in OSC version 1.0. A provider can return additional elements in the site URL array, but these are not used in OSC version 1.0.

GetAutoConfiguredSession

Syntax	HRESULT _stdcall GetAutoConfiguredSession([out, retval] ISocialSession** session);
Description	Gets an automatically configured ISocialSession interface.
Remarks	The returned ISocialSession interface is automatically logged on to the network, based on a method that is specific to the provider. The provider should raise the OSC_E_NOT_IMPLEMENTED error if the social network does not support automatic configuration.

GetCapabilities

Syntax	HRESULT _stdcall GetCapabilities([out, retval] BSTR* result);
Description	Gets a string that describes provider capabilities.
Remarks	The returned XML string must comply with the schema definition for capabilities, as defined in the schema for OSC provider extensibility. The provider must return a capabilities string to enable subsequent calls from the OSC to the provider to operate correctly.

GetSession

Syntax	HRESULT _stdcall GetSession([out, retval] ISocialSession** session);
Description	Gets an ISocialSession interface.
Remarks	The OSC uses the ISocialSession interface to log on to the social network.

GetStatusSettings

Syntax	HRESULT _stdcall GetStatusSettings([out] BSTR* statusDefault, [out] int* maxStatusLength);
Description	Gets status settings.
Remarks	Not yet implemented in OSC version 1.0.

Load

Syntax	HRESULT _stdcall Load([in] BSTR socialProviderInterfaceVersion, [in] BSTR languageTag);
Description	Initializes the OSC provider.
Remarks	The OSC passes two parameters in the Load method. The first parameter, socialProviderInterfaceVersion, represents the version of the OSC provider interfaces expected by the OSC. The version format is X.xxxx, where X is the major version and xxxx is the minor version of the OSC. The second parameter, languageTag, is the Internet Engineering Task Force (IETF) language tag defined by RFC 4646 and RFC 4647 that represents the current Outlook user interface language.

SocialNetworkGuid

Syntax	[propget] HRESULT _stdcall SocialNetworkGuid([out, retval] GUID* guid);
Description	Returns a GUID that represents a unique identifier for the social network. Read-only.
Remarks	The GUID must be immutable and must not change even if the provider version changes.

SocialNetworkIcon

Syntax	[propget] HRESULT _stdcall SocialNetworkIcon([out, retval] SAFEARRAY(unsigned char)* networkIcon);
Description	Returns an array of bytes that represents the icon for the social network. Read-only.
Remarks	The supported picture resources are .bmp, .jpeg, and .png formats.

SocialNetworkName

Syntax	[propget] HRESULT _stdcall SocialNetworkName([out, retval] BSTR* networkName);
Description	Returns a string that represents the social network name. Read-only.
Remarks	Providers should localize the social network name.

Version

Syntax	[propget] HRESULT _stdcall Version([out, retval] BSTR* Version);
Description	Returns a string that represents the version number of the provider for this social network. Read-only.
Remarks	The version string should use the MajorVersion.MinorVersion format (for example, 1.4730).

ISocialSession

interface ISocialSession : IUnknown

Represents a connection to a social network site.

The following table shows the members that are available on the ISocialSession interface.

Name	Member type
FindPerson	Method
FollowPerson	Method
GetActivities	Method
GetLoggedOnUser	Method
GetLogonUrl	Method
GetNetworkIdentifier	Method
GetPerson	Method
LoggedOnUserID	Property
LoggedOnUserName	Property
Logon	Method
LogonWeb	Method
SiteUrl	Property
UnFollowPerson	Method

FindPerson

Syntax	HRESULT _stdcall FindPerson([in] BSTR userId, [out, retval] BSTR* result);
Description	Gets a string that represents a collection of people who match the userID parameter.
Remarks	userID can be a user ID, SMTP address, or display name. If only one person matches the FindPerson request, this method returns only that person's information in the XML specified for friends (in the result parameter). The returned XML string must comply with the schema definition for friends, as defined in the schema for OSC provider extensibility.

 

FollowPerson

Syntax	HRESULT _stdcall FollowPerson([in] BSTR emailAddress);
Description	Follows the person identified by the emailAddress parameter on the social network.
Remarks	The emailAddress parameter must be a valid SMTP address. If the provider has set the followPerson method as true in capabilities, and the argument for emailAddress does not match a user on the network, the provider must raise the OSC_E_NOT_FOUND error. If the provider has set followPerson as false in capabilities, the provider should raise the OSC_E_FAIL error.

 

GetActivities

Syntax	HRESULT GetActivities([in] SAFEARRAY(BSTR) emailAddresses, [in] DATE startTime, [out, retval] BSTR *activities);
Description	Gets a string that represents a collection of activities for the person specified by the emailAddresses parameter.
Remarks	The returned XML string must comply with the schema definition for activityFeed. The emailAddresses parameter is an array of valid SMTP addresses for a user on the network. The user does not have to be a friend or colleague of the user represented by the LoggedOnUserName property. The startTime parameter is a Date value in Coordinated Universal Time (UTC). Local time values must be converted to UTC Date values. Activities that the GetActivities method returns must have a creation time value that is greater than startTime and less than or equal to Now. If no changes have occurred between startTime and Now, the provider must raise an OSC_E_NO_CHANGES error.

 

GetLoggedOnUser

Syntax	HRESULT _stdcall GetLoggedOnUser([out, retval] ISocialProfile** result);
Description	Gets an ISocialProfile interface that represents the logged-on user.

GetLogonUrl

Syntax	HRESULT _stdcall GetLogonUrl([out, retval] BSTR* url);
Description	Gets a string that represents a URL used for presenting a browser-based form to the user during Web authentication.
Remarks	After the form is presented to the user, the LogonWeb method is called with an empty string for the connectIn parameter.

GetNetworkIdentifier

Syntax	HRESULT _stdcall GetNetworkIdentifier([out, retval] BSTR* networkIdentifier);
Description	Gets a string that represents a unique social network identifier for a given social network connection. A unique network identifier is a string that identifies the provider social network. This method can also return E_NOTIMPL.

GetPerson

Syntax	HRESULT _stdcall GetPerson([in] BSTR userId, [out, retval] ISocialPerson** result);
Description	Gets an ISocialPerson interface based on the userID parameter.
Remarks	userID must be a user ID or SMTP address.

LoggedOnUserID

Syntax	[propget] HRESULT _stdcall LoggedOnUserID([out, retval] BSTR* result);
Description	Returns a string that represents the ID of the user who is currently logged on. Read-only.

LoggedOnUserName

Syntax	[propget] HRESULT _stdcall LoggedOnUserName([out, retval] BSTR* result);
Description	Returns a string that represents the user name that is used when logging on. Read-only.

Logon

Syntax	HRESULT _stdcall Logon([in] BSTR username, [in] BSTR password);
Description	Logs on to the social network site by using the specified user name and password.

LogonWeb

Syntax	HRESULT _stdcall LogonWeb([in] BSTR connectIn, [out] BSTR* connectOut);
Description	Logs on to the social network site by using forms-based authentication.
Remarks	The OSC calls the LogonWeb method only if the provider indicates that it supports forms-based authentication. The provider indicates that it requires form-based authentication by setting useLogonWebAuth as true in the XML for capabilities. If the provider sets useLogonWebAuth as false, the OSC uses basic authentication and calls the Logon method. Logging on to a social network site by using forms-based authentication involves calling the LogonWeb and GetLogonUrl methods in a specific order: The OSC calls LogonWeb the first time, passing 空 to the connectIn parameter. The provider raises the OSC_E_AUTH_ERROR error to the OSC. The OSC next calls ISocialSession::GetLogonUrl. The provider returns the appropriate logon URL in the GetLogonUrl method. The OSC uses the URL returned by GetLogonUrl to display the forms-based logon page. The OSC then calls LogonWeb a second time, passing 空 in the connectIn parameter. If authentication succeeds, the provider returns the connectOut parameter to the OSC. If authentication fails, the provider raises the OSC_E_AUTH_ERROR error to the OSC. The connectOut parameter is an opaque string to the OSC, and is passed to the connectIn parameter on subsequent attempts by the OSC to log on to the social network. The provider should place any credentials in the connectOut string that the provider wants the OSC to store across connections. connectOut is not interpreted by the OSC, and the string is encrypted for security when it is stored in the Windows registry.

SiteUrl

Syntax	[propput] HRESULT _stdcall siteUrl([in] BSTR rhs);
Description	Sets the social network site URL that the provider will use. Write-only.

UnFollowPerson

Syntax	HRESULT _stdcall UnFollowPerson([in] BSTR userID);
Description	Removes the person identified by the userID parameter from the follow action on the social network.
Remarks	The userID parameter must be a valid user ID for the person on the social network. If the provider has set doNotFollowPerson as true in capabilities, the provider must raise the OSC_E_NOT_FOUND error in the case that the user ID passed in does not match a user on the network. If the provider has set doNotFollowPerson as false in capabilities, the provider should raise the OSC_E_FAIL error.

 

ISocialProfile

interface ISocialProfile : IUnknown

Represents the logged-on user.

The following table shows the members that are available on the ISocialProfile interface.

Name	Member type
AreFriendsOrColleagues	Method
GetActivitiesOfFriendsAndColleagues	Method
SetStatus	Method

AreFriendsOrColleagues

Syntax	HRESULT _stdcall AreFriendsOrColleagues(SAFEARRAY(BSTR) userIds, [out, retval] SAFEARRAY(VARIANT_BOOL)* results);
Description	Determines whether the specified users are friends or colleagues.
Remarks	For each user represented in the input array of the userIds parameter, this method sets the corresponding element in the output array of the results parameter. true indicates that the user is a friend or colleague, and false indicates that the user is neither a friend nor a colleague. Not implemented in OSC version 1.0.

GetActivitiesOfFriendsAndColleagues

Syntax	HRESULT _stdcall GetActivitiesOfFriendsAndColleagues([in] DATE startTime, [out, retval] BSTR* activitiesCollection);
Description	Gets a string that represents a collection of activities for friends and colleagues.
Remarks	The returned XML string must comply with the schema definition for activityFeed, as defined in the schema for OSC provider extensibility. The startTime parameter is a Date value in Coordinated Universal Time (UTC). Local time values must be converted to UTC Date values. Activities that the GetActivitiesOfFriendsAndColleagues method returns have a creation time value that is greater than startTime and less than or equal to Now. If no changes have occurred between startTime and Now, the provider must raise the OSC_E_NO_CHANGES error.

SetStatus

Syntax	HRESULT _stdcall SetStatus(BSTR status);
Description	Sets the status for the logged-on user.
Remarks	Not implemented in OSC version 1.0.

ISocialPerson

interface ISocialPerson : IUnknown

Represents a person on the social network.

The following table shows the members that are available on the ISocialPerson interface.

Name	Member type
GetActivities	Method
GetDetails	Method
GetFriendsAndColleagues	Method
GetFriendsAndColleaguesIDs	Method
GetPicture	Method
GetStatus	Method

GetActivities

Syntax	HRESULT _stdcall GetActivities([in] DATE startTime, [out, retval] BSTR* activities);
Description	Gets a string that represents a collection of activities for the person.
Remarks	The returned XML string must comply with the schema definition for activityFeed, as defined in the schema for OSC provider extensibility. The startTime parameter is a Date value in UTC. Local time values must be converted to UTC Date values. Activities that the GetActivities method returns have a creation time value that is greater than startTime and less than or equal to Now. If no changes have occurred between startTime and Now, the provider must raise the OSC_E_NO_CHANGES error.

GetDetails

Syntax	HRESULT _stdcall GetDetails([out, retval] BSTR* details);
Description	Gets a string that represents details for the person, such as firstName and lastName.
Remarks	The returned XML string must comply with the schema definition for person, as defined in the schema for OSC provider extensibility.

GetFriendsAndColleagues

Syntax	HRESULT _stdcall GetFriendsAndColleagues([out, retval] BSTR* personsCollection);
Description	Gets a string that represents a collection of people.
Remarks	The returned XML string must comply with the schema definition for friends, as defined in the schema for OSC provider extensibility.

GetFriendsAndColleaguesIDs

Syntax	HRESULT _stdcall GetFriendsAndColleaguesIDs([out, retval] SAFEARRAY(BSTR)* friendsIDs);
Description	Gets an array of strings that contain the user IDs or SMTP addresses for friends and colleagues.

GetPicture

Syntax	HRESULT _stdcall GetPicture([out, retval] SAFEARRAY(unsigned char)* picture);
Description	Gets an array of bytes that contains the picture resource for the person.
Remarks	Supported picture resources are in .bmp, .jpeg, or .png format.

GetStatus

Syntax	HRESULT _stdcall GetStatus([out, retval] BSTR* status);
Description	Gets a string that represents the status for the person.
Remarks	Not implemented in OSC version 1.0.

XML Schema Reference

This section contains detailed conceptual descriptions for Capabilities and Activities XML Elements, XML Examples, and the complete XML Schema for OSC provider extensibility.

Capabilities and Activities XML Elements

This section describes the XML elements that support capabilities and activities. These are the XML elements that an OSC provider returns to the OSC.

Capabilities XML Elements

Capabilities XML is critical because it signals the functionality supported by the provider to the OSC. The default value of each capabilities element is false. If the element is not specified in the capabilities XML returned by the ISocialProvider::GetCapabilities method, the value of the element is equal to false. The following table describes each element of the capabilities schema.

Element	Description
getFriends	Indicates whether the provider supports the ISocialPerson::GetFriendsAndColleagues method call. If the provider sets getFriends as true, the OSC uses the value of cacheFriends to determine whether the social network site allows storing friends as Outlook contact items. If the provider sets getFriends as false, the OSC ignores the value of cacheFriends and operates as if cacheFriends equals false.
cacheFriends	Indicates whether the provider allows storing friends as Outlook contact items. If the provider sets cacheFriends as true, the OSC creates a network-specific Contacts folder in the user’s default store for friend contacts. The name of the network-specific Contacts folder is the value of the ISocialProvider::SocialNetworkName property. If the provider sets cacheFriends as false, the OSC ignores followPerson and doNotFollowPerson settings and does not create a network-specific Contacts folder for friend contacts.
followPerson	Indicates whether the provider supports the ISocialPerson::FollowPerson method call. If the provider sets followPerson as true, the OSC displays a network badge in the People Pane for people that the user is following, and enables the on <NetworkName> command on the Add (+) menu in the People Pane. If the provider sets followPerson as false, the network badge is not displayed and the on <NetworkName> command is hidden.
doNotFollowPerson	Indicates whether the provider supports the ISocialSession::UnFollowPerson method call.
getActivities	Indicates whether the provider supports the ISocialSession::GetActivities and ISocialPerson::GetActivities method calls. If the provider sets getActivities as true, the OSC uses the value of cacheActivities or dynamicActivitiesLookup to determine whether the social network site allows storing activities as Outlook RSS items or as in-memory activities. If the provider sets getActivities as false, the OSC ignores the value of cacheActivities and operates as if cacheActivities equals false and dynamicActivitiesLookup equals false.
cacheActivities	Indicates whether the provider allows storing activities as Outlook RSS items. If the provider sets getActivities as false, the OSC ignores the value of cacheActivities. If the provider sets cacheActivities as true, the OSC will create RSS items in a hidden folder in the user’s default store. If the provider sets cacheActivities as false and sets dynamicActivitesLookup as true, the OSC caches activities in memory. The activities memory cache is refreshed on a 30-minute interval.
dynamicActivitiesLookup	Indicates whether the provider supports the ISocialSession::GetActivities method call for dynamic lookup of activities. If the provider sets dynamicActivitiesLookup as true and getActivities as true, the OSC will call ISocialSession::GetActivities every time the People Pane is refreshed. The People Pane is refreshed when the user changes the selected item in the Outlook explorer window or opens an Outlook inspector window. Dynamic activities lookup ensures that the user will always see the latest activities in the People Pane, but it will increase the number of calls from the provider to the social network. If the provider sets dynamicActivitiesLookup as false, the OSC does not call ISocialSession::GetActivities for people displayed in the People Pane.
displayUrl	Indicates whether the OSC should display the URL Address text box for the social network in the account configuration dialog box.
useLogonWebAuth	Indicates whether the OSC should use forms-based authentication and the ISocialSession::LogonWeb method. If the provider sets useLogonWebAuth as false, the OSC uses basic authentication and calls the ISocialSession::Logon method. If the provider sets useLogonWebAuth as true, the OSC uses forms-based authentication and calls ISocialSession::LogonWeb.
hideHyperlinks	Indicates whether the OSC should hide the Click here to create an account and Forgot your password? hyperlinks in the account configuration dialog box. This setting is ignored in OSC version 1.0, and the hyperlinks are always hidden.
supportsAutoConfigure	Indicates whether the OSC should call the GetAutoConfiguredSession function on the ISocialProvider interface to attempt automatic configuration of the network for the user.
contactSyncRestartInterval	Determines the minimum time, in minutes, between network contact synchronization attempts, regardless of success. The default contact synchronization interval is 30 minutes, unless the default is overridden by the ContactSyncRestartInterval key under HKEY_CURRENT_USER\Software\Microsoft\Office\Outlook\SocialConnector. If the provider sets contactSyncRestartInterval, the provider value will override the default interval of 30 minutes or the registry key value.

Depending on the capabilities XML returned by the provider in the ISocialProvider::GetCapabilities method, the account configuration dialog box changes. For example, Figure 4 shows the account configuration dialog box for the TestProvider sample.

Figure 4. TestProvider sample in the account configuration dialog box

Activities XML Elements

Your provider must return the correct activities XML to ensure that user activities appear in the People Pane. The following guidelines are designed to help you understand the logic used by the OSC to display activities in the People Pane.

Cached Activities

The following guidelines apply to cached activities:

• If you cache activities by setting cacheActivites to true, activity items are stored as Outlook RSS items in a hidden folder in the Outlook user’s default delivery store. The name of the hidden folder is News Feed.

• The OSC will call the ISocialProfile::GetActivitiesOfFriendsAndColleagues method to create activities in the News Feed folder.

• To ensure that cached activities appear correctly in the People Pane, you must set one or more of the following elements:

  • The ownerID element in the activityDetails element is required, and is an opaque string that identifies the user on the network.

  • If only the ownerID element is specified, and either the nameHint or emailAddress element in the publisherVariable node of the templateVariables element is not specified, the OSC calls the ISocialSession::GetPerson method and then the ISocialPerson::GetDetails method to resolve the ownerID.

  • When the OSC calls ISocialPerson::GetDetails, the provider must return person XML that specifies fullName and emailAddress elements.

  • If the OSC has both nameHint and emailAddress elements, the OSC does not call ISocialSession::GetPerson and ISocialPerson::GetDetails.

  • If the OSC has only the nameHint or emailAddress element, the OSC calls ISocialSession::GetPerson and ISocialPerson::GetDetails.

  • The nameHint element is optional; the OSC uses it to match the nameHint element with the display name of the user displayed in the People Pane.

  • The emailAddress element is optional; the OSC uses it to match the emailAddress element with the SMTP address of the user displayed in the People Pane.

On-Demand Activities

The following guidelines apply to on-demand activities:

• If the activities for the user do not appear in the People Pane because the user’s primary SMTP address is not available, consider enabling on-demand activities by setting dynamicActivitiesLookup to true in your provider capabilities XML.

• On-demand activity synchronization will not cache activities in the hidden News Feed folder, but it will cause the OSC to call the ISocialSession::GetActivities method when the activity feed in the People Pane needs to be loaded. On-demand activity synchronization does not require matching the SMTP address of the user displayed in the People Pane against the ownerID, nameHint, or emailAddress element.

Creating Activity Feed Items

Figure 5 shows the three pieces of information for each activity feed item that the social network provider controls: the icon, title, and extra data for the feed item.

Figure 5. Components of an activity feed item in the OSC

提示

In OSC version 1.0, the icon displayed in the activity feed is always the same as the provider icon returned by the ISocialProvider::SocialNetworkIcon property.

To create an activity feed item, you must conform to the OSC provider extensibility XML schema. Figure 6 shows the activity feed schema.

Figure 6. Activity XML structure

The two most important parts of this schema are the ActivityDetails and ActivityTemplateContainer elements. The ActivityDetails elements store the specific information for that activity feed item, such as the person’s name or the URLs for the pictures they uploaded. The ActivityTemplateContainer elements store the format or layout for feed items. Templates can be reused for multiple feed items.

The following sections further describe the ActivityDetails element, the ActivityTemplateContainer element, template tokens, and template variables.

ActivityDetails Element

The ActivityDetails element stores the raw data for a single feed item. Each activity feed item must have its own ActivityDetails element. Data in the ActivityDetails element is referenced in activity templates by using Name elements. Every piece of data in the ActivityDetails element must have a Name element.

The following table describes the six elements that the ActivityDetails element requires.

Element	Description
ownerID	Specifies the ID of the user who generated this feed item.
objectID	Specifies a unique feed item string, which is used for detecting duplicate feed items.
applicationId	Specifies one of two unique IDs that are used to match the feed item with its template. If you have multiple applications or other groupings, this can be used as a first-tier template organizer.
templateId	Specifies the second unique ID that is used to match the feed item with its template. This can be used as a second-tier template organizer.
publishDate	Specifies the date and time that the feed item was published.
templateVariables	Specifies the data to be used in the tokens for the feed item template.

ActivityTemplateContainer Element

Templates allow you to format your feed items and reuse XML that specifies a layout. IDs are used to match a feed item to a template, and then the layout data is stored in the activityTemplate element. To reference data that is pulled from the individual feed item, tokens are used as placeholders for information such as people, links, and text.

The following table describes the three elements that the activityTemplateContainer element requires.

Element	Description
applicationID	Specifies one of two unique IDs that are used to match the feed item with its template. If you have multiple applications or other groupings, this can be used as a first-tier template organizer.
templateID	Specifies the second unique ID that is used to match the feed item with its template. This can be used as a second-tier template organizer.
activityTemplate	Specifies the layout of the template, including values for the icon, title, and data elements.

The following table describes the three parts of the layout for a template, represented by their corresponding XML elements.

Element	Description
icon	Contains only a link token, which references the URL for the icon for that feed item.
title	Contains the required information for the feed item.
data	Contains the additional information for the feed item such as pictures, text, or links.

Template Tokens

Tokens are used in templates to reference data that is stored in each feed item. Tokens must specify a type and a name to reference the data stored in the feed item, as follows:

{Token type: Token name}

The following table shows the supported tokens.

Token	Description
link	Specifies a link object.
publisher	Specifies the person, group, or thing that created the feed item.
text	Specifies a block of text.
entity	Specifies a person, group, or thing.
picture	Specifies a picture.
list	Specifies a group of pictures to display pictures in the activity feed.

Template Variables

Template variables are used to specify the data to be referenced for a token in a template. The following table shows the supported template variable types, each represented by the corresponding enumeration value for the type.

Type of template variable	Description
linkVariable	Specifies a link.
publisherVariable	Specifies the publisher of the feed item.
textVariable	Specifies a block of text.
entityVariable	Specifies a person, group, or thing.
pictureVariable	Specifies a picture.
listVariable	Specifies a group of objects.

Each template variable type has required elements to specify the data about that variable. Template variables are specified as follows:

<templateVariable type="variable type">

Template variables that are contained within a list variable are specified as follows:

<simpleTemplateVariable type="variable type of either text, link, or picture">

The following table shows the required and optional elements supported for template variables of each type.

Type of template variable	Elements	Description
linkVariable	name	Specifies the name of the variable. Required.
	value	Specifies the URL for this link. Required.
	text	Specifies the link text to display instead of the URL itself. Optional.
publisherVariable	name	Specifies the name of the variable. Required.
	id	Specifies the unique ID of the user. Required.
	nameHint	Specifies the name to be displayed in the feed item. Optional.
	profileUrl	Specifies the URL of the person’s profile that will be used as the hyperlink for the person’s name in the feed item, if the person’s name is present. Optional.
	emailAddress	Specifies the e-mail address that is used to update this person’s contact information in Outlook. Optional.
textVariable	name	Specifies the name of the variable. Required.
	value	Specifies the text to display. Optional.
entityVariable	name	Specifies the name of the variable. Required.
	id	Specifies the unique ID of the user. Required.
	nameHint	Specifies the name to be displayed in the feed item. Optional.
	profileUrl	Specifies the URL of the person’s profile that will be used as the hyperlink for the person’s name in the feed item, if the person’s name is present. Optional.
	emailAddress	Specifies the e-mail address that is used to update this person’s contact information in Outlook. Optional.
pictureVariable	name	Specifies the name of the variable. Required.
	value	Specifies the URL for the picture. Required.
	altText	Specifies the alternate text to display for accessibility and when the user moves the mouse pointer over the picture. Optional.
	href	Specifies the hyperlink to use when the user clicks the picture, if the desired target is not the picture URL specified by the value element. Optional.
listVariable	name	Specifies the name of the variable. Required.
	listItems	Specifies a container for items in the list. Required. The listVariable type is further explained immediately following this table.

A variable of the listVariable type is a container for objects. In OSC version 1.0, the only lists that are supported are comma-delimited lists and pictures. Lists can contain either five pictures or five items.

You can create comma-delimited lists that have link or text tokens. The activity feed will then localize the list according to the Windows system locale.

To correctly parse and display pictures that are included with a feed item, the pictures must be included in a list. All pictures are resized to be 52 pixels high. The width of the picture is not resized.

XML Examples

This section contains XML examples that use the capabilities, activityFeed, and friends XML elements, complying with the XML schema for OSC provider extensibility.

Capabilities XML Example

The following example shows the provider capabilities returned by the ISocialProvider::GetCapabilities method.

<?xml version="1.0" encoding="utf-8" ?>
<capabilities xmlns="https://schemas.microsoft.com/office/outlook/socialprovider.xsd">
  <getFriends>true</getFriends>
  <cacheFriends>true</cacheFriends>
  <followPerson>true</followPerson>
  <doNotFollowPerson>false</doNotFollowPerson>
  <getActivities>true</getActivities>
  <cacheActivities>true</cacheActivities>
  <dynamicActivitiesLookup>false</dynamicActivitiesLookup>
  <displayUrl>false</displayUrl>
  <useLogonWebAuth>false</useLogonWebAuth>
  <hideHyperlinks>true</hideHyperlinks>
  <supportsAutoConfigure>false</supportsAutoConfigure>
</capabilities>

ActivityFeed XML Example

The following example shows an activity feed returned by the ISocialPerson::GetActivitiesOfFriendsAndColleagues method.

<?xml version="1.0" encoding="utf-8"?>
<activityFeed xmlns="https://schemas.microsoft.com/office/outlook/socialprovider.xsd">
  <network>Contoso</network>
  <activities>
    <activityDetails>
      <ownerID>4667647</ownerID>
      <objectID>9d2b5e6360894a21d56d7d0b5969d23cf4034a31</objectID>
      <applicationID>2</applicationID>
      <templateID>1</templateID>
      <publishDate>2010-01-28T17:19:57</publishDate>
      <templateVariables>
        <templateVariable type="publisherVariable">
          <name>Publisher</name>
          <id>4667647</id>
          <nameHint>Melissa MacBeth</nameHint>
          <profileUrl>https://www.contoso.com/</profileUrl>
        </templateVariable>
        <templateVariable type="listVariable">
          <name>ProfilePhoto</name>
          <listItems>
            <simpleTemplateVariable type="pictureVariable">
              <name>Photo</name>
              <value>https://office.microsoft.com/global/images/default.aspx?assetid=ZA103873861033</value>
              <altText>Melissa MacBeth</altText>
              <href>https://office.microsoft.com/global/images/default.aspx?assetid=ZA103873861033</href>
            </simpleTemplateVariable>
          </listItems>
        </templateVariable>
      </templateVariables>
    </activityDetails>
    <activityDetails>
      <ownerID>5015012</ownerID>
      <objectID>9d2b5e6360894a21d56d7d0b5969d23cf4034a32</objectID>
      <applicationID>2</applicationID>
      <templateID>1</templateID>
      <publishDate>2010-01-30T17:19:57</publishDate>
      <templateVariables>
        <templateVariable type="publisherVariable">
          <name>Publisher</name>
          <id>5015012</id>
          <nameHint>Michael Affronti</nameHint>
          <profileUrl>https://www.contoso.com/</profileUrl>
        </templateVariable>
        <templateVariable type="listVariable">
          <name>ProfilePhoto</name>
          <listItems>
            <simpleTemplateVariable type="pictureVariable">
              <name>Photo</name>
              <value>https://office.microsoft.com/global/images/default.aspx?assetid=ZA103895491033</value>
              <altText>Michael Affronti</altText>
              <href>https://office.microsoft.com/global/images/default.aspx?assetid=ZA103895491033</href>
            </simpleTemplateVariable>
          </listItems>
        </templateVariable>
      </templateVariables>
    </activityDetails>
  </activities>
  <templates>
    <activityTemplateContainer>
      <applicationID>2</applicationID>
      <templateID>1</templateID>
      <activityTemplate>
        <type>Photo</type>
        <title>{publisher:Publisher} has a new profile photo: </title>
        <data>{list:ProfilePhoto({picture:Photo})}</data>
        <icon>https://www.microsoft.com/about/images/rss_button.gif</icon>
      </activityTemplate>
    </activityTemplateContainer>
  </templates>
</activityFeed>

Friends XML Example

The following example is a brief friends list returned by the ISocialSession::GetFriendsAndColleagues method.

<?xml version="1.0" encoding="utf-8"?>
<friends xmlns="https://schemas.microsoft.com/office/outlook/socialprovider.xsd">
  <person>
    <userID>4667647</userID>
    <firstName>Melissa</firstName>
    <lastName>MacBeth</lastName>
    <nickname></nickname>
    <fileAs>MacBeth, Melissa (Contoso Ltd.)</fileAs>
    <company>Contoso Ltd.</company>
    <title>Product Manager</title>
    <anniversary>2005-05-17</anniversary>
    <birthday>1979-08-09</birthday>
    <emailAddress>melissa@contoso.com</emailAddress>
    <emailAddress2>melissa@fabrikam.com</emailAddress2>
    <emailAddress3>melissa@adventureworks.com</emailAddress3>
    <webProfilePage>https://contoso.com/melissa</webProfilePage>
    <phone>800-555-1212</phone>
    <cell>888-555-1212</cell>
    <workPhone>425-555-1212</workPhone>
    <creationTime>2010-01-08T08:30:20-08:00</creationTime>
    <lastModificationTime>2010-01-08T11:40:14-08:00</lastModificationTime>
    <expirationTime>2010-01-09T11:40:14-08:00</expirationTime>
    <gender>female</gender>
  </person>
  <person>
    <userID>5015012</userID>
    <firstName>Michael</firstName>
    <lastName>Affronti</lastName>
    <nickname>Mr. Social</nickname>
    <fileAs>Affronti, Michael (Contoso Ltd.)</fileAs>
    <company>Contoso Ltd.</company>
    <title>Sales Director</title>
    <anniversary>2009-06-21</anniversary>
    <birthday>1980-09-10</birthday>
    <emailAddress>michael@contoso.com</emailAddress>
    <emailAddress2>michael@fabrikam.com</emailAddress2>
    <emailAddress3>michael@adventureworks.com</emailAddress3>
    <webProfilePage>https://contoso.com/michael</webProfilePage>
    <phone>800-555-1212</phone>
    <cell>888-555-1212</cell>
    <workPhone>425-555-1212</workPhone>
    <creationTime>2010-01-08T08:30:20-08:00</creationTime>
    <lastModificationTime>2010-01-08T11:40:14-08:00</lastModificationTime>
    <expirationTime>2010-01-09T11:40:14-08:00</expirationTime>
    <gender>male</gender>
  </person>
</friends>

XML Schema

All XML returned from an OSC provider's interface methods must comply with the following OSC provider extensibility XML schema. The schema is reproduced here in its entirety. The schema definition file, OutlookSocialProvider.xsd, is also provided in the sample provider named TestProvider and the provider templates that accompany this article. For more information, see Outlook Sample: Outlook Social Connector Provider.

<?xml version="1.0" encoding="utf-8"?>
<!--
    XML Schema for Microsoft Outlook Social Connector Provider Extensibility 
    Copyright (c) 2009 Microsoft Corporation
    All Rights Reserved
-->
<xs:schema
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    targetNamespace="https://schemas.microsoft.com/office/outlook/socialprovider.xsd"
    xmlns="https://schemas.microsoft.com/office/outlook/socialprovider.xsd"
    elementFormDefault="qualified">

  <!-- Root element for the activity feed -->
  <xs:element name="activityFeed" type="activityFeedType" />

  <!-- Type definition for .\activityFeed  -->
  <xs:complexType name="activityFeedType">
    <xs:sequence>
      <!-- Network where the activity feed items originated (required) -->
      <xs:element name="network"    type="xs:string"  minOccurs="1" maxOccurs="1" />

      <!-- Container for activity feed items (required) -->
      <xs:element name="activities" type="activitiesType" minOccurs="1" maxOccurs="1" />

      <!-- Container for feed item display templates (required) -->
      <xs:element name="templates"  type="templatesType"  minOccurs="1" maxOccurs="1" />
    </xs:sequence>
  </xs:complexType>

  <!-- Type definition for .\activityFeed\activities -->
  <xs:complexType name="activitiesType">
    <xs:sequence>
      <xs:element name="activityDetails" type="activityDetailsType" minOccurs="0" maxOccurs="unbounded" />
    </xs:sequence>
  </xs:complexType>

  <!-- Type definition for .\activityFeed\activities\activityDetails element -->
  <xs:complexType name="activityDetailsType">
    <xs:sequence>
      <!-- Used to denote the user id of the user generating this activity (required) -->
      <xs:element name="ownerID" type="xs:string" minOccurs="1" maxOccurs="1" />

      <!-- Used to denote a unique string idenfitifying this activity. Used for duplicate detection (required) -->
      <xs:element name="objectID" type="xs:string" minOccurs="1" maxOccurs="1" />

      <!-- Used to denote an activity feed update template, such as a blog post or profile change (required) -->
      <xs:element name="applicationID" type="xs:unsignedLong" minOccurs="1" maxOccurs="1" />

      <!-- Used to denote the template type, such as multiple profile change types (required) -->
      <xs:element name="templateID" type="xs:unsignedLong" minOccurs="1" maxOccurs="1" />

      <!-- Date on which this feed item was published (required) -->
      <xs:element name="publishDate" type="xs:dateTime" minOccurs="1" maxOccurs="1" />

      <!-- Used for denoting a status, photo or document related activity feed item (optional) -->
      <xs:element name="type" type="activityTemplateTypeRestrictionType" minOccurs="0" maxOccurs="1" />
  
      <!-- Variables included with the feed item (required) -->
      <xs:element name="templateVariables" type="templateVariablesType" minOccurs="1" maxOccurs="1" />
    </xs:sequence>
  </xs:complexType>

  <!-- Type definition for .\activityFeed\activities\activityDetails\templateVariables element -->
  <xs:complexType name="templateVariablesType">
    <xs:sequence>
      <xs:element name="templateVariable" type="templateVariableType" minOccurs="0" maxOccurs="unbounded" />
    </xs:sequence>
  </xs:complexType>

  <!-- Type definition for .\activityFeed\activities\activityDetails\templateVariables\templateVariable element -->
  <xs:complexType name="templateVariableType">
    <xs:sequence>
      <!-- All activityTemplateType nodes require a Name element to identify the node
           (required for all nodes)  -->
      <xs:element name="name" type="xs:string" minOccurs="1" maxOccurs="1" />

      <!-- Used for Publisher and Entity nodes, the Id node value is a unique id of the person or entity
           (required for the Publisher and Entity nodes)  -->
      <xs:element name="id" type="xs:string" minOccurs="0" maxOccurs="1" />

      <!-- Used for Publisher and Entity nodes, the nameHint node value is the name to be displayed in
           the formatted activity  -->
      <xs:element name="nameHint" type="xs:string" minOccurs="0" maxOccurs="1" />

      <!-- Used for Publisher and Entity nodes, the emailAddress node value is the SMTP address associated
           with the person being mentioned in the feed  -->
      <xs:element name="emailAddress" type="xs:string" minOccurs="0" maxOccurs="1" />

      <!-- Used for Publisher and Entity nodes, the profileUrl node value is the URI which points to the
           user's profile page   -->
      <xs:element name="profileUrl" type="xs:string" minOccurs="0" maxOccurs="1" />

      <!-- Used for Link nodes to denote the text the link should display
           (optional for the Link node, if not specified the URI will be used as the display text)  -->
      <xs:element name="text" type="xs:string" minOccurs="0" maxOccurs="1" />

      <!-- Used Link and Picture nodes to denote the URI of the picture location or desired link
           (required for the Link and Picture nodes)  -->
      <xs:element name="value" type="xs:anyURI" minOccurs="0" maxOccurs="1" />

      <!-- Used for the Picture node to denote alternate text for the picture and/or a link where
           the user is taken when they click the picture
           (both elements are optional for the Picture node) -->
      <xs:element name="altText" type="xs:string" minOccurs="0" maxOccurs="1" />
      <xs:element name="href" type="xs:anyURI" minOccurs="0" maxOccurs="1" />

      <!-- Used for the List node as a container of the simpleTemplateVariables, which contain Picture nodes
           (required for the List node)  -->
      <xs:element name="listItems" type="templateListItemsType" minOccurs="0" maxOccurs="1" />

    </xs:sequence>
    <xs:attribute name="type" type="templateTypeRestrictionType" use="required" />
  </xs:complexType>

  <xs:simpleType name="templateTypeRestrictionType">
    <xs:restriction base="xs:string">
      <!-- Denotes the publisher of the feed item -->
      <xs:enumeration value="publisherVariable" />

      <!-- Entities which are not the publisher included with the feed item -->
      <xs:enumeration value="entityVariable" />

      <!-- Links included with the feed item -->
      <xs:enumeration value="linkVariable" />

      <!-- Text included with the feed item -->
      <xs:enumeration value="textVariable" />

      <!-- Picture variables included in ListVariableItem -->
      <xs:enumeration value="pictureVariable" />

      <!-- List to hold pictures included with the feed item
           A list holds a Name node and ListItems node  -->
      <xs:enumeration value="listVariable" />
    </xs:restriction>
  </xs:simpleType>

  <xs:complexType name="templateListItemsType">
    <xs:sequence>
      <!-- Lists are used to contain a series of pictures, defined as a simpleTemplateVariable which is
           enumerated as a PictureVariable -->
      <xs:element name="simpleTemplateVariable" type="simpleTemplateVariableType" minOccurs="0" maxOccurs="unbounded" />
    </xs:sequence>
  </xs:complexType>

  <xs:complexType name="simpleTemplateVariableType">
    <xs:sequence>
      <!-- The name is used to identify this variable within the feed item template (required) -->
      <xs:element name="name" type="xs:string" minOccurs="1" maxOccurs="1" />

      <!-- Used for Link nodes to denote the text the link should display
           (optional for the Link node, if not specified the URI will be used as the display text)  -->
      <xs:element name="text" type="xs:string" minOccurs="0" maxOccurs="1" />

      <!-- URI of the picture location (required) -->
      <xs:element name="value" type="xs:anyURI" minOccurs="0" maxOccurs="1" />

      <!-- Alternate text for the picture (optional) -->
      <xs:element name="altText" type="xs:string" minOccurs="0" maxOccurs="1" />

      <!-- The picture can be a link which is specified here (optional) -->
      <xs:element name="href" type="xs:anyURI" minOccurs="0" maxOccurs="1" />
    </xs:sequence>
    <xs:attribute name="type" type="templateSimpleTypeRestrictionType" use="required" />
  </xs:complexType>

  <xs:simpleType name="templateSimpleTypeRestrictionType">
    <xs:restriction base="xs:string">
      <!-- Links included with the feed item -->
      <xs:enumeration value="linkVariable" />

      <!-- Text included with the feed item -->
      <xs:enumeration value="textVariable" />

      <!-- Picture variables included in ListVariableItem -->
      <xs:enumeration value="pictureVariable" />
    </xs:restriction>
  </xs:simpleType>

  <!-- Type definiton for .\activityFeed\templates -->
  <xs:complexType name="templatesType">
    <xs:sequence>
      <!-- Container for template parts -->
      <xs:element name="activityTemplateContainer" type="activityTemplateContainerType" minOccurs="0" maxOccurs="unbounded" />
    </xs:sequence>
  </xs:complexType>

  <!-- Type definiton for .\activityFeed\templates\activityTemplateContainer -->
  <xs:complexType name="activityTemplateContainerType">
    <xs:sequence>
      <!-- Used to denote an activity feed update template, such as a blog post or profile change (required) -->
      <xs:element name="applicationID" type="xs:unsignedLong" minOccurs="1" maxOccurs="1" />

      <!-- Used to denote the template type, such as multiple profile change types (required) -->
      <xs:element name="templateID" type="xs:unsignedLong" minOccurs="1" maxOccurs="1" />

      <!-- Template information for displaying activity feed item (required) -->
      <xs:element name="activityTemplate" type="activityTemplateType" minOccurs="1" maxOccurs="1" />
    </xs:sequence>
  </xs:complexType>

  <!-- Type definiton for .\activityFeed\templates\activityTemplateContainer\activityTemplate -->
  <xs:complexType name="activityTemplateType">
    <xs:sequence>
      <!-- Used for denoting a status, photo or document related activity feed item (optional) -->
      <xs:element name="type" type="activityTemplateTypeRestrictionType" minOccurs="0" maxOccurs="1" />

      <!-- Title used for displaying activity feed item (required) -->
      <xs:element name="title" type="xs:string" minOccurs="1" maxOccurs="1" />

      <!-- Extra information displayed with activity feed item (optional) -->
      <xs:element name="data" type="xs:string" minOccurs="0" maxOccurs="1" />

      <!-- Icon used for displaying activity feed item (required) -->
      <xs:element name="icon" type="xs:anyURI" minOccurs="1" maxOccurs="1" />
    </xs:sequence>
  </xs:complexType>

  <!-- Type definiton for .\activityFeed\templates\activityTemplateContainer\activityTemplate\type -->
  <!-- Only status, photo and document updates are specially recognized -->
  <xs:simpleType name="activityTemplateTypeRestrictionType">
    <xs:restriction base="xs:string">
      <xs:enumeration value="Status Update" />
      <xs:enumeration value="Photo" />
      <xs:enumeration value="Document" />
      <xs:enumeration value="Other" />
    </xs:restriction>
  </xs:simpleType>

  <!-- Type definition for Capabilities-->
  <xs:element name="capabilities">
    <xs:annotation>
      <xs:documentation xml:lang="en">
        Schema for Capabilities
      </xs:documentation>
    </xs:annotation>
    <xs:complexType>
    <xs:sequence>
      <!-- Indicates if the network supports get friends call-->
      <xs:element name="getFriends" type="xs:boolean" minOccurs="1" maxOccurs="1"/>
      <!-- Indicates if the network allows storing friends-->
      <!--(contacts) locally as Outlook contact items-->
      <xs:element name="cacheFriends" type="xs:boolean" minOccurs="1" maxOccurs="1"/>
      <!-- Indicates if the network supports follow this person call-->
      <xs:element name="followPerson" type="xs:boolean" minOccurs="1" maxOccurs="1"/>
      <!-- Indicates if the network supports do not follow this person call-->
      <xs:element name="doNotFollowPerson" type="xs:boolean" minOccurs="1" maxOccurs="1"/>
      <!-- Indicates if the network supports get activities call-->
      <xs:element name="getActivities" type="xs:boolean" minOccurs="1" maxOccurs="1"/>
      <!-- Indicates if the network supports storing activities-->
      <!-- as Outlook RSS items-->
      <xs:element name="cacheActivities" type="xs:boolean" minOccurs="1" maxOccurs="1"/>
      <!-- Indicates if the network supports dynamic lookup-->
      <!-- of Activities-->
      <xs:element name="dynamicActivitiesLookup" type="xs:boolean" minOccurs="0" maxOccurs="1"/>
      <!-- Indicates if the OSC displays network url in Acct config-->
      <xs:element name="displayUrl" type="xs:boolean" minOccurs="1" maxOccurs="1"/>
      <!-- Indicates if the OSC should use Forms Based Authentication (LogonWeb method)-->
      <xs:element name="useLogonWebAuth" type="xs:boolean" minOccurs="1" maxOccurs="1"/>
      <!-- Indicates if the OSC should hide "Click here to create an account" and-->
      <!-- "Forgot your password?" hyperlinks in the account setup dialog-->
      <xs:element name="hideHyperlinks" type="xs:boolean" minOccurs="0" maxOccurs="1"/>
      <!-- Indicates if the OSC should call the GetAutoConfiguredSession-->
      <!-- function on the ISocialSession object interface to attempt-->
      <!-- autoconfiguration of the network for the user-->
      <xs:element name="supportsAutoConfigure" type="xs:boolean" minOccurs="0" maxOccurs="1"/>
      <!-- Determines the minimum time in minutes between network contact syncs, regardless of success -->
      <xs:element name="contactSyncRestartInterval" type="xs:unsignedInt" minOccurs="0" maxOccurs="1"/>
    </xs:sequence>
    </xs:complexType>
  </xs:element>

  <!-- Root element for friends list-->
  <xs:element name="friends">
    <xs:annotation>
      <xs:documentation xml:lang="en">
        Friends contains a collection of person elements
      </xs:documentation>
    </xs:annotation>
    <xs:complexType>
      <xs:sequence>
        <xs:element name="person" minOccurs="0" maxOccurs="unbounded" type="personType">
        </xs:element>
      </xs:sequence>
    </xs:complexType>
  </xs:element>

  <!-- Type definition for personType -->
  <xs:complexType name="personType">
    <xs:annotation>
      <xs:documentation xml:lang="en">
        personType represents a person contact in Outlook
      </xs:documentation>
    </xs:annotation>
      <xs:sequence>
        <!-- Network User ID for this person -->
        <xs:element name="userID" type="xs:string" />
        <!-- Person first name or given name -->
        <xs:element name="firstName" minOccurs="0" type="stringType" />
        <!-- Person last name or surname-->
        <xs:element name="lastName" minOccurs="0" type="stringType" />
        <!-- Person full name -->
        <xs:element name="fullName" minOccurs="0" type="stringType" />
        <!-- Person nickname -->
        <xs:element name="nickname" minOccurs="0" type="stringType" />
        <!-- Person fileas name used for FileAs property of Contact item-->
        <xs:element name="fileAs" minOccurs="0" type="stringType" />
        <!-- Company name for the person -->
        <xs:element name="company" minOccurs="0" type="stringType" />
        <!-- Person title -->
        <xs:element name="title" minOccurs="0" type="stringType" />
        <!-- Person's anniversary date -->
        <xs:element name="anniversary" minOccurs="0" type="xs:date" />
        <!-- Person's birthday -->
        <xs:element name="birthday" minOccurs="0" type="xs:date" />
        <!-- Unique SMTP address for the person -->
        <xs:element name="emailAddress" minOccurs="0" type="xs:string" />
        <!-- Email2 SMTP address for the person -->
        <xs:element name="emailAddress2" minOccurs="0" type="xs:string" />
        <!-- Email3 SMTP address for the person -->
        <xs:element name="emailAddress3" minOccurs="0" type="xs:string" />
        <!-- Web profile page for the person -->
        <xs:element name="webProfilePage" minOccurs="0" type="xs:string" />
        <!-- Person's home phone -->
        <xs:element name="phone" minOccurs="0" type="stringType" />
        <!-- Person's cell or mobile phone -->
        <xs:element name="cell" minOccurs="0" type="stringType" />
        <!-- Person's home phone (this element is not used in OSC v1.0) -->
        <xs:element name="homePhone" minOccurs="0" type="stringType" />
        <!-- Person's work phone -->
        <xs:element name="workPhone" minOccurs="0" type="stringType" />
        <!-- Person's address -->
        <xs:element name="address" minOccurs="0" type="stringType" />
        <!-- Person's city -->
        <xs:element name="city" minOccurs="0" type="stringType" />
        <!-- Person's state/province -->
        <xs:element name="state" minOccurs="0" type="stringType" />
        <!-- Person's zip code -->
        <xs:element name="zip" minOccurs="0" type="stringType" />
        <!-- Person's relationship (this element is not used in OSC v1.0) -->
        <xs:element name="relationship" minOccurs="0" type="stringType" />
        <!-- Creation time of the person's profile on the network -->
        <xs:element name="creationTime" minOccurs="0" type="xs:dateTime" />
        <!-- Last modification time of person's profile on the network -->
        <xs:element name="lastModificationTime" minOccurs="0" type="xs:dateTime" />
        <!-- Expiration time of the person's profile data -->
        <xs:element name="expirationTime" minOccurs="0" type="xs:dateTime" />
        <!-- Gender for this person -->
        <xs:element name="gender" minOccurs="0">
          <xs:simpleType>
            <xs:restriction base="xs:string">
              <xs:pattern value="male|female|unspecified"/>
            </xs:restriction>
          </xs:simpleType>
        </xs:element>
      </xs:sequence>
  </xs:complexType>

  <xs:simpleType name="stringType">
    <xs:restriction base="xs:string">
      <xs:maxLength value="1024" />
    </xs:restriction>
  </xs:simpleType>

</xs:schema>

Error Codes

Success, warning, and error values are returned by using a 32-bit number that is called a result handle, or HRESULT. An HRESULT is really not a handle to anything; it is merely a 32-bit value that has several fields encoded in the value. A zero result indicates success, and a nonzero result indicates failure.

Providers should return errors to the caller by using one of the error codes shown in the following table.

Error	Error code (hexadecimal)	Description
OSC_E_INTERNAL_ERROR	0x80041400	An internal error occurred because of an invalid operation.
OSC_E_INVALIDARG (E_INVALIDARG)	0x 80070057	An invalid argument was passed to a function.
OSC_E_AUTH_ERROR	0x80041404	Authentication failed on the network of the social network site.
OSC_E_COULDNOTCONNECT	0x80041402	No connection is available to connect to the social network site.
OSC_E_NOT_FOUND	0x80041405	A resource cannot be found.
OSC_E_NOT_IMPLEMENTED (E_NOTIMPL)	0x80004001	The request to the social network site is valid but has not been implemented by the social network site.
OSC_E_OUT_OF_MEMORY (E_OUTOFMEMORY)	0x8007000E	An out-of-memory error occurred.
OSC_E_PERMISSION_DENIED	0x80041403	The OSC provider denied permission for the resource.
OSC_E_VERSION	0x80041401	The provider does not support this version of OSC provider extensibility.

Provider Calling Sequence

The actual provider calling sequence is not guaranteed to follow the calling sequence described in this document. Provider calling sequence can vary depending on the capabilities returned by the ISocialProvider::GetCapabilities method. The calling sequence is provided to developers to help you determine the social network API calls required to implement the given member on a provider extensibility interface.

Basic Authentication

The OSC calls provider methods and properties in a sequence that is determined by the capabilities XML returned in the ISocialProvider::GetCapabilities method. The following table shows the typical calling sequence of the OSC if the OSC provider supports basic authentication.

Provider member	Description
ISocialProvider::Load	Occurs when the OSC loads the provider.
ISocialProvider::Version	Returns a string that represents the version number of the OSC provider.
ISocialProvider::SocialNetworkName	Returns a string that represents the social network name.
ISocialProvider::SocialNetworkGuid	Returns an immutable GUID that represents the social network.
ISocialProvider::GetCapabilities	Gets a string that complies with the schema definition for capabilities.
ISocialProvider::SocialNetworkIcon	Returns a byte array that represents the icon for the social network site.
ISocialProvider::GetSession	Gets an ISocialSession interface.
ISocialSession::Logon	Logs on to the social network site by using the specified user name and password.
ISocialSession::GetLoggedOnUser	Gets an ISocialProfile interface that represents the logged-on user.
ISocialSession::GetNetworkIdentifier	Gets a string that represents a unique identifier for a social network site. The network identifier can be equivalent to the network name.

Forms-Based Authentication

The following table shows the typical calling sequence of the OSC if the OSC provider supports forms-based authentication.

Provider member	Description
ISocialProvider::Load	Occurs when the OSC loads the provider.
ISocialProvider::Version	Returns a string that represents the version number of the provider for this social network.
ISocialProvider::SocialNetworkName	Returns a string that represents the social network name.
ISocialProvider::SocialNetworkGuid	Returns an immutable GUID that represents the social network.
ISocialProvider::GetCapabilities	Obtains a string that complies with schema definition for capabilities.
ISocialProvider::SocialNetworkIcon	Returns a byte array that represents the icon for the social network.
ISocialProvider::GetSession	Gets an ISocialSession interface.
ISocialSession::LogonWeb	Logs on to the social network site by using forms-based authentication. For the initial logon, the OSC passes 空 for the connectIn parameter. After the initial logon, the OSC passes an opaque token URL to the provider in the connectIn string.
ISocialSession::GetLogonUrl	Returns a string used to display a browser-based form to the user during Web authentication. This method is called only if the initial call to LogonWeb passes 空 for the connectIn parameter.
ISocialSession:: LogonWeb	Logs on to the social network site by using forms-based authentication. This method is called a second time only if the initial LogonWeb call passed 空 for the connectIn parameter.
ISocialSession::GetLoggedOnUser	Gets an ISocialProfile interface that represents the logged-on user.
ISocialSession::GetNetworkIdentifier	Gets a string that represents a unique identifier for a social network site. The network identifier can be equivalent to the network name.

Synchronizing Friends

The following table shows the calling sequence of the OSC that occurs when the OSC synchronizes the user’s friend list from the social network.

Provider member	Description
ISocialPerson::GetFriendsAndColleagues	Gets and synchronizes the user’s friend list.
ISocialSession::GetPerson	For each person in the XML returned by GetFriendsAndColleagues, the OSC calls GetPerson to get an ISocialPerson interface for that person.
ISocialPerson::GetPicture	For each person in the XML returned by GetFriendsAndColleagues, the OSC calls GetPicture to get a picture resource for that person.

Synchronizing Activities

The following table shows the OSC calling sequence that occurs when the OSC synchronizes the activities of friends and colleagues from the social network.

Provider member	Description
ISocialProfile::GetActivitiesOfFriendsAndColleagues	Gets and synchronizes a collection of activities for friends and colleagues.
ISocialSession::GetPerson	For each activityFeed in the XML returned by GetActivitiesOfFriendsAndColleagues, the OSC calls GetPerson to get an ISocialPerson interface for that person.
ISocialPerson::GetDetails	For each activityFeed in the XML returned by GetActivitiesOfFriendsAndColleagues, the OSC calls GetDetails to get details for that person, such as first name and last name.

Provider Debugging

To debug a provider, create a DebugProviders value of type DWORD in the Windows registry under the SocialConnector key (shown on the following line), and set the DebugProviders value to 1.

HKEY_CURRENT_USER\Software\Microsoft\Office\Outlook\SocialConnector

By default, provider debugging is not turned on. If the DebugProviders value is not present, or it is present and set to a value of 0, provider debugging is turned off.

If the DebugProviders value is set to 1, an alert dialog box is displayed with verbose error information when an error occurs. Setting the DebugProviders value to 1 also causes validation of provider XML against the schema for OSC provider extensibility, OutlookSocialProvider.xsd. The effect of this registration key is global—the debug alert appears for all loaded providers instead of for a specific provider.

To display command bar buttons that can help you debug a provider, create a ShowDebugButtons value of type DWORD in the Windows registry under the SocialConnector key, and set the ShowDebugButtons value to 1. To hide the debug command bar buttons, set the ShowDebugButtons value to 0.

For Outlook 2010, the debug command bar buttons appear on the Add-ins tab of the explorer ribbon. For Outlook 2007 and Outlook 2003, the debug command bar buttons appear on the standard command bar of the Outlook explorer window.

The following table shows the provider debug commands.

Command	Function
Sync Feeds	Causes the OSC to ask the provider for cached activities only.
Sync Contacts	Causes the OSC to ask the provider for cached contacts only.
GAL Sync	Causes the OSC to populate data from the Microsoft Exchange Global Address List to Outlook contacts.
Clear AFI Cache	Clears the in-memory activity cache.
Clear Contact Cache	Clears the in-memory contact cache.
Invalidate Category Cache	Causes the OSC to reload the category list for each store when the activity feed is refreshed.

Provider Deployment

The recommended method of deploying an OSC provider is to use a Microsoft Windows Installer (.msi) package. After downloading the installation package to a local hard disk, the end user installs the provider. Once provider installation is complete, the user can connect the provider and provide credentials for logon to the user's social network account. If the user decides to uninstall the provider, the user can use Programs and Features in the Windows Control Panel.

COM Registration Required

During installation, the provider DLL must be registered by using COM self-registration or regsvr32. COM registration of the provider DLL registers the provider under the HKCR registry hive.

An OSC provider developed in managed code has a COM-visible provider assembly.

If the provider is managed, the provider assembly must be COM-visible. You should use a separate application domain for the provider component. Otherwise, the provider uses the default shared application domain that is used by other components, and the provider may not operate as expected.

Registry Entries

The OSC uses the following registry keys and values to recognize OSC providers:

• HKEY_CURRENT_USER\Software\Microsoft\Office\Outlook\SocialConnector\SocialProviders

• HKEY_LOCAL_MACHINE\Software\Microsoft\Office\Outlook\SocialConnector\SocialProviders

Write the key under HKCU, because administrative permissions are not required. Procedures to install and uninstall an OSC provider component should add and remove the provider’s programmatic identifier (ProgID) under the SocialProviders key.

Installation Checks

When you build the installation package for an OSC provider, complete the following installation checks to ensure that the OSC provider installs correctly.

1. As a prerequisite, the provider installer should determine whether the OSC is installed. To determine whether the OSC is installed, write an installer custom action to test for the existence of the following qualified component ID:

   {A3B82DA3-8AD9-4935-AEA8-54B754459483}

   The qualified component ID is a GUID that provides a method of single-level indirection, similar to a pointer. For more information about Windows Installer, see Roadmap to Windows Installer Documentation.

2. If the qualified component ID specified in step 1 does not exist, check whether the OSC is installed as a default component of a Click-to-Run installation of Outlook 2010.

   Click-to-Run is a virtual environment in which Outlook 2010 can run. The Click-to-Run virtual machine is 32-bit only. To determine whether Outlook 2010 is running as a Click-to-Run application, examine the VirtualOutlook key in the following location in the Windows registry:

   HKEY_LOCAL_MACHINE\Software\Microsoft\Office\14.0\Common\InstallRoot\Virtual\VirtualOutlook

   The VirtualOutlook key is a REG_SZ value that contains the culture tag of the installed product language, such as "en-us".

3. If either condition 1 or 2 is satisfied, the OSC is installed. Proceed with installing the provider. If you do not support a 64-bit version of your provider, you must evaluate condition 4.

4. Check whether 64-bit Outlook 2010 (and, hence, 64-bit OSC) has been installed on the client computer. If so, a 32-bit OSC provider will not work and you must install a 64-bit OSC provider.

   Outlook 2010 is available in both 32-bit and 64-bit versions. Versions of Outlook prior to Outlook 2010 are available only in a 32-bit version. The default installation of Microsoft Office 2010 on 64-bit Windows is 32-bit. However, if you intend to support the 64-bit version of the OSC that is installed with 64-bit Outlook 2010, you must also release a 64-bit version of your provider. To determine the bitness of the installed version of Outlook 2010, examine the Bitness key in the following location in the Windows registry:

   HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Office\14.0\Outlook

   The Bitness key is "x86" for 32-bit Outlook 2010, or "x64" for 64-bit Outlook 2010.

5. In addition to checking whether the OSC is installed, the provider installer can also check the installed version of the OSC type library by examining the OSCVersion key in the following location in the Windows registry:

   HKEY_LOCAL_MACHINE\Software\Microsoft\Office\Outlook\SocialConnector\OSCVersion

   The value of OSCVersion is a string that specifies the type library version number of Socialprovider.dll (for example, "1.0").

6. During installation, the provider can also check the current Outlook user interface language by examining the OSCLcid key in the following location in the Windows registry:

   HKEY_LOCAL_MACHINE\Software\Microsoft\Office\Outlook\SocialConnector\OSCLcid

   The OSCLcid key is a DWORD value that specifies the Internet Engineering Task Force (IETF) language tag (defined by RFC 4646 and RFC 4647), that represents the current Outlook user interface language.

Best Practices for Developing an OSC Provider

You should use the following practices when you develop an OSC provider:

• To minimize the size of the provider download package, build the provider by using a native compiler such as C++ or any other tool that can build a COM component.

• If you are developing a provider for a third-party social network, your provider must adhere to the social network’s terms of service.

• In your provider, generate a unique user agent that is sent to the network to track calls made by your provider to the network.

• Do not make calls to the social network when the OSC calls the ISocialProvider::GetCapabilities method. If there is no network connection, the ISocialProvider::GetCapabilities call will not return valid capabilities XML. The best practice is to store capabilities XML as a resource in your provider.

• Your OSC provider can generate a significant volume of calls to a social network, because of the number of Outlook users and the number of mail messages read by each user daily. Depending on the terms of service for your social network, using friend and activity caching can reduce the number of calls from the OSC to your provider and, in turn, from your provider to the social network.

• Outlook 2010 is available in both 32-bit and 64-bit versions. Versions of Outlook prior to Outlook 2010 are available only in a 32-bit version. The default installation of Microsoft Office 2010 on 64-bit Windows is 32-bit. However, if you intend to support the 64-bit version of the OSC that is installed with 64-bit Outlook 2010, you must also release a 64-bit version of your provider.

Sample OSC Provider

Accompanying this article are one sample provider and several provider templates for C++, C#, and Visual Basic.

The sample provider is named TestProvider and is for demonstration only. It does not connect to a specific real social network, but it does implement all the members required by the four interfaces that a provider must implement. Each interface is represented by a class. TestProvider uses Visual C# and requires Microsoft Visual Studio 2008 Service Pack 1 and Outlook 2010, Outlook 2007, or Outlook 2003.

The provider templates are available for use when you build a provider in the language of your choice. To minimize the download size of the provider and to minimize provider load time, you should build a production provider by using C++. If you are developing a provider for users who already have the .NET Framework 3.5 SP1 installed on their computers, you should also consider writing a managed provider by using Visual C# or Visual Basic.

Installation Instructions

To download the sample code installation package

1. Download the SampleOSCProviders.zip file from Outlook Sample: Outlook Social Connector Provider.

2. Extract the .zip file into the folder of your choice. In Windows Vista or Windows 7, the default path for Visual Studio 2008 projects is C:\Users\user\Documents\Visual Studio 2008\Projects.

3. After extracting the .zip file, you will find the following projects in your projects folder:

   • OSCProvider_CPP—Contains the C++ provider template.

   • OSCProvider_CS—Contains the C# provider template.

   • OSCProvider_VB—Contains the Visual Basic provider template.

   • TestProvider—Contains the TestProvider project.

Using the TestProvider Project

The TestProvider project helps you understand when and how the OSC calls OSC provider extensibility interfaces that your OSC provider implements. The TestProvider project does not connect to an actual social network. The data provided by TestProvider is static and is for demonstration purposes only.

To build and run the TestProvider project

1. Start Visual Studio 2008 by using the Run As Adminstrator command.

2. Open TestProvider.sln in the C:\Users\user\Documents\Visual Studio 2008\Projects\TestProvider folder.

3. On the Build menu, click Build TestProvider.

4. Open RegisterProvider.reg in the TestProvider folder to add the correct registry entries for TestProvider.

   RegisterProvider.reg also turns on provider debugging. It sets the DebugProviders and ShowDebugButtons values so that Debug buttons appear on the Add-ins group in the ribbon for Outlook 2010, or the standard explorer command bar in Outlook 2007 or Outlook 2003.

5. Select TestProvider properties on the Project menu, and then click the Debug tab.

6. Under Start Action, select the Start External Program option, and specify the full path of the version of Outlook that is installed on your computer. For Outlook 2010, the default installation path is C:\Program Files\Microsoft Office\Office14\OUTLOOK.EXE. For Outlook 2007, the default is C:\Program Files\Microsoft Office\Office12\OUTLOOK.EXE. For Outlook 2003, the default is C:\Program Files\Microsoft Office\Office11\OUTLOOK.EXE.

7. Under the References node in Solution Explorer, ensure that the reference is correct for OutlookSocialProvider. If the reference is incorrect, remove the reference and then select Add Reference on the Project menu. On the COM tab of the Add Reference dialog box, add a reference to the Microsoft Outlook Social Provider Extensibility type library.

8. On the Debug menu, click Start Debugging. This starts Outlook.

9. Click the Add button in the People Pane, and then click Add a Network to add TestProvider. You can add a fictitious user name and password, but these are not required for TestProvider.

10. After TestProvider is loaded, you can use breakpoints in the OSC provider code to learn about the calling sequences of the OSC and the OSC provider.

Sample OSC Provider Templates

The sample provider templates give you a framework for implementing an OSC provider. The provider templates are available in C++, C#, and Visual Basic. These templates are just a starting point for your provider development; writing the implementation code for the provider and creating a setup package for the provider are not addressed in this document.

To use the sample provider templates

1. Change the project name and namespace in the template to your project name and namespace identifiers.

2. Modify the AssemblyInfo class to specify the appropriate assembly information.

3. Implement the interface members marked as To-Do and add more dependencies and references, as required.

4. Build the project.

5. Ensure that the provider assembly ProgID is listed as a key under HKEY_CURRENT_USER\Software\Microsoft\Office\Outlook\SocialConnector\SocialProviders.

6. To distribute the setup project, create a setup project in Visual Studio or a setup tool of your choice.

7. Your setup project should complete COM registration for your assembly and also create the ProgID key as listed in step 5.

Conclusion

The OSC provider extensibility interfaces provide a way for disparate social networks to show friend, activity, and relationship information in Outlook. An OSC provider component must implement the ISocialProvider, ISocialSession, ISocialProfile, and ISocialPerson interfaces. These interfaces expose methods and properties that allow the OSC to communicate with a social network independently of the APIs provided by the social network.

Additional Resources

If you are interested in developing a provider for your social network or line-of-business application, please send e-mail to oscprex@microsoft.com. We will consider enrolling you in our early adopter program.