Platform SDK: DirectX

Supporting External Lobby Launching

The basic steps in recognizing a lobby launch and becoming part of an application session are as follows:

[C++]
  1. At startup, create an IDirectPlayLobby3 interface using the CoCreateInstance function.
  2. Call the IDirectPlayLobby3::GetConnectionSettings method. (Normally you would call it twice, once to retrieve the necessary buffer size, and again after the buffer has been allocated.) If the method returns DPERR_NOTLOBBIED, the application was not launched by a lobby but was presumably executed by the user in the normal way. Proceed with the code path that allows the user to connect to or create a non-lobbied session. If GetConnectionSettings succeeds, it returns a DPLCONNECTION structure with the connection settings (including the session description) established by the lobby. You can make changes by using IDirectPlayLobby3::SetConnectionSettings.
  3. Call IDirectPlayLobby3::ConnectEx to create or join the application session. (The application knows whether it is to create or join a session by examining DPLCONNECTION.dwFlags.)
  4. Create a player, using the name information supplied in the DPLCONNECTION structure obtained in step 2.

At this point, the application can continue on the same code path as if the user had manually selected a connection, joined or created a session, and entered the name of the player to create.

The IDirectPlayLobby3 interface can be saved if the game will pass information back to the lobby (see Staying in Touch with the Lobby). Otherwise it can be discarded by using the Release method.

For more information and sample code, see the Duel (Lobby.c) and ChatConnect (Lobby.cpp) samples, and Tutorial 1: Connecting by Using the Lobby.

[Visual Basic]
  1. At startup, create a DirectPlayLobby3 object by using the DirectX7.DirectPlayLobbyCreate method.
  2. Call the DirectPlayLobby3.GetConnectionSettings method. If the method raises a DPERR_NOTLOBBIED error, the application was not launched by a lobby but was presumably executed by the user in the normal way. Proceed with the code path that allows the user to connect to or create a non-lobbied session. If GetConnectionSettings succeeds, it returns a DirectPlayLobbyConnection object representing the connection settings (including the session description) established by the lobby. You can make changes by using DirectPlayLobby3.SetConnectionSettings.
  3. Call DirectPlayLobby3.Connect to create or join the application session. (The application knows whether it is to create or join a session by examining the value returned by DirectPlayLobbyConnection.GetFlags.)
  4. Create a player, using the name information supplied in the DirectPlayLobbyConnection object obtained in step 2.

At this point, the application can continue on the same code path as if the user had manually selected a connection, joined or created a session, and entered the name of the player to create.

The DirectPlayLobby3 object can be saved if the game will pass information back to the lobby (see Staying in Touch with the Lobby).

Many lobbies launch the application and then go into a suspend mode, waiting for the application to terminate. DirectPlay notifies the lobby when the application it launched has terminated. For this reason it is important that the application launched by the lobby not launch another application. (However, a properly registered application can itself be run by a launcher. See Supporting Ripple Launching.)