Tutorial 6: Handling Host Migration

A peer-to-peer session must have a host. This tutorial extends Tutorial 5 and discusses how to handle the situation that occurs when the host leaves the session. The complete sample code for this tutorial is included with the Microsoft® DirectX® software development kit (SDK) and can be found at (SDK root)\Samples\C++\DirectPlay\Tutorials\Tut02_HostMigration.

• User's Guide
• Host Migration
• Terminating the Application

Refer to the preceding tutorials for a discussion of the initial steps in the process:

• Tutorial 1: Creating a DirectPlay Object and Enumerating Service Providers
• Tutorial 2: Hosting a Session
• Tutorial 3: Enumerating Hosted Sessions
• Tutorial 4: Connecting to a Session
• Tutorial 5: Sending Messages to Other Peers

User's Guide

When you run this tutorial sample, a window opens and you have the choice to either Host or Connect.

If you choose Host:

1. A window will open and you should enter a session name. Select the Migrate Host box to allow host migration to take place in this session. Then click OK. Your session status will change to 'Hosting Session "YourSessionName".'
2. You can now choose to send a message or disconnect. If you choose to send a message, enter a text string and click Send. If you choose to disconnect, click Disconnect and the session ends.
3. Click Exit to end the sample

If you choose Connect:

1. The Connect to Session window will open and you should enter an Internet Protocol (IP) address and click Search. If any sessions are found at that address, they will be listed in the Detected Sessions box. Select a session and click Connect. If the address does not exist, a message box opens with an error message.
2. Once connected, your session status will change to 'Connected to Session "YourSessionName".' You can now choose to send a message or disconnect. If you choose to send a message, enter a text string and click Send. If you choose to disconnect, click Disconnect.
3. Click Exit to end the sample.

You can run this sample twice—once to host a session and once to connect. When connecting, enter your computer's IP address. When connected, you can send messages between the host and the client application. To test host migration, close the host application. The client application's session status will change to 'Hosting Session "YourSessionName".'.

Host Migration

In a peer-to-peer game, there is nothing to prevent the session host from leaving before the game is finished. This situation typically occurs when the player decides to leave the game but might also result from a network problem that disconnects the player. Because a game must have a host, there are two possible ways to deal with this problem: stop the game, or choose a new host. The process of choosing a new host in the middle of a game is referred to as "host migration."

When a session host initially advertises a session, it must choose whether to allow host migration. If host migration is not allowed, the game terminates when the host leaves. To enable host migration in a session, the original session host must set the DPNSESSION_MIGRATE_HOST flag in the dwFlag member of the DPN_APPLICATION_DESC structure that is passed to the IDirectPlay8Peer::Host. See Tutorial 2: Hosting a Session for more discussion of how to host a session.

If host migration is enabled, the host can still force the session to terminate by calling the IDirectPlay8Peer::TerminateSession method. Otherwise, Microsoft DirectPlay® selects a new session host. When the host migrates, each remaining member's DirectPlay message handler receives a DPN_MSGID_HOST_MIGRATE message. The associated structure includes the identifier of the new host, which may be any remaining player in the session including you.

The following excerpt from the tutorial sample illustrates how to handle DPN_MSGID_HOST_MIGRATE.

HRESULT WINAPI DirectPlayMessageHandler(void *pvUserContext, DWORD dwMessageId, void *pMsgBuffer)
{
switch( dwMessageId )
{
.
.
.
  case DPN_MSGID_HOST_MIGRATE:
        {
            PDPNMSG_HOST_MIGRATE    pHostMigrateMsg;

            pHostMigrateMsg = (PDPNMSG_HOST_MIGRATE) pMsgBuffer;

            // See if you are the new host.
            if( pHostMigrateMsg->dpnidNewHost == g_dpnidLocalPlayer)
                //You are the New Host;
            else
                //The new host is pHostMigrateMsg->dpnidNewHost

            break;
       }
}
}

Terminating the Application

If a DirectPlay peer object was successfully initialized, you should first close the object by calling IDirectPlay8Peer::Close; then release all active objects and terminate the application. See Tutorial 1 for further discussion.