IDirectPlayLobby3::RunApplication

The IDirectPlayLobby3::RunApplication method starts an application and passes to it all the information necessary to connect it to a session. This method is used by a lobby client.

HRESULT RunApplication(
  DWORD dwFlags,
  LPDWORD lpdwAppID,
  LPDPLCONNECTION lpConn,
  HANDLE hReceiveEvent
);

Parameters

dwFlags

Reserved; must be 0.

lpdwAppID

Pointer to a variable that will be filled with an ID identifying the application that was started. The lobby client must save this application ID for use on with any calls to the IDirectPlayLobby3::SendLobbyMessage and IDirectPlayLobby3::ReceiveLobbyMessage methods.

lpConn

Pointer to a DPLCONNECTION structure that contains all the information necessary to specify which application to start and how to get it connected to a session instance without displaying any user dialog boxes.

hReceiveEvent

Specifies a synchronization event that will be set when a lobby message is received. This event can be changed later by using the IDirectPlayLobby3::SetLobbyMessageEvent method.

Return Values

Returns DP_OK if successful, or one of the following error values otherwise:

Remarks

This method will return after the application process has been created. The lobby client will receive a system message indicating the status of the application. If the lobby client is starting an application that will be hosting a session, it should wait until it receives a DPLSYS_DPLAYCONNECTSUCCEEDED system message before starting the other applications that will be joining the session. If the application was unable to create or join a session, a DPLSYS_DPLAYCONNECTFAILED message will be generated. The lobby client will also receive a DPLSYS_CONNECTIONSETTINGSREAD system message when the application has read the connection settings and a DPLSYS_APPTERMINATED system message when the application terminates.

It is important that the lobby client not release its IDirectPlayLobby3 interface before it receives a DPLSYS_CONNECTIONSETTINGSREAD system message. The lobby client can either check IDirectPlayLobby3::ReceiveLobbyMessage in a loop until it is received, or supply a synchronization event.

Requirements

  Windows NT/2000: Requires Windows 2000.
  Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
  Header: Declared in dplobby.h.
  Import Library: Use dplayx.lib.

See Also

IDirectPlayLobby3::ReceiveLobbyMessage, IDirectPlayLobby3::GetConnectionSettings, IDirectPlayLobby3::SetLobbyMessageEvent