Developing an Outlook Social Connector Provider

Note:
This article discusses the OSC provider extensibility in the Beta version of Outlook 2010. Some of the OSC provider API is expected to change in the RTM release.

The Outlook Social Connector (OSC) is a Microsoft Outlook 2010 add-in that connects to social and business networks, including Microsoft SharePoint and other popular third-party social networking sites, so users can stay in touch with the people in their networks without leaving Outlook. This document discusses the interfaces that an 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 status information) in Outlook 2010.

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.

An OSC provider can be written by using managed languages such as Microsoft Visual C# or Microsoft Visual Basic, or unmanaged languages such as Microsoft Visual C++. Any tool that can create a COM-visible DLL component can be used 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 INFO: 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 conform to 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 ships 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 ships 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 DLL friendly name is selected by the developer when setting a reference to Socialprovider.dll in the Visual Studio 2008 Tools for Office Add Reference dialog box shown in Figure 2.

Figure 2. Visual Studio 2008 Add Reference dialog box

An OSC provider must implement all of the following interfaces.

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
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 conform to 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 XXXX.xxxx where XXXX is the major version and xxxx is the minor version. 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.

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.4435).

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
GetLoggedOnUser	Method
GetLogonUrl	Method
GetNetworkIdentifier	Method
GetPerson	Method
InviteToNetwork	Method
LoggedOnUserID	Property
LoggedOnUserName	Property
Logon	Method
LogonWeb	Method
SiteUrl	Property

FindPerson

Syntax

HRESULT _stdcall FindPerson([in] BSTR userId, [out, retval] BSTR* result);

Description

Gets a string that represents a collection of people that 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 results parameter). The returned XML string must conform to the schema definition for friends, as defined in the schema for OSC provider extensibility.

Not implemented in OSC version 1.0.

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 connectIn string.

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. This function 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.

InviteToNetwork

Syntax	`HRESULT _stdcall InviteToNetwork([in] BSTR emailAddress);`
Description	Issues an invitation to a person to join the social network, based on the person's e-mail address, which is specified as an argument to the emailAddress parameter.
Remarks	The emailAddress parameter must be a valid SMTP address.

LoggedOnUserID

Syntax

[propget]

HRESULT _stdcall LoggedOnUserID([out, retval] BSTR* result);

Description

Returns a string that represents the user ID used when logging on. Read-only.

LoggedOnUserName

Syntax

[propget]

HRESULT _stdcall LoggedOnUserName([out, retval] BSTR* result);

Description

Returns a string that represents the user name 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 LogonWeb only if the provider indicates that it supports forms-based authentication. The provider indicates that 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 LogonWeb and GetLogonUrl in a specific order:

The OSC calls LogonWeb the first time, passing null to the connectIn parameter.
The provider raises the OSC_E_LOGON_FAILURE 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 in Microsoft Internet Explorer.
The OSC then calls LogonWeb a second time, passing null 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_LOGON_FAILURE error to the OSC.

Note: 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 purposes when it is stored in the Windows registry.

SiteUrl

Syntax

[propput]

HRESULT _stdcall siteUrl([in] BSTR rhs);

Description

Returns or sets the social network site URL to be used by the provider. Read/write.

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 userIds, this method sets the corresponding element in the output results array. 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 conform to the schema definition for an activity feed, 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 returned by GetActivitiesOfFriendsAndColleagues have a creation time value that is greater than startTime and lesser than or equal to Now.

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
DoNotFollowThisPerson	Method
FollowThisPerson	Method
GetActivities	Method
GetDetails	Method
GetFriendsAndColleagues	Method
GetFriendsAndColleaguesIDs	Method
GetPicture	Method
GetStatus	Method

DoNotFollowThisPerson

Syntax	`HRESULT _stdcall DoNotFollowThisPerson();`
Description	Removes the person from the follow action.

FollowThisPerson

Syntax	`HRESULT _stdcall FollowThisPerson();`
Description	Follows this person.

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 conform to the schema definition for an activity feed, as defined in the schema for OSC provider extensibility. The startTime parameter is a UTC Date value. Local time values must be converted to UTC Date values. Activities returned by GetActivities have a creation time value that is greater than startTime and lesser than or equal to Now.

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 conform to the schema definition for a 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 conform to 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 contain 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.

