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\Multimedia\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

Note  The error handling code for the examples in this document has been deleted for clarity. See the tutorial sample for a complete version of the code.

User's Guide

When you run this tutorial sample, a Microsoft® MS-DOS® command window opens and you have the choice to either Host or Connect.

If you choose Host, do the following:

1. Enter a session name. A message prints on the screen telling you that you are "currently hosting."
2. Choose to Send or Exit. If you choose Send, you will be prompted to enter a text string. If you choose Exit, the session ends.

If you choose Connect, do the following:

1. Enter an IP address. If a session is found at that address, you will be connected. If the address does not exist or if no session is found at the address, the application prints error messages.
2. Once connected, choose Send or Exit. If you choose Send, you are prompted to enter a text string. If you choose Exit, the session ends.

You can run this sample twice—once to host a session and once to connect. When connecting, enter your computer's IP address. Once connected, you can send messages between the host and the client applications. To test host migration, close the host application. The client application is notified that it is the new host.

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, 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 *pvContext, DWORD dwMsgId, void *pMsgBuffer)
{
switch( dwMsgId )
{
.
.
.
  case DPN_MSGID_HOST_MIGRATE:
        {
            PDPNMSG_HOST_MIGRATE    pHostMigrateMsg;

            pHostMigrateMsg = (PDPNMSG_HOST_MIGRATE) pMsgBuffer;

            // See if we 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.