The message handler is a callback function that is used by the lobby client object to communicate with the lobby client. The lobby client message handler has three parameters that pass in the following information.

• A message ID that indicates the message type.
• A pointer to a message data block. You must cast this parameter to the structure that is used by the particular message.
• A pointer to an optional application-defined user-context data block.

The user context value is defined by the lobby client when it calls IDirectPlay8LobbyClient::Initialize. It can be used for such purposes as differentiating between messages that are sent from different objects. For more information about user-context values, see Using Player Context Values

Your message handler must be able to handle the following five lobby client-specific messages.

• DPL_MESSAGE_CONNECT
• DPL_MESSAGE_CONNECTION_SETTINGS
• DPL_MESSAGE_DISCONNECT
• DPL_MESSAGE_RECEIVE
• DPL_MESSAGE_SESSION_STATUS

Most of these messages are generated by the lobby client object in response to changes in the game status, or when the lobby client requests information. The exception is DPL_MESSAGE_RECEIVE. This message is used to pass data directly from the game application to the lobby client. See PFNDPNMESSAGEHANDLER for a complete description the message handler function.

Note  Microsoft® DirectPlay® message handlers must be written to work properly in a multithreaded environment, or your application may not function well.

DPL_MSGID_CONNECT

This message is sent by the lobby client following the launch of a lobbyable application. The message indicates that the application has been successfully connected. The associated DPL_MESSAGE_CONNECT structure holds a variety of information, including:

• A connection ID. Use this ID when your lobby client needs to send data to the application with IDirectPlay8LobbyClient::Send, or release the connection with IDirectPlay8LobbyClient::ReleaseApplication.
• Lobby connection data.
• An optional connection context value.

DPL_MSGID_CONNECTION_SETTINGS

This message is sent by DirectPlay whenever an associated lobbyable application calls its IDirectPlay8LobbiedApplication::SetConnectionSettings method to modify the session connections. The associated DPL_MESSAGE_CONNECTION_SETTINGS structure contains the updated connection information.

DPL_MSGID_DISCONNECT

This message is sent when the lobbyable application disconnects from the session by calling IDirectPlay8LobbiedApplication::Close. Your lobby client application should delete the connection from its list and free any data that is associated with the application.

DPL_MSGID_RECEIVE

This message enables an application to pass data to the lobby client. DirectPlay passes the data block from the application to the lobby client in a DPL_MESSAGE_RECEIVE structure. It is up to the lobby client to process the data.

DPL_MSGID_SESSION_STATUS

This message is sent by DirectPlay whenever one of the following six changes in the session's status occurs.

• The session is connected.
• The session could not connect.
• The session has been disconnected.
• The session has been terminated.
• The session host has migrated.
• This computer has become the session host.

The type of status change is indicated by the value of the dwStatus field in the associated DPL_MESSAGE_SESSION_STATUS structure.

For more information, see A Sample Lobby Client Message Handler.