All XML returned from an OSC provider's interface methods must conform to 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 2010 Sample: Social Connector Provider.

XML

<?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="http://schemas.microsoft.com/office/outlook/socialprovider.xsd"
    xmlns="http://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>
            <!-- Social 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 identifying 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" />

            <!-- 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" />

            <!-- URI of the picture location (required). -->
            <xs:element name="value" type="xs:anyURI" minOccurs="1" 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" />
    </xs:complexType>

    <xs:simpleType name="templateSimpleTypeRestrictionType">
        <xs:restriction base="xs:string">
            <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"/>
                <!-- ttl (time-to-live) in minutes for friends calls. -->
                <!-- Minimum=1440 minutes(24 hours), 
                    Maximum=10080 minutes(7 days).-->
                <xs:element name="friendsTTL" type="friendsTTLType" minOccurs="0" maxOccurs="1" />
                <!-- Indicates if the network supports the call to follow
                    this person.-->
                <xs:element name="followPerson" type="xs:boolean" minOccurs="1" maxOccurs="1"/>
                <!-- Indicates if the network supports the call to 
                    not follow this person. -->
                <xs:element name="doNotFollowPerson" type="xs:boolean" minOccurs="1" maxOccurs="1"/>
                <!-- Indicates if the network supports the call to add 
                    A friend. -->
                <xs:element name="addFriendOrColleague" type="xs:boolean" minOccurs="1" maxOccurs="1"/>
                <!-- Indicates if the network provides an SMTP address
                    for a user. -->
                <xs:element name="provideUserSMTPAddress" type="xs:boolean" minOccurs="1" maxOccurs="1"/>
                <!-- Indicates if the network supports call to get 
                    activities. -->
                <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"/>
                <!-- ttl (time-to-live) in minutes for activities calls:-->
                <!-- minimum=5 minutes, maximum=1440 minutes (24 hours). -->
                <xs:element name="activitiesTTL" type="activitiesTTLType" minOccurs="0" maxOccurs="1"/>
                <!-- Indicates if the network supports dynamic lookup -->
                <!-- of activities-->
                <xs:element name="dynamicActivitiesLookup" type="xs:boolean" minOccurs="1" maxOccurs="1"/>
                <!-- Indicates if the OSC displays network URL in account
                    configuration. -->
                <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="1" 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="1" 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's first name or given name. -->
            <xs:element name="firstName" minOccurs="0" type="stringType" />
            <!-- Person's last name or surname. -->
            <xs:element name="lastName" minOccurs="0" type="stringType" />
            <!-- Person's full name. -->
            <xs:element name="fullName" minOccurs="0" type="stringType" />
            <!-- Person's nickname. -->
            <xs:element name="nickname" minOccurs="0" type="stringType" />
            <!-- Person's 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's 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" />
            <!-- Web profile page for the person. -->
            <xs:element name="webProfilePage" minOccurs="0" type="xs:string" />
            <!-- Person's contact telephone number. -->
            <xs:element name="phone" minOccurs="0" type="stringType" />
            <!-- Person's cell home phone. -->
            <xs:element name="cell" minOccurs="0" type="stringType" />
            <!-- Person's home phone -->
            <xs:element name="homePhone" minOccurs="0" type="stringType" />
            <!-- Person's work phone -->
            <xs:element name="workPhone" minOccurs="0" type="stringType" />
            <!-- Person's street 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. -->
            <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" />
        </xs:sequence>
        <!-- Gender for this person. -->
        <xs:attribute name="gender">
            <xs:simpleType>
                <xs:restriction base="xs:string">
                    <xs:pattern value="male|female|unspecified"/>
                </xs:restriction>
            </xs:simpleType>
        </xs:attribute>
    </xs:complexType>

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

    <xs:simpleType name="activitiesTTLType">
        <xs:restriction base="xs:integer">
            <xs:minInclusive value="5" />
            <xs:maxInclusive value="1440" />
        </xs:restriction>
    </xs:simpleType>

    <xs:simpleType name="friendsTTLType">
        <xs:restriction base="xs:integer">
            <xs:minInclusive value="1440" />
            <xs:maxInclusive value="10080" />
        </xs:restriction>
    </xs:simpleType>

</xs:schema>

