Implementing a Lobbied Application Callback Message Handler

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

A message identifier (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 to be able to handle the following four lobbied application-specific messages.

Most of these messages are generated by the lobbied application object in response to changes in the connection, or when the lobbied application requests connection information. The exception is DPL_MSGID_RECEIVE. This message is used to pass data directly from the lobby client to the game application. 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 lobbied application object when the lobby client calls IDirectPlay8LobbyClient::ConnectApplication to connect an application to a session. The associated DPL_MSGID_CONNECT structure includes the following information.

A connection ID. Use this ID when your application needs to send data to the lobby client with IDirectPlay8LobbiedApplication::Send, or update the session status with IDirectPlay8LobbiedApplication::UpdateStatus.
Lobby connection data.
An optional connection context value. You can set the connection context value when you handle the DPL_MSGID_CONNECT message. If this value is set for a connection, it will be returned whenever you receive a message from that connection in the pvConnectionContext parameter. This is a useful value to set if your application has multiple connections and a common lobbied application message handler.

DPL_MSGID_CONNECTION_SETTINGS

DirectPlay sends this message whenever an associated lobby client calls its IDirectPlay8LobbyClient::SetConnectionSettings method to modify the session connections. The associated DPL_MSGID_CONNECTION_SETTINGS structure contains the updated connection information.

DPL_MSGID_DISCONNECT

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

DPL_MSGID_RECEIVE

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

For more information, see A Sample Lobbied Application Message Handler.