Microsoft DirectX 9.0

IDirectPlay8Client::CancelAsyncOperation Method

Cancels asynchronous requests.


HRESULT CancelAsyncOperation(      

    const DPNHANDLE hAsyncHandle,     const DWORD dwFlags );


[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 requests 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 0 to cancel all pending calls to the server.
[in] Flag that specifies which asynchronous request to canceled. You can set one of the following flags.
Cancel all asynchronous IDirectPlay8Client::EnumHosts requests. A single IDirectPlay8Client::EnumHosts request can be canceled by specifying the handle returned from the IDirectPlay8Client::EnumHosts method.
Cancel an asynchronous IDirectPlay8Client::Connect request.
Cancel an asynchronous IDirectPlay8Client::Send request.
Cancel all asynchronous IDirectPlay8Client::Send requests.
Cancel low-priority asynchronous IDirectPlay8Client::Send requests.
Cancel normal-priority asynchronous IDirectPlay8Client::Send requests.
Cancel high-priority asynchronous IDirectPlay8Client::Send requests.
Cancel all asynchronous requests.

Return Value

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

DPNERR_CANNOTCANCELThe operation could not be canceled.
DPNERR_INVALIDFLAGSThe flags passed to this method are invalid.
DPNERR_INVALIDHANDLEThe handle specified is invalid.
DPNSUCCESS_PENDINGAn asynchronous operation has reached the point where it is successfully queued.


Many methods of the IDirectPlay8Client 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 be run asynchronously return a 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.

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

You can cancel a send by providing the handle returned from IDirectPlay8Client::Send method. A DPN_MSGID_SEND_COMPLETE system message is still posted to the applications message handler for each asynchronous send that is sent without the DPNSEND_NOCOMPLETE flag set. Sends that are canceled by this method return DPNERR_USERCANCEL in their 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.

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.

© 2002 Microsoft Corporation. All rights reserved.