The following examples illustrate XML that conforms to the XML schema for OSC provider extensibility.

Friends XML

The following example is a brief friends list returned from ISocialSession::GetFriendsAndColleagues.

XML

<?xml version="1.0" encoding="utf-8"?>
<friends xmlns="http://schemas.microsoft.com/office/outlook/socialprovider.xsd">
    <person gender="female">
        <userID>4abf8339zqg889</userID>
        <firstName>Melissa</firstName>
        <lastName>MacBeth</lastName>
        <nickname></nickname>
        <fileAs>MacBeth, Melissa (Contoso Ltd.)</fileAs>
        <company>Contoso Ltd.</company>
        <title>Product Manager</title>
        <anniversary>2002-05-17</anniversary>
        <birthday>1981-08-09</birthday>
        <emailAddress>melissa@contoso.com</emailAddress>
        <webProfilePage>http://contoso.com</webProfilePage>
        <relationship>friend</relationship>
        <creationTime>2009-01-08T08:30:20-08:00</creationTime>
        <lastModificationTime>2009-01-08T11:40:14-08:00</lastModificationTime>
        <expirationTime>2009-01-09T11:40:14-08:00</expirationTime>
    </person>
    <person gender="male">
        <userID>9wrf9045zty743</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>1993-06-21</anniversary>
        <birthday>1974-09-10</birthday>
        <emailAddress>michael@contoso.com</emailAddress>
        <webProfilePage>http://contoso.com</webProfilePage>
        <relationship>friend</relationship>
        <creationTime>2009-01-08T08:30:20-05:00</creationTime>
        <lastModificationTime>2009-01-08T11:40:14-05:00</lastModificationTime>
        <expirationTime>2009-01-09T11:40:14-05:00</expirationTime>
    </person>
</friends>

ActivityFeed XML

The following example illustrates an activity feed returned from ISocialPerson::GetActivitiesOfFriendsAndColleagues.

XML

