HRESULT Receive(LPDPID lpidFrom, LPDPID lpidTo,
DWORD dwFlags, LPVOID lpData, LPDWORD lpdwDataSize);
Retrieves a message from the message queue.
·Returns DP_OK if successful, or one of the following error values otherwise:
lpidFrom
Address of a variable 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
Address of a variable 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. Both DPRECEIVE_TOPLAYER and DPRECEIVE_FROMPLAYER can be specified, in which case this method returns whichever message is encountered first.
Returns the first available message. This is the default.
Returns the first message from the player ID that the lpidFrom parameter points to. System messages come from player ID DPID_SYSMSG.
Returns a message as specified by the other flags, but does not remove it from the message queue.
Returns the first message intended for the player ID that the lpidTo parameter points to.
lpData
Address of 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
Address of a variable that is initialized to the size of the buffer before calling this method. After the method returns, this parameter will be set to the size, in bytes, of the group data. 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 IDirectPlay2::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 IDirectPlay2::Receive. It is best to keep reallocating memory until a DPERR_BUFFERTOOSMALL error is not received.
Any message received from player ID DPID_SYSMSG is a system message generated by the host. 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 player ID DPID_SYSMSG as a way to broadcast them to all players or to a group ID to send them to all the players in the group still appear to come from the sending player ID. An application will receive only 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 and lpidTo parameters are meaningless.
All the service providers shipped with DirectPlay perform integrity checks on the data to protect against corruption. Any message received will be verified, and if data corruption is detected, it will either be thrown away (if it was sent nonguaranteed) or it will be retransmitted (if it was sent guaranteed).