DirectPlayLobby is a standard way for custom matchmaking lobby solutions to interact with DirectPlay applications. A custom lobby solution will usually include some kind of lobby client software, which runs on the user's computer and communicates with a lobby server. The lobby client implements the user interface through which a user can locate other players to engage in a gaming session. When a group of players has decided to start a session, the lobby client starts the application on each of their computers and supplies them with the information they need to select a service provider and connect to the session. A DirectPlay application that can be started and connected through the DirectPlayLobby API function is referred to as lobby-able. DirectPlayLobby also has methods that allow an application to communicate with the lobby client while the session is in progress, and to inform the lobby client when the application has terminated.
The lobby client can determine which DirectPlay applications the user has by using the IDirectPlayLobby::EnumLocalApplications method. It can also determine which service providers are available by using the DirectPlayEnumerate function. After a user decides to join a session and the lobby client verifies the availability of the necessary application and service provider, the lobby client can start the application and connect it to the session by using the IDirectPlayLobby::RunApplication method. In this call, the lobby client specifies the application to run, the DirectPlay service provider to use, the information the service provider will need to connect to the session (by using the IDirectPlayLobby::CreateAddress and IDirectPlayLobby::EnumAddress methods), and the name the user is known by within the lobby environment. DirectPlayLobby locates the application executable and starts it with the appropriate command line switches. DirectPlayLobby also stores all the service provider and connection information.
The lobby client and application can communicate by using the IDirectPlayLobby::SendLobbyMessage and IDirectPlayLobby::ReceiveLobbyMessage methods. The lobby client sets up an event to occur when a message is received in the IDirectPlayLobby::RunApplication method. The application sets up an event by using the IDirectPlayLobby::SetLobbyMessageEvent method. By using this method, the lobby can change its event, too.
For an application to be lobby-able, it must also create an IDirectPlayLobby interface. The application can examine the connection parameters that the lobby client provided by using the IDirectPlayLobby::GetConnectionSettings method, and then modify them by using the IDirectPlayLobby::SetConnectionSettings method. The application then calls IDirectPlayLobby::Connect, which uses the connection settings and connects to the session. During this time, the lobby client will receive system messages indicating the progress of starting the application.
The application should then obtain the player name data (by using IDirectPlayLobby::GetConnectionSettings) and assign it to the player being created. The IDirectPlayLobby::Connect call (if successful) takes the place of the following series of calls:
1DirectPlayEnumerate (the lobby specifies the service provider)
2DirectPlayCreate (IDirectPlayLobby::Connect will create a DirectPlay object)
3IDirectPlay2::EnumSessions (the lobby also specifies the session information so the user doesn't have to pick one)
4IDirectPlay2::Open (the session will open automatically)
If IDirectPlayLobby::GetConnectionSettings returns the DPERR_NOTLOBBIED error, the starting of the application was not initiated by a lobby client, and the application should go through its normal DirectPlay initialization.