<?xml version="1.0" encoding="utf-8"?>
<activityFeed xmlns="http://schemas.microsoft.com/office/outlook/socialprovider.xsd">
    <network>Contoso</network>
    <activities>
        <activityDetails>
            <ownerID>238a44824gh89</ownerID>
            <objectID>23782rqb78</objectID>
            <applicationID>6403544982806810</applicationID>
            <templateID>0</templateID>
            <publishDate>2009-02-06T23:49:15</publishDate>
            <templateVariables>
                <templateVariable type="linkVariable">
                    <name>Icon</name>
                    <value>http://blogs.msdn.com/examplebloguri.com/maffronti?icon=25</value>
                    <altText>Blog Post</altText>
                </templateVariable>
                <templateVariable type="publisherVariable">
                    <name>Publisher</name>
                    <id>michael@contoso.com</id>
                </templateVariable>
                <templateVariable type="linkVariable">
                    <name>BlogTitle</name>
                    <value>http://blogs.msdn.com/examplebloguri.com/michael?entry=103</value>
                    <altText>BLOG ROCKING</altText>
                </templateVariable>
                <templateVariable type="textVariable">
                    <name>Summary</name>
                    <value>Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book.</value>
                </templateVariable>
            </templateVariables>
        </activityDetails>
        <activityDetails>
            <ownerID>238a44824gh89</ownerID>
            <objectID>99752wti99</objectID>
            <applicationID>6262816084389130</applicationID>
            <templateID>0</templateID>
            <publishDate>2009-02-06T23:09:46</publishDate>
            <templateVariables>
                <templateVariable type="linkVariable">
                    <name>Icon</name>
                    <value>http://cId-8f493d79049225a6.contoso.com/redir.aspx?icon=3</value>
                    <altText>A New Photo Album Was Published</altText>
                </templateVariable>
                <templateVariable type="publisherVariable">
                    <name>Publisher</name>
                    <id>melissa@contoso.com</id>
                </templateVariable>
                <templateVariable type="linkVariable">
                    <name>AlbumTitle</name>
                    <text>Lake City Excursion</text>
                    <value>http://cId-8f493d79049225a6.contoso.com/redir.aspx?page=browse&amp;resId=8F493D79049225A6!3636&amp;view=thumbs&amp;ct=photos</value>
                </templateVariable>
                <templateVariable type="listVariable">
                    <name>Thumbs</name>
                    <listItems>
                        <simpleTemplateVariable type="pictureVariable">
                            <name>Photo</name>
                            <value>http://bad95w.contoso.com/y1pfSUs_-5hus0Q86VR9AqoplMl3Y0IJAytpCiYgW76vb4Z6xjCT7smo7Fs0JAEm61Tx_J7byWhmlY</value>
                            <altText>IMG_5354.jpg</altText>
                            <href>http://cId-8f493d79049225a6.contoso.com/redir.aspx?client=wnf&amp;resId=8F493D79049225A6!3649&amp;ct=photos</href>
                        </simpleTemplateVariable>
                        <simpleTemplateVariable type="pictureVariable">
                            <name>Photo</name>
                            <value>http://bad95w.contoso.com/y1pHoSzz70GnfYP8aDf22bTGtIWCWG-WhroSlgEObChCC2H2vA9i16G_9gdpLJujbvKzNd4MW3IkF8</value>
                            <altText>IMG_5353.jpg</altText>
                            <href>http://cId-8f493d79049225a6.contoso.com/redir.aspx?client=wnf&amp;resId=8F493D79049225A6!3648&amp;ct=photos</href>
                        </simpleTemplateVariable>
                        <simpleTemplateVariable type="pictureVariable">
                            <name>Photo</name>
                            <value>http://bad95w.contoso.com/y1p8hJt96vPVMZq7ZqVvXXwUaK1lPwZg7e8VtY8tVjzJgyS8g24kiQsdBstNQX5nKw2REwFM69PYj4</value>
                            <altText>IMG_5352.jpg</altText>
                            <href>http://cId-8f493d79049225a6.contoso.com/redir.aspx?client=wnf&amp;resId=8F493D79049225A6!3647&amp;ct=photos</href>
                        </simpleTemplateVariable>
                        <simpleTemplateVariable type="pictureVariable">
                            <name>Photo</name>
                            <value>http://bad95w.contoso.com/y1p5IYlyXzAlaiqRNU2Jo9TzM8Z7PN1FzloGgt3vQDrD824ulyxgdCAM0thHiWFEjawaFmVfijeg0g</value>
                            <altText>IMG_5351.jpg</altText>
                            <href>http://cId-8f493d79049225a6.contoso.com/redir.aspx?client=wnf&amp;resId=8F493D79049225A6!3646&amp;ct=photos</href>
                        </simpleTemplateVariable>
                        <simpleTemplateVariable type="pictureVariable">
                            <name>Photo</name>
                            <value>http://bad95w.contoso.com/y1pBPilofZ5NU8MaX-AH_TNtPmRIdltn6L89-4EoqU0EOvG0y97MGCIBYU6_KT_ksB3Zz7k7JnMvys</value>
                            <altText>IMG_5350.jpg</altText>
                            <href>http://cId-8f493d79049225a6.contoso.com/redir.aspx?client=wnf&amp;resId=8F493D79049225A6!3645&amp;ct=photos</href>
                        </simpleTemplateVariable>
                    </listItems>
                </templateVariable>
            </templateVariables>
        </activityDetails>
        <activityDetails>
            <ownerID>8dwwe90fgh89</ownerID>
            <objectID>99752wti99</objectID>
            <applicationID>6333180533604183</applicationID>
            <templateID>1</templateID>
            <publishDate>2009-02-06T18:52:00</publishDate>
            <templateVariables>
                <templateVariable type="publisherVariable">
                    <name>Publisher</name>
                    <id>will@contoso.com</id>
                </templateVariable>
                <templateVariable type="textVariable">
                    <name>StatusUpdate</name>
                    <text>It's bring your sons/daughters to work day tomorrow!</text>
                </templateVariable>
                <templateVariable type="linkVariable">
                    <name>Icon</name>
                    <value>http://www.contoso.com/exampleprofileuri.com/will?icon=10</value>
                    <altText>Status Update</altText>
                </templateVariable>
            </templateVariables>
        </activityDetails>
        <activityDetails>
            <ownerID>8dwwe90fgh89</ownerID>
            <objectID>80372wti99</objectID>
            <applicationID>1140855816</applicationID>
            <templateID>12</templateID>
            <publishDate>2009-02-06T21:31:11</publishDate>
            <templateVariables>
                <templateVariable type="linkVariable">
                    <name>Icon</name>
                    <value>http://contoso.com/icon?type=replytoperson</value>
                </templateVariable>
                <templateVariable type="publisherVariable">
                    <name>Publisher</name>
                    <id>randy@contoso.com</id>
                </templateVariable>
                <templateVariable type="linkVariable">
                    <name>AppName</name>
                    <text>Adventure Works</text>
                    <value>http://contoso.com/randy</value>
                </templateVariable>
                <templateVariable type="linkVariable">
                    <name>Owner</name>
                    <text>Randy</text>
                    <value>http://contoso.com/randy</value>
                </templateVariable>
                <templateVariable type="textVariable">
                    <name>ReplyText</name>
                    <value>Last night at SEA we were delayed 4 hours due to air traffic. We played our favorite game. It made the wait more bearable.</value>
                </templateVariable>
            </templateVariables>
        </activityDetails>
        <activityDetails>
            <ownerID>8dwwe90fgh89</ownerID>
            <objectID>80372wti67</objectID>
            <applicationID>1073750531</applicationID>
            <templateID>31</templateID>
            <publishDate>2009-02-06T19:07:48</publishDate>
            <templateVariables>
                <templateVariable type="publisherVariable">
                    <name>Publisher</name>
                    <id>michael@contoso.com</id>
                </templateVariable>
                <templateVariable type="listVariable">
                    <name>Thumbs</name>
                    <listItems>
                        <simpleTemplateVariable type="pictureVariable">
                            <name>Photo</name>
                            <value>http://farm4.contoso.com/3506/3258799194_d542122475_s.jpg</value>
                            <altText>Dec06 031</altText>
                            <href>http://www.contoso.com/photos/72516638@N00/3258799194/</href>
                        </simpleTemplateVariable>
                    </listItems>
                </templateVariable>
                <templateVariable type="linkVariable">
                    <name>AppName</name>
                    <text>Photo Share</text>
                    <value>http://www.contoso.com/people/72516638@N00/</value>
                </templateVariable>
            </templateVariables>
        </activityDetails>
    </activities>
    <templates>
        <activityTemplateContainer>
            <applicationID>6403544982806810</applicationID>
            <templateID>0</templateID>
            <activityTemplate>
                <title>{publisher:Publisher} added a blog entry {link:BlogTitle}.</title>
                <data>"{text:Summary}"</data>
                <icon>{link:Icon}</icon>
            </activityTemplate>
        </activityTemplateContainer>
        <activityTemplateContainer>
            <applicationID>6262816084389130</applicationID>
            <templateID>0</templateID>
            <activityTemplate>
                <title>{publisher:Publisher} added photos to {link:AlbumTitle}</title>
                <data>{list:Thumbs({picture:Photo})}</data>
                <icon>{link:Icon}</icon>
            </activityTemplate>
        </activityTemplateContainer>
        <activityTemplateContainer>
            <applicationID>6333180533604183</applicationID>
            <templateID>1</templateID>
            <activityTemplate>
                <type>Status Update</type>
                <title>{publisher:Publisher}: {text:StatusUpdate}</title>
                <icon>{link:Icon}</icon>
            </activityTemplate>
        </activityTemplateContainer>
        <activityTemplateContainer>
            <applicationID>1140855816</applicationID>
            <templateID>12</templateID>
            <activityTemplate>
                <title>{publisher:Publisher} replied to {link:Owner} on {link:AppName}</title>
                <data>"{text:ReplyText}"</data>
                <icon>{link:Icon}</icon>
            </activityTemplate>
        </activityTemplateContainer>
    </templates>
