IDirectPlay8Peer::CancelAsyncOperation Method

Cancels asynchronous requests. For instance, several methods of the IDirectPlay8Peer interface run asynchronously by default. Depending on the situation, you might want to cancel requests before they are processed. All the methods of this interface that can run asynchronously return an hAsyncHandle parameter.

Specific requests are canceled by passing the hAsyncHandle of the request in this method's hAsyncHandle parameter. You can cancel all pending asynchronous operations by calling this method, specifying NULL in the hAsyncHandle parameter, and specifying DPNCANCEL_ALL_OPERATIONS in the dwFlags parameter. If a specific handle is provided to this method, no flags should be set.

Syntax

HRESULT CancelAsyncOperation(      
    const DPNHANDLE hAsyncHandle,
    const DWORD dwFlags
);

Parameters

hAsyncHandle

[in] Handle of the asynchronous operation to stop. You receive this handle when you call one of several methods that support asynchronous operations. This value can be set to NULL to stop all operations or a particular type of asynchronous request. If a particular handle is specified, the dwFlags parameter must be 0. If one of the DPNCANCEL_PLAYER_SENDS flags is specified in the dwFlags parameter, hAsyncHandle must be set to a player's DPNID.

dwFlags

[in] Flag that specifies which asynchronous request is to be canceled. One of the following flags can be set.

DPNCANCEL_ENUM

Cancel all asynchronous IDirectPlay8Peer::EnumHosts requests. A single IDirectPlay8Peer::EnumHosts request can be canceled by specifying the handle returned from the IDirectPlay8Peer::EnumHosts method.

DPNCANCEL_CONNECT

Cancel an asynchronous IDirectPlay8Peer::Connect request.

DPNCANCEL_SEND

Cancel an asynchronous IDirectPlay8Peer::SendTo request.

DPNCANCEL_PLAYER_SENDS

Cancel all asynchronous IDirectPlay8Peer::SendTo requests for the player specified in the hAsyncHandle parameter.

DPNCANCEL_PLAYER_SENDS_PRIORITY_LOW

Cancel low-priority asynchronous IDirectPlay8Peer::SendTo requests for the player specified in the hAsyncHandle parameter.

DPNCANCEL_PLAYER_SENDS_PRIORITY_NORMAL

Cancel normal-priority asynchronous IDirectPlay8Peer::SendTo requests for the player specified in the hAsyncHandle parameter.

DPNCANCEL_PLAYER_SENDS_PRIORITY_HIGH

Cancel high-priority asynchronous IDirectPlay8Peer::SendTo requests for the player specified in the hAsyncHandle parameter.

DPNCANCEL_ALL_OPERATIONS

Cancel all asynchronous IDirectPlay8Peer::Connect, IDirectPlay8Peer::SendTo, and IDirectPlay8Peer::EnumHosts operations.

Return Value

Returns S_OK if successful, or one of the following error values.

DPNERR_CANNOTCANCEL	The operation could not be canceled.
DPNERR_INVALIDFLAGS	The flags passed to this method are invalid.
DPNERR_INVALIDHANDLE	The handle specified is invalid.

Remarks

You can use this method to cancel an asynchronous operation for the IDirectPlay8Peer::Connect, IDirectPlay8Peer::SendTo, and IDirectPlay8Peer::EnumHosts methods. Microsoft® DirectPlay® does not support cancellation of other asynchronous operations.

You can cancel a send request by providing the handle returned from the IDirectPlay8Peer::SendTo method. A DPN_MSGID_SEND_COMPLETE, or DPN_MSGID_CONNECT_COMPLETE system message is still posted to the application's message handler for each asynchronous send request that is sent without the DPNSEND_NOCOMPLETE flag set. Send requests that are canceled by this method return DPNERR_USERCANCEL in the hResultCode member of the DPN_MSGID_SEND_COMPLETE message.

If you set the DPNCANCEL_ALL_OPERATIONS, DPNCANCEL_CONNECT, DPNCANCEL_SEND, or DPNCANCEL_ENUM flags in dwFlags, DirectPlay will attempt to cancel all matching operations. This method will return an error if any attempted cancellation fails, even though some cancellations may have been successful.

If you set one of the DPNCANCEL_PLAYER_SENDS flags in dwFlags, you must specify a player's DPNID in hAsyncHandle. This will cancel all pending IDirectPlay8Peer::SendTo requests where the DPNID specified in the dpnid parameter matches the value set in the hAsyncHandle parameter.

Note  The completion message might not arrive until after this method returns. Do not assume that the operation has been terminated until you have received a DPN_MSGID_SEND_COMPLETE, DPN_MSGID_CONNECT_COMPLETE, or DPN_MSGID_ASYNC_OP_COMPLETE message.