IDirectPlay4::GetMessageQueue

The IDirectPlay4::GetMessageQueue method determines how many messages are in the send or receive queue. By monitoring the status of the send queue, an application can regulate how many messages to send to other players in the session based on the bandwidth of the underlying network.

Note that the queue size on a machine is for all players in the session on that machine, not for an individual player, if there is more than one player in the session on a single machine.

HRESULT GetMessageQueue(
  DPID idFrom,
  DPID idTo,
  DWORD dwFlags,
  LPDWORD lpdwNumMsgs,
  LPDWORD lpdwNumBytes
);

Parameters

idFrom

ID of the player sending the messages whose queue status is desired. Zero returns information about all sent messages. If idTo is also specified, only information about messages that are both from the player with idFrom and to the player with idTo is returned.

idTo

ID of the player sent the messages whose queue status is desired. Zero returns information about all sent messages. If idFrom is also specified, only information about messages that are both from the player with idFrom and to the player with idTo is returned. Note that you cannot specify a group ID for idTo.

dwFlags

Determines what type of information about the queue to obtain. Default (dwFlags = 0) returns information about the send queue. Can be one, and only one, of the following values:

DPMESSAGEQUEUE_SEND

Retrieves information about the send queue.

DPMESSAGEQUEUE_RECEIVE

Retrieves information about the receive queue.

lpdwNumMsgs

Pointer to a DWORD that will be filled with the number of messages in the queue. If NULL, no value is returned.

lpdwNumBytes

Pointer to a DWORD that will be filled with the total number of bytes in the queue. If NULL, no value is returned.

Return Values

Returns DP_OK if successful, or one of the following error values otherwise:

Returns DPERR_INVALIDPLAYER if you check the receive queue (DPMESSAGEQUEUE_RECEIVE) while specifying idTo for a remote player. Returns DPERR_INVALIDPLAYER if you check the send queue (DPMESSAGEQUEUE_SEND) while specifying idFrom for a remote player. Returns DPERR_INVALIDFLAGS if you specify both the receive queue and the send queue flags (dwFlags = DPMESSAGEQUEUE_RECEIVE|DPMESSAGEQUEUE_SEND). Returns DPERR_UNSUPPORTED if you attempt to check the send queue when DirectPlay protocol is not turned on and the service provider does not support checking the send queue.

Remarks

You cannot check message queues on remote machines.

Requirements

  Windows NT/2000: Requires Windows 2000.
  Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
  Header: Declared in dplay.h.
  Import Library: Use dplayx.lib.

See Also

IDirectPlay4::Send, IDirectPlay4::SendEx