Export (0) Print
Expand All
0 out of 2 rated this helpful - Rate this topic

WINHTTP_STATUS_CALLBACK function pointer

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

Syntax


typedef void ( CALLBACK *WINHTTP_STATUS_CALLBACK)(
  _In_  HINTERNET hInternet,
  _In_  DWORD_PTR dwContext,
  _In_  DWORD dwInternetStatus,
  _In_  LPVOID lpvStatusInformation,
  _In_  DWORD dwStatusInformationLength
);

Parameters

hInternet [in]

The handle for which the callback function is called.

dwContext [in]

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.

dwInternetStatus [in]

Specifies the status code that indicates why the callback function is called. This can be one of the following values:

WINHTTP_CALLBACK_STATUS_CLOSING_CONNECTION

Closing the connection to the server. The lpvStatusInformation parameter is NULL. This flag has been deprecated.

WINHTTP_CALLBACK_STATUS_CONNECTED_TO_SERVER

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. This flag has been deprecated.

WINHTTP_CALLBACK_STATUS_CONNECTING_TO_SERVER

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

WINHTTP_CALLBACK_STATUS_CONNECTION_CLOSED

Successfully closed the connection to the server. The lpvStatusInformation parameter is NULL. This flag has been deprecated.

WINHTTP_CALLBACK_STATUS_DATA_AVAILABLE

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).

WINHTTP_CALLBACK_STATUS_HANDLE_CREATED

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

WINHTTP_CALLBACK_STATUS_HANDLE_CLOSING

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.

WINHTTP_CALLBACK_STATUS_HEADERS_AVAILABLE

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

WINHTTP_CALLBACK_STATUS_INTERMEDIATE_RESPONSE

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.

WINHTTP_CALLBACK_STATUS_NAME_RESOLVED

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

WINHTTP_CALLBACK_STATUS_READ_COMPLETE

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.

WINHTTP_CALLBACK_STATUS_RECEIVING_RESPONSE

Waiting for the server to respond to a request. The lpvStatusInformation parameter is NULL. This flag has been deprecated.

WINHTTP_CALLBACK_STATUS_REDIRECT

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.

WINHTTP_CALLBACK_STATUS_REQUEST_ERROR

An error occurred while sending an HTTP request. The lpvStatusInformation parameter contains a pointer to a WINHTTP_ASYNC_RESULT structure, of which the dwResult member indicates the return value of the function and any error codes that apply.

WINHTTP_CALLBACK_STATUS_REQUEST_SENT

Successfully sent the information request to the server. The lpvStatusInformation parameter contains a pointer to a DWORD indicating the number of bytes sent. This flag has been deprecated.

WINHTTP_CALLBACK_STATUS_RESOLVING_NAME

Looking up the IP address of a server name. The lpvStatusInformation parameter contains a pointer to the server name being resolved. This flag has been deprecated.

WINHTTP_CALLBACK_STATUS_RESPONSE_RECEIVED

Successfully received a response from the server. The lpvStatusInformation parameter contains a pointer to a DWORD indicating the number of bytes received. This flag has been deprecated.

WINHTTP_CALLBACK_STATUS_SECURE_FAILURE

One or more errors were encountered while retrieving a Secure Sockets Layer (SSL) certificate from the server. The lpvStatusInformation parameter contains a flag. For more information, see the description for lpvStatusInformation.

WINHTTP_CALLBACK_STATUS_SENDING_REQUEST

Sending the information request to the server. The lpvStatusInformation parameter is NULL. This flag has been deprecated.

WINHTTP_CALLBACK_STATUS_SENDREQUEST_COMPLETE

The request completed successfully. The lpvStatusInformation parameter is NULL.

WINHTTP_CALLBACK_STATUS_WRITE_COMPLETE

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.

WINHTTP_CALLBACK_STATUS_GETPROXYFORURL_COMPLETE

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

WINHTTP_CALLBACK_STATUS_CLOSE_COMPLETE

The connection was successfully closed via a call to WinHttpWebSocketClose.

WINHTTP_CALLBACK_STATUS_SHUTDOWN_COMPLETE

The connection was successfully shut down via a call to WinHttpWebSocketShutdown.

lpvStatusInformation [in]

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

If the dwInternetStatus parameter is WINHTTP_CALLBACK_STATUS_SECURE_FAILURE, this parameter can be a bitwise-OR combination of one or more of the following values:

ValueMeaning
WINHTTP_CALLBACK_STATUS_FLAG_CERT_REV_FAILED

Certification revocation checking has been enabled, but the revocation check failed to verify whether a certificate has been revoked. The server used to check for revocation might be unreachable.

WINHTTP_CALLBACK_STATUS_FLAG_INVALID_CERT

SSL certificate is invalid.

WINHTTP_CALLBACK_STATUS_FLAG_CERT_REVOKED

SSL certificate was revoked.

WINHTTP_CALLBACK_STATUS_FLAG_INVALID_CA

The function is unfamiliar with the Certificate Authority that generated the server's certificate.

WINHTTP_CALLBACK_STATUS_FLAG_CERT_CN_INVALID

SSL certificate common name (host name field) is incorrect, for example, if you entered www.microsoft.com and the common name on the certificate says www.msn.com.

WINHTTP_CALLBACK_STATUS_FLAG_CERT_DATE_INVALID

SSL certificate date that was received from the server is bad. The certificate is expired.

WINHTTP_CALLBACK_STATUS_FLAG_SECURITY_CHANNEL_ERROR

The application experienced an internal error loading the SSL libraries.

 

dwStatusInformationLength [in]

A value of type unsigned long integer that specifies the size, in bytes, of the lpvStatusInformation buffer.

Return value

This function pointer does not return a value.

Remarks

This callback function must be threadsafe and should be able to handle reentered for the same request while it is processing. A value of WINHTTP_CALLBACK_STATUS_HANDLE_CLOSING in the dwInternetStatus parameter indicates that this is the last callback the application receives, and that no other messages for this request are processed.

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.

Completion flagFunction
WINHTTP_CALLBACK_STATUS_DATA_AVAILABLE WinHttpQueryDataAvailable
WINHTTP_CALLBACK_STATUS_HEADERS_AVAILABLE WinHttpReceiveResponse
WINHTTP_CALLBACK_STATUS_READ_COMPLETE WinHttpReadData
WINHTTP_CALLBACK_STATUS_SENDREQUEST_COMPLETE WinHttpSendRequest
WINHTTP_CALLBACK_STATUS_WRITE_COMPLETE WinHttpWriteData
WINHTTP_CALLBACK_STATUS_REQUEST_ERRORAny of the above functions when an error occurs.

 

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 afinity when you call WinHttp asynchronously: a call might start from one thread, but any other thread can receive the callback.

Note  For more information about implementation in Windows XP and Windows 2000, see Run-Time Requirements.

Requirements

Minimum supported client

Windows XP, Windows 2000 Professional with SP3 [desktop apps only]

Minimum supported server

Windows Server 2003, Windows 2000 Server with SP3 [desktop apps only]

Redistributable

WinHTTP 5.0 and Internet Explorer 5.01 or later on Windows XP and Windows 2000.

Header

Winhttp.h

See also

WinHttpSetStatusCallback
WinHTTP Versions

 

 

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.