Messenger Session Invite and Messenger Private APIs

This topic provides information about the Messenger Session Invite APIs that provide a way to run peer-to-peer applications for any two Messenger client users.

The Messenger Session Invite and Messenger Private APIs exposed by Microsoft Windows Messenger enables two client programs to connect programmatically using the Microsoft .NET Messenger Service.

Note  By default, the Messenger Session Invite and Messenger Private APIs are locked only for use with the .NET Messenger Service to establish a peer-to-peer connection. They are not locked when used in conjunction with services other than the .NET Messenger Service.

The topics addressed are:

• Introduction
• Prerequisites
• Terminology
• Launching Session Invite Within Messenger
• Launching Session Invite Within an Application
• Additional Information
• Related Topics

Introduction

The Messenger Session Invite API provides a way to run peer-to-peer applications for any two Messenger client users. Unlike earlier versions of Messenger client, the messenger session invite mechanism does not depend on Microsoft DirectPlay. It does, however, support DirectPlay invitations from earlier versions of Messenger client.

Users who are already communicating through Messenger client can start both sides of an application from within a Messenger client. Users can also start an application first and then invite a user to join.

The following graphic illustrates the relationship between two Messenger client users who run a peer-to-peer application. Each Messenger user's platform establishes connection with one another, enabling the application to connect on both sides.

Note  A license and ID/key pair are required in order for an application to access the .NET Messenger Service using the Messenger Session Invite and Messenger Private APIs. The license requires an application that uses this API to follow certain guidelines designed to help help protect the integrity of the Messenger service. The ID/key pair is used to unlock the Messenger service APIs and to authenticate the application. To unlock the .NET Messenger Service, see the Unlock the Messenger APIs section of this topic. For more information, see the Messenger Lock and Key API.

Important  ID/key pairs are no longer being issued.

Prerequisites

Users should be familiar with Microsoft Visual C++ or Microsoft Visual Basic and know how to call an API exposed by Component Object Model (COM) objects.

Terminology

This section defines certain terms that are used throughout the article.

Launching Session Invite Within Messenger

Users who are already communicating through Messenger can start an application with each other from within Messenger by following these steps:

1. Sign in to Messenger.
2. Select the application to be used in the invitation.
3. Choose a recipient, and then click OK.

When installing an application, register it so that it belongs to the Messenger Invite menu. By doing this, the user can invite contacts to participate in a peer-to-peer session with this application from the Messenger Invite menu. The user can also accept an invitation to participate in a peer-to-peer session with this application when someone else invites him or her.

During the application registration, specify a location from which a recipient can download the application so that the recipient can run it regardless of whether it has been installed.

To register an application manually, you need a GUID, URL, path, and application name. The GUID is the key identifier for the application and must be unique. The other three values are the strings that identify the key. URL is the download site from which a user can retrieve the application. The path is an absolute or relative path of the application to be run. The application name is used as an identifier for the application. The new key to be created is located at HKEY_LOCAL_MACHINE\Software\Microsoft\MessengerService\SessionManager\Apps. After the application is manually registered, it appears in the Messenger Invite menu and can be used in a peer-to-peer session.

Launching Session Invite Within an Application

You can send an invitation to any running Messenger application using the Microsoft Session Invite API. Although similar to using the Messenger user interface (UI), this method is different in two ways. First, the application does not have to be launched on the originating side because it is already running. Second, context data (GUID, IP, sign-in name, and IMsgrSession::SessionID) from the application on the originating side can be provided at the beginning of the invitation sequence.

The following describe each step of the invitation process.

• Create a Session Object
• Unlock the Messenger APIs
• Send an Invitation
• Notifications Fired From a Messenger Service

Create a Session Object

Create a MsgrSessionManager object using the Messenger Session Invite API. The MsgrSessionManager object, when created, is composed of the initial context including both users' sign-in names and the download location (URL) for the application from the registry. After you create the MsgrSessionManager object, create a MsgrSession object.

Upon creating the session, the IMsgrSession::State property changes and a IMsgrSession::SessionID property is created. The IMsgrSession::SessionID property takes the format of {xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx} and the IMsgrSession::State property can be one of eight SESSION_STATE values.

Note  A new session must be created each time you want to send an invitation.

Unlock the Messenger APIs

To unlock the Messenger service APIs, you must have a license and valid ID/key pair. The license requires an application that uses the API to follow guidelines designed to help protect the integrity of the Messenger service. The Lock and Key mechanism helps prevent unauthorized applications from using the Messenger service APIs.

Note  A Messenger client cannot unlock the Messenger service APIs more than once during a session. Therefore, if an application attempts to re-authenticate during the same session, the MSGR_E_API_ALREADY_UNLOCKED error code is returned and there is no resulting transaction.

For more information about the Messenger Lock and Key mechanism used to help control access to the Messenger service APIs as well as the protocol and service interfaces, see Messenger Lock and Key API.

Send an Invitation

The IMsgrSession::Invite method is used to send an invitation to a user. This method creates a session containing all the inviter's session information on the Messenger client server. In addition, the Messenger client server creates a session object on the recipient's Messenger client platform. When this happens, a dialog box is displayed that offers the user the choice to accept, decline, or cancel the invitation. If the recipient declines or cancels the invitation, the result is sent back to the inviter's application and the session is terminated. If the recipient accepts the invitation, the Messenger client platform confirms that the application is installed on the computer.

