PDVMESSAGEHANDLER Prototype

DirectPlay

 
Microsoft DirectX 9.0 SDK Update (Summer 2003)

PDVMESSAGEHANDLER Prototype


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

Syntax

typedef HRESULT (CALLBACK *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 Value

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 view 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. When 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®.

Prototype Information

Headerdvoice.h
Import libraryNone
Minimum operating systems Windows 98, Pocket PC 2002


© 2003 Microsoft Corporation. All rights reserved.