PDVMESSAGEHANDLER

PDVMESSAGEHANDLER is an application-defined callback function used by the IDirectPlayVoiceClient and IDirectPlayVoiceServer interfaces to send messages to the user.

typedef HRESULT (FAR PASCAL *PDVMESSAGEHANDLER)( 
  LPVOID pvUserContext,
  DWORD dwMessageType,
  LPVOID lpMessage
);

Parameters

pvUserContext

Pointer to the application-defined structure that will be passed to this callback function. This is defined in the lpUserContext parameter of the IDirectPlayVoiceServer::Initialize and IDirectPlayVoiceClient::Initialize methods.

dwMessageType

One of the following message types.

DVMSGID_CONNECTRESULT

DVMSGID_CREATEVOICEPLAYER

DVMSGID_DELETEVOICEPLAYER

DVMSGID_DISCONNECTRESULT

DVMSGID_GAINFOCUS

DVMSGID_HOSTMIGRATED

DVMSGID_INPUTLEVEL

DVMSGID_LOCALHOSTSETUP

DVMSGID_LOSTFOCUS

DVMSGID_OUTPUTLEVEL

DVMSGID_PLAYEROUTPUTLEVEL

DVMSGID_PLAYERVOICESTART

DVMSGID_PLAYERVOICESTOP

DVMSGID_RECORDSTART

DVMSGID_RECORDSTOP

DVMSGID_SESSIONLOST

DVMSGID_SETTARGETS

lpMessage

Structure containing message information.

Return Values

See the documentation for the individual messages for appropriate return values. Unless otherwise noted, this function should return DV_OK.

Remarks

When implementing this callback function, you must first look at the message type returned in the dwMessageType parameter and then cast the message structure (lpMessage) to that type to obtain message information. Some messages don't have a defined structure because they have no parameters. For these messages, the lpMessage parameter is NULL.

Note  This function may be called on multiple different threads at the same time. It must thus be threadsafe and reentrant.

All message structures have the same name as the corresponding message types except the prefix is DVMSG_ instead of DVMSGID_. For example, the structure for DVMSGID_RECORDSTART is DVMSG_RECORDSTART.

The structure sent to the message handler is valid only for the duration of the call. Therefore, if you want to use any of the information passed into the function after the handler function has returned you must make a copy of the data.

Callback messages from the same player are serialized. Once you receive a message from a player, you will not receive another until you have handled the first message, and the callback function has returned.

Only messages that are specified in the message mask through a call to the IDirectPlayVoiceClient::Initialize, IDirectPlayVoiceServer::Initialize, IDirectPlayVoiceClient::SetNotifyMask and IDirectPlayVoiceServer::SetNotifyMask methods are sent to this callback function.

The DVMSGID_GAINFOCUS and DVMSGID_LOSTFOCUS message structures have not been implemented in this release of Microsoft® DirectPlay® .

Requirements

  Windows NT/2000/XP: Available as a redistributable for Windows 2000 and later.
  Windows 98/Me: Available as a redistributable for Windows 98 and later.
  Header: Declared in Dvoice.h.