WINHTTP_STATUS_CALLBACK callback function (winhttp.h)

The WINHTTP_STATUS_CALLBACK type represents an application-defined status callback function.

WINHTTP_STATUS_CALLBACK WinhttpStatusCallback;

void WinhttpStatusCallback(
  [in] HINTERNET hInternet,
  [in] DWORD_PTR dwContext,
  [in] DWORD dwInternetStatus,
  [in] LPVOID lpvStatusInformation,
  [in] DWORD dwStatusInformationLength
)
{...}

[in] hInternet

The handle for which the callback function is called.

[in] dwContext

A pointer to a DWORD that specifies the application-defined context value associated with the handle in the hInternet parameter.

A context value can be assigned to a Session, Connect, or Request handle by calling WinHttpSetOption with the WINHTTP_OPTION_CONTEXT_VALUE option. Alternatively, WinHttpSendRequest can be used to associate a context value with a Request handle.

[in] dwInternetStatus

Points to a DWORD that specifies the status code that indicates why the callback function is called. This can be one of the following values:

Closing the connection to the server. The lpvStatusInformation parameter is NULL.

Successfully connected to the server. The lpvStatusInformation parameter contains a pointer to an LPWSTR that indicates the IP address of the server in dotted notation.

Connecting to the server. The lpvStatusInformation parameter contains a pointer to an LPWSTR that indicates the IP address of the server in dotted notation.

Successfully closed the connection to the server. The lpvStatusInformation parameter is NULL.

Data is available to be retrieved with WinHttpReadData. The lpvStatusInformation parameter points to a DWORD that contains the number of bytes of data available. The dwStatusInformationLength parameter itself is 4 (the size of a DWORD).

An HINTERNET handle has been created. The lpvStatusInformation parameter contains a pointer to the HINTERNET handle.

This handle value has been terminated. The lpvStatusInformation parameter contains a pointer to the HINTERNET handle. There will be no more callbacks for this handle.

The response header has been received and is available with WinHttpQueryHeaders. The lpvStatusInformation parameter is NULL.

Received an intermediate (100 level) status code message from the server. The lpvStatusInformation parameter contains a pointer to a DWORD that indicates the status code.

Successfully found the IP address of the server. The lpvStatusInformation parameter contains a pointer to a LPWSTR that indicates the name that was resolved.

Data was successfully read from the server. The lpvStatusInformation parameter contains a pointer to the buffer specified in the call to WinHttpReadData. The dwStatusInformationLength parameter contains the number of bytes read.

When used by WinHttpWebSocketReceive, the lpvStatusInformation parameter contains a pointer to a WINHTTP_WEB_SOCKET_STATUS structure, and the dwStatusInformationLength parameter indicates the size of lpvStatusInformation.

Waiting for the server to respond to a request. The lpvStatusInformation parameter is NULL.

An HTTP request is about to automatically redirect the request. The lpvStatusInformation parameter contains a pointer to an LPWSTR indicating the new URL. At this point, the application can read any data returned by the server with the redirect response and can query the response headers. It can also cancel the operation by closing the handle.

An error occurred while sending an HTTP request. The lpvStatusInformation parameter contains a pointer to a WINHTTP_ASYNC_RESULT structure. Its dwResult member indicates the ID of the called function and dwError indicates the return value.

Successfully sent the information request to the server. The lpvStatusInformation parameter contains a pointer to a DWORD indicating the number of bytes sent.

Looking up the IP address of a server name. The lpvStatusInformation parameter contains a pointer to the server name being resolved.

Successfully received a response from the server. The lpvStatusInformation parameter contains a pointer to a DWORD indicating the number of bytes received.

One or more errors were encountered while establishing a Secure (HTTPS) connection to the server. The lpvStatusInformation parameter contains a pointer to a DWORD that is a bitwise-OR combination of error values. For more information, see the description for lpvStatusInformation.

Sending the information request to the server. The lpvStatusInformation parameter is NULL.

The request completed successfully. The lpvStatusInformation parameter is the lpOptional value passed to WinHttpSendRequest (the initial request body), and the dwStatusInformationLength parameter indicates the number of such initial body bytes successfully written (the dwOptionalLength value passed to WinHttpSendRequest).

Data was successfully written to the server. The lpvStatusInformation parameter contains a pointer to a DWORD that indicates the number of bytes written.

When used by WinHttpWebSocketSend, the lpvStatusInformation parameter contains a pointer to a WINHTTP_WEB_SOCKET_STATUS structure, and the dwStatusInformationLength parameter indicates the size of lpvStatusInformation.

The operation initiated by a call to WinHttpGetProxyForUrlEx is complete. Data is available to be retrieved with WinHttpReadData.

The connection was successfully closed via a call to WinHttpWebSocketClose. The lpvStatusInformation parameter is NULL.

The connection was successfully shut down via a call to WinHttpWebSocketShutdown. The lpvStatusInformation parameter is NULL.

[in] lpvStatusInformation

A pointer to a buffer that specifies information pertinent to this call to the callback function. The format of these data depends on the value of the dwInternetStatus argument. For more information, see dwInternetStatus.

If the dwInternetStatus argument is WINHTTP_CALLBACK_STATUS_SECURE_FAILURE, then lpvStatusInformation points to a DWORD which is a bitwise-OR combination of one or more of the following values.

[in] dwStatusInformationLength

WINHTTP_CALLBACK_STATUS_REDIRECT status callbacks provide a dwStatusInformationLength value that corresponds to the character count of the LPWSTR pointed to by lpvStatusInformation.

None

The callback function must be threadsafe and reentrant because it can be called on another thread for a separate request, and reentered on the same thread for the current request. It must therefore be coded to handle reentrance safely while processing. When the dwInternetStatus parameter is equal to WINHTTP_CALLBACK_STATUS_HANDLE_CLOSING, the callback does not need to be able to handle reentrance for the same request, because this callback is guaranteed to be the last, and does not occur when other messages for this request are handled.

The status callback function receives updates on the status of asynchronous operations through notification flags. Notifications that indicate a particular operation is complete are called completion notifications, or just completions. The following table lists the six completion flags and the corresponding function that is complete when this flag is received.

Because callbacks are made during the processing of the request, the application should spend as little time as possible in the callback function to avoid degrading data throughput on the network. For example, displaying a dialog box in a callback function can be such a lengthy operation that the server terminates the request.

The callback function can be called in a thread context different from the thread that initiated the request.

Similarly, there is no callback thread affinity when you call WinHttp asynchronously: a call might start from one thread, but any other thread can receive the callback.

WinHTTP Versions

WinHttpSetStatusCallback