---

IDirectPlay3::Receive

IDirectPlay3 Interface

Retrieves a message from the message queue.

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

Parameters

lpidFrom

Pointer to a DPID that will be set to the sender's player ID when this method returns. If the DPRECEIVE_FROMPLAYER flag is specified, this variable must be initialized with the player ID before calling this method.

lpidTo

Pointer to a DPID that will be set to the receiver's player ID when this method returns. 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. The message order in the receive queue can change between calls to IDirectPlay3::Receive. Therefore, it is possible to get a DPERR_BUFFERTOOSMALL error again even after the application has allocated the memory requested from the previous call to IDirectPlay3::Receive. It is best to keep reallocating memory until a DPERR_BUFFERTOOSMALL error is not received.

Return Values

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

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.

See Also

DPMSG_GENERIC, IDirectPlay3::Send

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

Top of Page