If the application is not installed, the Messenger client declines the invitation and launches a browser to the site from which the recipient can download it. After the application is successfully installed, the Messenger client sends an acceptance to the inviter's Messenger client switchboard server and the application is launched. The inviter's Messenger client then passes a cookie to the locally launched application with which it creates its own MsgrSessionManager object.

At this point, the application is running on both computers and the data is being shared through the session object known to both instances of Messenger client.

The following example shows how to use the IMsgrSession::Invite method. This snippet also includes references to the MessengerAPI API . For more information, see Messenger API SDK Documentation .

/******************************************************************************
How to call WM session invite...

    ' 1. Create a context data variable to be used. Context data
         variable is string that contains information specific to   
         the application launching session that needs to be shared   
         across clients
    ' 2. Create and assign a value for the sign-in name to a
         variable.
    ' 3. Create and assign a value for the ServiceID of the user to        
         be invited.
    ' 4. Set the MsgrContact object to the variables created in
         steps 2 and 3
    ' 5. Create a session object using session manager
    ' 6. Set the application id on the session object
    ' 7. Create session using contact ID and context data

CMessengerSessionImpl class has two methods,

1. Initialize : Creates the session manager, messenger client
                objects and gets the interface pointers
2. Invite:      Makes the invite session call.
******************************************************************************/

class CMessengerSessionImpl
{
private:
         // MessengerAPI.Messenger Object
    IMessenger* m_pIMessenger;
    // MessengerPrivate.MsgrSessionManager  
    IMsgrSessionManager* m_pISessionMgr;
public:
    CMessengerSessionImpl()
    {
    // MessengerAPI.Messenger Object
         m_pIMessenger = NULL;
         // MessengerPrivate.MsgrSessionManager
         m_pISessionMgr = NULL;
    }

    ~CMessengerSessionImpl()
    {
        if(m_pIMessenger)
        {
            m_pIMessenger->Release();
        }
        if(m_pISessionMgr)
        {
            m_pISessionMgr->Release();
        }
    }
    
    HRESULT Initialize()
    {
        // Session manager
        hr = CoCreateInstance(CLSID_MsgrSessionManager,NULL,CLSCTX_LOCAL_SERVER,
                        IID_MsgrSessionManager, (LPVOID *)&m_pISessionMgr);

        if(SUCCEEDED(hr))
        {
            // Messenger client api
            hr = CoCreateInstance(CLSID_Messenger,NULL,CLSCTX_LOCAL_SERVER,
                IID_IMessenger, (LPVOID *)&m_pIMessenger);
        }
        return hr;
    }
    HRESULT Invite(BSTR bstrSigninName, BSTR bstrServiceID, BSTR bstrAppGUID, BSTR bstrContextData)
    {
        // Get the Contact
        HRESULT hr=E_POINTER;
        IDispatch** ppContact;
        // Get the Messenger Contact object
        hr = m_pIMessenger->GetContact(bstrSigninName, bstrServiceID, ppContact);
        if(SUCCEEDED(hr))
        {
        IDispatch** ppSession;
        // Create a session object using session manager
        hr = m_pISessionMgr->CreateSession(ppSession);
        if(SUCCEEDED(hr))
        {
            IMsgrSession* pIMsgrSession;
            HRESULT hr = (*ppSession)->QueryInterface(IID_IMsgrSession, (void **) &pIMsgrSession);
            if(SUCCEEDED(hr))
            {
            // Set the application id eg. "{44BBA842-CC51-11CF-AAFA-00AA00B6015C}" for netmeeting
                hr = pIMsgrSession->put_Application(bstrAppGUID);
                if(SUCCEDED(hr))
                {
                    hr = pIMsgrSession->Invite(bstrContextData, *ppContact);
                }
            }
            (*ppSession)->Release();
        }
        if(*ppContact)
        {
            (*ppContact)->Release();
        }
        // Work on session object.
        // Release pIMsgrSession & hence session object when done.
    }
};

Notifications Fired From a Messenger Service

In the preceding example, the MsgrSession, MsgrSessionManager, and MessengerPriv objects are declared with types MsgrSession, MsgrSessionManager, and MessengerPrivate, respectively. The following tables show the events that are fired from the three interfaces in C++.

MsgrSession events reference

MsgrSessionManager events reference

MessengerPriv events reference

Additional Information

The Local Address of the MsgrSession Object

The IMsgrSession::LocalAddress of a MsgrSession object can be modified by using the IMsgrSession::LocalAddress property. This property does not change the physical IP address of the computer. It only modifies the data member within the object. Both the inviter and recipient can modify their own IMsgrSession::LocalAddress property by doing the following steps before launching a peer-to-peer application session.

1. The inviter creates a session object.
2. Before sending an invitation, if the inviter wants to send a specific local address, the inviter must set the IMsgrSession::LocalAddress property.
3. Inviter sends an invitation to the recipient.
4. Before the recipient accepts the invitation, the recipient can set the IMsgrSession::LocalAddress property.

After the IMsgrSession::LocalAddress property of the MsgrSession object has been set, if the inviter or recipient retrieves the IMsgrSession::RemoteAddress property, the IMsgrSession::LocalAddress set by either person will be retrieved.

Note  It is not necessary for either the inviter or recipient to set the IMsgrSession::LocalAddress property of their respective MsgrSession objects. By default, the IMsgrSession::LocalAddress property is assigned the local IP of each user's computer.

Related Topics

• Windows Messenger
• Messenger Lock and Key API