IDirectPlay4::CancelMessage

The IDirectPlay4::CancelMessage method is used to cancel a specific message (or all the messages) that are still in the send queue. CancelMessage applies only to asynchronous messages.

In order to cancel a specific message, the application must obtain and save the message ID returned by the IDirectPlay4::SendEx method.

Messages that have left the message queue and are partially sent cannot be canceled. A message sent to a group cannot be canceled after it has been sent to at least one member of the group.

Canceling a message still generates a DPMSG_SENDCOMPLETE system message indicating the message was canceled.

HRESULT CancelMessage(
  DWORD dwMsgID,
  DWORD dwFlags
);

Parameters

dwMsgID

ID of the specific message to be canceled. This ID is returned when the message is sent using IDirectPlay4::SendEx. Specify 0 to cancel all messages.

dwFlags

This parameter is reserved. Must be 0.

Return Values

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

This method returns DPERR_CANCELFAILED if the message cannot be canceled. This method returns DPERR_UNKNOWNMESSAGE if the ID of the message to be canceled is invalid. It returns DP_OK if there are no messages in the send queue.

Remarks

If the DirectPlay Protocol was specified in the session description, then all the options on CancelMessage are available. Otherwise, an application should call GetCaps to determine what options the service provider has implemented.

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::SendEx, IDirectPlay4::Send, IDirectPlay4::GetMessageQueue, DPMSG_SENDCOMPLETE, IDirectPlay4::CancelPriority