IDirectPlay4::Receive
IDirectPlay4 Interface
Retrieves a message from the message queue.
Syntax
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 IDirectPlay4::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 IDirectPlay4::Receive. It is best to keep reallocating memory until a DPERR_BUFFERTOOSMALL error is not received.
Return Value
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
Top of Page
© 1998 Microsoft Corporation. All rights reserved. Terms of Use.