An application retrieves the next message in the queue by calling IDirectPlay4::Receive.

If there is more than one local player—that is, more than one player has been created by this instance of the application—then the ID of the player for whom messages are desired must be passed to the Receive method in the lpidTo parameter, and the DPRECEIVE_TOPLAYER flag must be set.

In order to retrieve the message data, it is first necessary to allocate the right amount of memory. To determine the necessary buffer size, first call the method with the lpData parameter set to NULL, or pass in a pointer to an existing buffer of any size and set *lpdwDataSize to the current length. If there is a message waiting, but lpData is NULL or the buffer is not big enough, the method fails with DPERR_BUFFERTOOSMALL and returns the required amount of memory in *lpdwDataSize. Reallocate and try again.

Once the method succeeds and fills the buffer with the message data, *lpidFrom equals DPID_SYSMSG if this is a system message. If so, follow the steps outlined under Using System Messages. If not, follow the procedure in Using Player Messages.

For an example of this process, see the ReceiveMessages function in the Duel sample.

The DirectPlay4.Receive method retrieves the next message in the queue and returns a DirectPlayMessage object containing the message data. In addition, the method returns the ID of the sending player (DPID_SYSMSG if it is a system message) and the ID of the receiving player these are returned in variables that have been passed to the method.

If there is more than one local player—that is, more than one player has been created by this instance of the application—then the ID of the player for whom messages are desired must be passed to the Receive method in the toPlayerId parameter, and the DPRECEIVE_TOPLAYER flag must be set.

The following sample function retrieves all waiting messages:

' gObjDPlay is the DirectPlay4 object.
' gMyPlayerID is the ID for this player.

Sub ReceiveMessages
    Dim MsgCount as Long
    Dim MsgType as Long
    Dim FromPlayerID As Long
    Dim ToPlayerID As Long
    Dim dpMsg as DirectPlayMessage
 
    MsgCount = gObjDPlay.GetMessageCount(gMyPlayerID)
    For X% = 1 to MsgCount
        Set dpMsg = gObjDPlay.Receive(FromPlayerID, _
            ToPlayerID, DPRECEIVE_ALL)
        If FromPlayerID = DPID_SYSMSG Then
            MsgType = dpMsg.ReadLong()
           ' Process system message here
        Else
           'Process player message here
        End If
    Next X
End Sub

For more information on how to handle messages after receiving them, see the following topics:

• Using System Messages
• Using Player Messages
• Using Lobby Messages