Platform SDK: DirectX |
The IDirectPlay4::Receive method retrieves a message from the message queue.
HRESULT Receive( LPDPID lpidFrom, LPDPID lpidTo, DWORD dwFlags, LPVOID lpData, LPDWORD lpdwDataSize );
If only DPRECEIVE_TOPLAYER is specified, Receive will only return messages sent to the player specified by lpidTo.
If only DPRECEIVE_FROMPLAYER is specified, Receive will only return messages sent from the player specified by lpidFrom.
If neither DPRECEIVE_TOPLAYER nor DPRECEIVE_FROMPLAYER is set, Receive will return the first available message.
Returns DP_OK if successful, or one of the following error values otherwise:
DPERR_BUFFERTOOSMALL |
DPERR_GENERIC |
DPERR_INVALIDOBJECT |
DPERR_INVALIDPARAMS |
DPERR_INVALIDPLAYER |
DPERR_NOMESSAGES |
Any message received from a player ID defined as DPID_SYSMSG is a system message used to notify the application of a change in the session. In those cases, the lpData of system messages should be cast to DPMSG_GENERIC and the dwType member should be examined to see what specific system message it is.
Messages that were sent to a player ID defined as DPID_ALLPLAYERS or to a group ID still appear to come from the sending player ID. An application will only receive messages directed to a local player. A player cannot receive a message in which the values pointed to by lpidFrom and lpidTo are equal.
If DPSESSION_NOMESSAGEID is specified in the session description, the lpidFrom will always be 0xFFFFFFFF and the lpidTo value is arbitrary.
All the service providers shipped with DirectPlay perform integrity checks on the data to protect against corruption. Any message retrieved using Receive is guaranteed to be free from corruption.
Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in dplay.h.
Import Library: Use dplayx.lib.