IDirectPlay4::GetMessageQueue
IDirectPlay4 Interface
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.
Syntax
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 Value
Returns DP_OK if successful, or one of the following error values otherwise:
DPERR_INVALIDFLAGS DPERR_INVALIDPARAMS DPERR_INVALIDPLAYER DPERR_UNSUPPORTED 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.
See Also
Top of Page
© 1998 Microsoft Corporation. All rights reserved. Terms of Use.