</activityFeed>

Capabilities XML

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

XML

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

Capabilities XML is critical because it signals the functionality supported by the provider to the OSC. The following table summarizes each element of the capabilities schema.

Element	Description
getFriends	Indicates whether the social network site supports the call to get friends.
cacheFriends	Indicates whether the social network site allows storing data for friends.
friendsTTL	Indicates the Time to Live (TTL) in minutes for friends calls.
followPerson	Indicates whether the social network site supports the call to follow this person.
doNotFollowPerson	Indicates whether the social network site supports the call to not follow this person.
addFriendOrColleague	Indicates whether the social network site supports the call to add a friend or colleague.
provideUserSMTPAddress	Indicates whether the social network site provides an SMTP address for a user.
getActivities	Indicates whether the social network site supports the call to get activities.
cacheActivities	Indicates whether the social network site supports storing activities as Outlook RSS items.
activitiesTTL	Indicates the Time to Live (TTL) in minutes for activities calls.
dynamicActivitiesLookup	Indicates whether the social network site supports dynamic lookup of activities.
displayUrl	Indicates whether the OSC displays the network URL in account configuration.
useLogonWebAuth	Indicates whether the OSC should use forms-based authentication and the LogonWeb method. If useLogonWebAuth is false, the OSC assumes that the provider uses basic authentication.
hideHyperlinks	Indicates whether the OSC should hide Click here to create an account and Forgot your password? hyperlinks in the account setup dialog box.
supportsAutoConfigure	Indicates whether the OSC should call the GetAutoConfiguredSession function on the ISocialProvider interface to attempt automatic configuration of the network for the user.

