IDirectPlay4::Receive

The IDirectPlay4::Receive method retrieves a message from the message queue.

HRESULT Receive(
  LPDPID lpidFrom,
  LPDPID lpidTo,
  DWORD dwFlags,
  LPVOID lpData,
  LPDWORD lpdwDataSize
);

Parameters

lpidFrom

Address of a variable to receive the sender's player ID. If the DPRECEIVE_FROMPLAYER flag is specified, this variable must be initialized with the player ID before calling this method.

lpidTo

Address of a variable to receive the receiver's player ID. If the DPRECEIVE_TOPLAYER flag is specified, this variable must be initialized with the player ID before calling this method.

dwFlags

One or more of the following control flags can be set. By default (dwFlags = 0), the first available message will be retrieved.

DPRECEIVE_ALL

Returns the first available message. This is the default.

DPRECEIVE_PEEK

Returns a message as specified by the other flags, but does not remove it from the message queue. This flag must be specified if lpData is NULL.

DPRECEIVE_TOPLAYER and DPRECEIVE_FROMPLAYER

If both DPRECEIVE_TOPLAYER and DPRECEIVE_FROMPLAYER are specified, Receive will only return messages that are: 1) sent to the player specified by lpidTo and 2) sent from the player specified by lpidFrom. Note that both conditions must be met.

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.

lpData

Pointer to a buffer where the message data is to be written. Set this parameter to NULL to request only the size of data. The lpdwDataSize parameter will be set to the size required to hold the data. If the message came from player ID DPID_SYSMSG, the application should cast lpData to DPMSG_GENERIC and check the dwType member to see what type of system message it is before processing it.

lpdwDataSize

Pointer to a DWORD that is initialized to the size of the buffer before calling this method. After the method returns, this parameter will be set to the number of bytes copied into the buffer. If the buffer was too small (DPERR_BUFFERTOOSMALL), then this parameter will be set to the buffer size required.

Return Values

Returns DP_OK if successful, or one of the following error values otherwise:

Remarks

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.

Requirements

  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.

See Also

DPMSG_GENERIC, IDirectPlay4::Send