IDirectPlayLobby2::RunApplication

IDirectPlayLobby2::RunApplication

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 zero.

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 IDirectPlayLobby2::SendLobbyMessage and IDirectPlayLobby2::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 IDirectPlayLobby2::SetLobbyMessageEvent method.

Return Values

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

DPERR_CANTCREATEPROCESS

DPERR_GENERIC

DPERR_INVALIDINTERFACE

DPERR_INVALIDOBJECT

DPERR_INVALIDPARAMS

DPERR_OUTOFMEMORY

DPERR_UNKNOWNAPPLICATION

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 IDirectPlayLobby2 interface before it receives a DPLSYS_CONNECTIONSETTINGSREAD system message. The lobby client can either check IDirectPlayLobby2::ReceiveLobbyMessage in a loop until it is received, or supply a synchronization event.