Success, warning, and error values are returned by using a 32-bit number known as a result handle, or HRESULT. An HRESULT is really not a handle to anything; it is merely a 32-bit value with 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 following error codes.

Error	Error code (hexadecimal)	Description
OSC_E_INTERNAL_ERROR	0x80041400	An internal error has occurred due to an invalid operation.
OSC_E_INVALIDARG (E_INVALIDARG)	0x 80070057	An invalid argument has been passed to a function.
OSC_E_LOGON_FAILURE	0x80041404	Authentication has failed on the network of the social network site.
OSC_E_NO_CONNECTION	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 has occurred.
OSC_E_PERMISSION_DENIED	0x80041403	Permission for the resource is denied by the OSC provider.
OSC_E_VERSION	0x80041401	The provider does not support this version of OSC provider extensibility.

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 ISocialProvider::GetCapabilities. The calling sequence is provided to developers to help you determine the social network API calls required to implement the given member on a social 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 illustrates the typical calling sequence of the OSC if the OSC provider supports basic authentication.

Provider member	Description
ISocialProvider::Load	Loads the OSC 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::GetCapabilities	Gets a string that conforms to the schema definition for `capabilities`.
ISocialProvider:: SocialNetworkIcon	Returns a byte array that represents the icon for the social network site.
ISocialSession::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 social network identifier. A unique network identifier is string representation of a GUID associated with the social network.

Forms-Based Authentication

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

Provider Member	Description
ISocialProvider::Load	Loads the OSC 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::GetCapabilities	Obtains a string that conforms to schema definition for `capabilities`.
ISocialProvider:: SocialNetworkIcon	Returns a byte array that represents the icon for the social network.
ISocialSession::GetSession	Gets an ISocialSession interface.
ISocialSession::LogonWeb	The first of a series of calls for the OSC to allow a user to log on to the social network site by using forms-based authentication, passing null to the connectIn parameter. The OSC provider returns OSC_E_LOGON_FAILURE to the OSC.
ISocialSession:: GetLogonUrl	The second of a series of calls for the OSC to obtain a string used as a URL to present a browser-based form to the user during Web authentication.
ISocialSession:: LogonWeb	The third of a series of calls for the OSC to complete the logon by using forms-based authentication. The OSC passes the URL for the browser-based form in connectIn, and the provider returns any logon credentials for the OSC to store across connections in connectOut.
ISocialSession:: GetLoggedOnUser	Gets an ISocialProfile interface that represents the logged-on user.
ISocialSession:: GetNetworkIdentifier	Gets a string that represents a unique social network identifier. A unique network identifier is string representation of a GUID associated with the social network.

Synchronizing Friends

When the OSC synchronizes the user’s friend list from the social network, the calling sequence of the OSC is as shown in the following table.

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

When the OSC synchronizes the activities of friends and colleagues from the social network, the OSC calling sequence is as shown in the following table.

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.

To debug a provider, in the Windows registry, under the SocialConnector key, create a value DebugProviders of type DWORD, 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, when an error occurs, an alert dialog is displayed with verbose error information. 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 rather than a specific provider.

To display command bar buttons that can help you debug a provider, in the Windows registry, under the SocialConnector key, create a ShowDebugButtons value of type DWORD value, 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.

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.

