InternetStatusCallback function - WinInet

Overview

The InternetStatusCallback function is a user-defined callback that receives status notifications from WinInet operations. It is typically used with InternetSetStatusCallback to monitor progress, handle errors, or log detailed activity.

Syntax

void CALLBACK InternetStatusCallback(
    HINTERNET hInternet,
    DWORD_PTR dwContext,
    DWORD dwInternetStatus,
    LPVOID lpvStatusInformation,
    DWORD dwStatusInformationLength
);

Parameters

Parameter	Type	Description
hInternet	HINTERNET	Handle to the Internet object that generated the callback.
dwContext	DWORD_PTR	Application-defined context value passed to InternetSetStatusCallback.
dwInternetStatus	DWORD	Status code indicating the type of notification. See Status Codes section.
lpvStatusInformation	LPVOID	Pointer to data associated with the status. The data type varies by status code.
dwStatusInformationLength	DWORD	Size, in bytes, of the information pointed to by `lpvStatusInformation`.

Return value

Return value is ignored. The function must return 0.

Remarks

The callback runs on a system thread. Keep processing fast and avoid blocking calls.
When receiving INTERNET_STATUS_HANDLE_CREATED, you can store hInternet for later use.
Do not free or modify the memory pointed to by lpvStatusInformation. It is owned by WinInet.
Use INTERNET_STATUS_REQUEST_COMPLETE to detect completion of an asynchronous request.

Status Codes

Code	Description
INTERNET_STATUS_RESOLVING_NAME	Resolving a host name.
INTERNET_STATUS_NAME_RESOLVED	Host name resolved.
INTERNET_STATUS_CONNECTING_TO_SERVER	Attempting to connect to the server.
INTERNET_STATUS_CONNECTED_TO_SERVER	Connection established.
INTERNET_STATUS_SENDING_REQUEST	Sending an HTTP request.
INTERNET_STATUS_REQUEST_SENT	Request sent successfully.
INTERNET_STATUS_RECEIVING_RESPONSE	Receiving server response.
INTERNET_STATUS_RESPONSE_RECEIVED	Response fully received.
INTERNET_STATUS_HANDLE_CREATED	A new handle is created.
INTERNET_STATUS_HANDLE_CLOSING	A handle is being closed.
INTERNET_STATUS_REQUEST_COMPLETE	Asynchronous request finished.

Example

The following example demonstrates how to register a callback and log status messages to the console.

#include <windows.h>
#include <wininet.h>
#include <stdio.h>

void CALLBACK MyStatusCallback(
    HINTERNET hInternet,
    DWORD_PTR dwContext,
    DWORD dwInternetStatus,
    LPVOID lpvStatusInformation,
    DWORD dwStatusInformationLength)
{
    UNREFERENCED_PARAMETER(hInternet);
    UNREFERENCED_PARAMETER(dwContext);
    UNREFERENCED_PARAMETER(lpvStatusInformation);
    UNREFERENCED_PARAMETER(dwStatusInformationLength);

    switch (dwInternetStatus) {
        case INTERNET_STATUS_RESOLVING_NAME:
            printf("Resolving host name...\n");
            break;
        case INTERNET_STATUS_NAME_RESOLVED:
            printf("Host name resolved.\n");
            break;
        case INTERNET_STATUS_CONNECTED_TO_SERVER:
            printf("Connected to server.\n");
            break;
        case INTERNET_STATUS_SENDING_REQUEST:
            printf("Sending request...\n");
            break;
        case INTERNET_STATUS_RESPONSE_RECEIVED:
            printf("Response received.\n");
            break;
        case INTERNET_STATUS_REQUEST_COMPLETE:
            printf("Request completed.\n");
            break;
        default:
            // Other statuses can be handled as needed
            break;
    }
}

int main(void)
{
    HINTERNET hSession = InternetOpenA("MyApp", INTERNET_OPEN_TYPE_PRECONFIG, NULL, NULL, 0);
    if (!hSession) {
        printf("InternetOpen failed. Error: %lu\\n", GetLastError());
        return 1;
    }

    // Register the callback
    InternetSetStatusCallback(hSession, MyStatusCallback);

    HINTERNET hConnect = InternetConnectA(hSession, "www.example.com", INTERNET_DEFAULT_HTTP_PORT,
        NULL, NULL, INTERNET_SERVICE_HTTP, 0, 0);
    if (!hConnect) {
        printf("InternetConnect failed. Error: %lu\\n", GetLastError());
        InternetCloseHandle(hSession);
        return 1;
    }

    HINTERNET hRequest = HttpOpenRequestA(hConnect, "GET", "/", NULL, NULL, NULL,
        INTERNET_FLAG_RELOAD, 0);
    if (!hRequest) {
        printf("HttpOpenRequest failed. Error: %lu\\n", GetLastError());
        InternetCloseHandle(hConnect);
        InternetCloseHandle(hSession);
        return 1;
    }

    // Send the request (asynchronous)
    if (!HttpSendRequestA(hRequest, NULL, 0, NULL, 0)) {
        printf("HttpSendRequest failed. Error: %lu\\n", GetLastError());
    }

    // Wait for the request to complete
    InternetCloseHandle(hRequest);
    InternetCloseHandle(hConnect);
    InternetCloseHandle(hSession);
    return 0;
}