Implementing a Callback Function in DirectPlay and DirectPlay Voice

Microsoft® DirectPlay® and DirectPlay Voice both require you to implement and register several callback functions to handle the events raised by DirectPlay. DirectPlay is multithreaded and will raise multiple events concurrently. Therefore, in order to correctly and reliably access data in DirectPlay callbacks, you are required to implement a method of multithreading synchronization. This is known as making your callback re-entrant or threadsafe.

Callback Function Structure

The structure of the callback follows standard Microsoft Win32® application programming interface (API) programming guidelines.

HRESULT WINAPI Callback(
  PVOID pvUserContext,
  DWORD dwMessageType,
  PVOID pMessage );

pvUserContext is the a context value you supply when you register the callback function with DirectPlay. If you pass this value to DirectPlay when you register your callback, the context value will be returned when DirectPlay invokes your callback.

dwMessageType is one of the identifier (ID) values passed to your callback by DirectPlay.

pMessage will contain the message passed by DirectPlay.

Registering Your Callback

DirectPlay networking callback functions are of type PFNDPNMESSAGEHANDLER. Depending on the type of networking session, you register the address of your callback function with IDirectPlay8Peer::Initialize, IDirectPlay8Client::Initialize, or IDirectPlay8Server::Initialize. If you are registering a DirectPlay voice callback function, register the address of your callback with IDirectPlayVoiceClient::Initialize or IDirectPlayVoiceServer::Initialize, depending on the type of DirectPlay voice session you want to create.

The following code snippet demonstrates how to register a callback function with the IDirectPlay8Peer interface.

HRESULT WINAPI Callback(PVOID, DWORD, PVOID);

IDirectPlay8Peer* pdp8Peer;



// Get the server interface
hr = CoCreateInstance( CLSID_DirectPlay8Peer, ...)
...

// Register the callback
hr = pdp8Peer->Initialize(NULL, Callback, 0);