To minimize the size of the OSC provider download package, build the provider by using a native compiler such as C++ or any other tool capable of building a COM component.
For a managed OSC provider to operate as expected, the provider component should use a separate application domain.
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 OSC calls.
Realize that 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 mails read by each user on a daily basis. 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. To determine the bitness of the installed version of Outlook 2010, examine the Bitness key under the following:

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.
As a prerequisite, the provider installer should check to determine whether the OSC is installed. To determine whether the OSC is installed, write a custom action to test for the existence of the following keys. If either of the keys is present in the Windows registry, the OSC is installed.

HKEY_CURRENT_USER\Software\Microsoft\Office\Outlook\SocialConnector

or

HKEY_LOCAL_MACHINE\Software\Microsoft\Office\Outlook\SocialConnector

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

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

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 that already have the .NET Framework 3.5 SP1 installed on their computers, then you should also consider writing a managed provider by using Visual C# or Visual Basic.

Installation Instructions

To download the sample code installation package

Download the SampleOSCProviders.zip file from Outlook 2010 Sample: Social Connector Provider.
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.
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.

The TestProvider project helps you to 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 learning purposes only.

To build and run the TestProvider project

Launch Visual Studio 2008 by using the Run As Adminstrator command.
Open TestProvider.sln in the C:\Users\<user>\Documents\Visual Studio 2008\Projects\TestProvider folder.
On the Build menu, click Build TestProvider.
Open RegisterProvider.reg in the TestProvider folder to add the correct registry entries for TestProvider.

RegisterProvider.reg also turns on provider debugging, setting the DebugProviders and ShowDebugButtons values so that Debug buttons appear on the Add-ins group in the ribbon for Outlook 2010.
Select TestProvider properties on the Project menu, and then click the Debug tab.
Under Start Action, select the Start External Program option, and adjust the path to the version of Outlook running on your computer. The default setting, C:\Program Files\Microsoft Office\Office14\OUTLOOK.EXE, runs the OSC provider on Outlook 2010.
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.
On the Debug menu, click Start Debugging. This launches Outlook.
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.
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.

The sample provider templates provide you with a framework for implementing an OSC provider. The provider templates are available in C++, C#, and Visual Basic. These templates are meant to jump-start your provider development, but 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

Change the project name and namespace in the template to your project name and namespace identifiers.
Modify the AssemblyInfo class to specify the appropriate assembly information.
Implement the interface members marked as To-Do and add additional dependencies and references, as required.
Build the project.
Ensure that the provider assembly ProgID is listed as a key under HKEY_CURRENT_USER\Software\Microsoft\Office\Outlook\SocialConnector\SocialProviders.
To distribute the setup project, create a setup project in Visual Studio or a setup tool of your choice.
Your setup project should complete COM registration for your assembly and also create the ProgID key as listed in step 5.

The OSC provider extensibility interfaces provide a way for disparate social networks to show friend, activity, and status 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.

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

Overview

Technical Requirements

Interface Reference

ISocialProvider

DefaultSiteUrls

GetAutoConfiguredSession

GetCapabilities

GetSession

GetStatusSettings

Load

SocialNetworkIcon

SocialNetworkName

Version

ISocialSession

FindPerson

GetLoggedOnUser

GetLogonUrl

GetNetworkIdentifier

GetPerson

InviteToNetwork

LoggedOnUserID

LoggedOnUserName

Logon

LogonWeb

SiteUrl

ISocialProfile

AreFriendsOrColleagues

GetActivitiesOfFriendsAndColleagues

SetStatus

ISocialPerson

DoNotFollowThisPerson

FollowThisPerson

GetActivities

GetDetails

GetFriendsAndColleagues

GetFriendsAndColleaguesIDs

GetPicture

GetStatus

XML Schema for OSC Provider Extensibility

XML Examples for an OSC Provider

Friends XML

ActivityFeed XML

Capabilities XML

Error Codes

Provider Calling Sequence

Basic Authentication

Forms-Based Authentication

Synchronizing Friends

Synchronizing Activities

Provider Debugging

Provider Deployment

COM Registration Required

Registry Entries

Best Practices for Developing an OSC Provider

Sample OSC Provider

Installation Instructions

Using the TestProvider Project

Sample OSC Provider Templates

Conclusion

Additional Resources