DirectPlay4.Receive

The DirectPlay4.Receive method retrieves a message from the message queue.

object.Receive(fromPlayerId As Long, _
    toPlayerId As Long, _
    flags As CONST_DPRECEIVEFLAGS) As DirectPlayMessage  

Parameters

object

Object expression that resolves to a DirectPlay4 object.

fromPlayerId

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

toPlayerId

Variable that will be set to the receiver's player ID when this method returns. If the DPRECEIVE_TOPLAYER flag is specified, this parameter must be initialized with the player ID before calling the method.

flags

Flags from the CONST_DPRECEIVEFLAGS enumeration indicating how messages should be received. One or more of the following control flags can be set. By default (flags = 0), the first available message will be retrieved.

DPRECEIVE_ALL

Returns the first available message, removing it from the message queue. This is the default.

DPRECEIVE_PEEK

Returns a message as specified by the other flags, but does not remove it from the message queue.

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 toPlayerId and (2) sent from the player specified by fromPlayerId. Both conditions must be met.

If only DPRECEIVE_TOPLAYER is specified, Receive will only return messages sent to the player specified by toPlayerId.

If only DPRECEIVE_FROMPLAYER is specified, Receive will only return messages sent from the player specified by fromPlayerId.

If neither DPRECEIVE_TOPLAYER nor DPRECEIVE_FROMPLAYER is set, Receive will return the first available message.

Return Values

If the method succeeds, it returns a DirectPlayMessage object whose methods can be used to retrieve the contents of the message, or Nothing if there are no messages pending.

Error Codes

If the method fails, an error is raised and Err.Number may be set to one of the following values:

Remarks

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 fromPlayerId and toPlayerId are equal.

If DPSESSION_NOMESSAGEID is specified in the session description, the fromPlayerId will always be 0xFFFFFFFF and the toPlayerId 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

DirectPlay4.Send