WinHTTP in Depth

A Professional Guide to HTTP Networking in Modern C++ on Windows

When building Windows-native backend clients, system services, or enterprise tools, many developers immediately reach for cross-platform libraries such as libcurl. While this is often a valid choice, Windows provides a first-class, production-grade HTTP stack that is frequently overlooked:

WinHTTP

WinHTTP is not a legacy API. It is the same networking foundation used internally by Windows components, including Windows Update and system services.

This article explains what WinHTTP really is, when you should use it, and how to use it correctly in modern C++, with real examples—not toy snippets.

1. What Is WinHTTP?

WinHTTP (Windows HTTP Services) is a low-level, synchronous/asynchronous HTTP client API provided by Windows.

It is designed for:

• System services

• Background applications

• Server-side Windows software

• Enterprise tools

• Non-interactive applications

It is not designed for browser-like behavior or UI-driven applications.

2. WinHTTP vs WinINet (Important Distinction)

Many developers confuse WinHTTP with WinINet. This confusion leads to incorrect architectural decisions.

Rule: If your application runs as a service, daemon, or backend tool, WinHTTP is the correct API.

3. Architectural Model of WinHTTP

WinHTTP is built around explicit state management.

The typical lifecycle:

1. Open session

2. Connect to server

3. Create request

4. Send request

5. Receive response

6. Read response data

7. Cleanup resources

This explicit design aligns well with RAII-based C++ architecture.

4. Opening a WinHTTP Session

A session represents the global HTTP configuration.

HINTERNET hSession = WinHttpOpen(
    L"MyApp/1.0",
    WINHTTP_ACCESS_TYPE_DEFAULT_PROXY,
    WINHTTP_NO_PROXY_NAME,
    WINHTTP_NO_PROXY_BYPASS,
    0
);
if (!hSession) {
    throw std::runtime_error("WinHttpOpen failed");
}

Key points:

• Always identify your application with a meaningful User-Agent

• Proxy configuration is explicit

• Session objects are thread-safe

5. Connecting to a Server

HINTERNET hConnect = WinHttpConnect(
    hSession,
    L"api.example.com",
    INTERNET_DEFAULT_HTTPS_PORT,
    0
);
if (!hConnect) {
    WinHttpCloseHandle(hSession);
    throw std::runtime_error("WinHttpConnect failed");
}

Notes:

• DNS resolution is handled internally

• HTTPS and HTTP use different ports

• Connections can be reused for multiple requests

6. Creating an HTTP Request

HINTERNET hRequest = WinHttpOpenRequest(
    hConnect,
    L"GET",
    L"/v1/status",
    nullptr,
    WINHTTP_NO_REFERER,
    WINHTTP_DEFAULT_ACCEPT_TYPES,
    WINHTTP_FLAG_SECURE
);
if (!hRequest) {
    throw std::runtime_error("WinHttpOpenRequest failed");
}

Important flags:

• WINHTTP_FLAG_SECURE enables TLS

• HTTP verbs are explicit

• Headers are not implicit

7. Sending the Request

BOOL ok = WinHttpSendRequest(
    hRequest,
    WINHTTP_NO_ADDITIONAL_HEADERS,
    0,
    WINHTTP_NO_REQUEST_DATA,
    0,
    0,
    0
);
if (!ok) {
    throw std::runtime_error("WinHttpSendRequest failed");
}
ok = WinHttpReceiveResponse(hRequest, nullptr);
if (!ok) {
    throw std::runtime_error("WinHttpReceiveResponse failed");
}

WinHTTP separates:

• Sending headers/body

• Receiving the response

This allows precise control over timing and retries.

8. Reading the Response Body

WinHTTP does not return the response body automatically. You must read it manually in a loop.

std::string response;
DWORD bytesAvailable = 0;
do {
    if (!WinHttpQueryDataAvailable(hRequest, &bytesAvailable)) {
        break;
    }
    if (bytesAvailable == 0) {
        break;
    }
    std::vector<char> buffer(bytesAvailable);
    DWORD bytesRead = 0;
    if (!WinHttpReadData(
            hRequest,
            buffer.data(),
            bytesAvailable,
            &bytesRead)) {
        break;
    }
    response.append(buffer.data(), bytesRead);
} while (bytesAvailable > 0);

This design:

• Avoids hidden allocations

• Allows streaming large responses

• Works well with binary data

9. Handling HTTP Status Codes

DWORD statusCode = 0;
DWORD size = sizeof(statusCode);
WinHttpQueryHeaders(
    hRequest,
    WINHTTP_QUERY_STATUS_CODE | WINHTTP_QUERY_FLAG_NUMBER,
    WINHTTP_HEADER_NAME_BY_INDEX,
    &statusCode,
    &size,
    WINHTTP_NO_HEADER_INDEX
);
if (statusCode != 200) {
    // handle error
}

Always check status codes explicitly. WinHTTP does not throw exceptions or auto-handle failures.

10. Sending POST Requests with JSON

const wchar_t* headers =
    L"Content-Type: application/json\r\n";
std::string json = R"({"name":"WinHTTP","lang":"C++"})";
WinHttpSendRequest(
    hRequest,
    headers,
    -1,
    (LPVOID)json.data(),
    json.size(),
    json.size(),
    0
);

Important:

• Headers must be wide strings

• Body is raw bytes

• Encoding responsibility is yours

11. TLS and Security Considerations

WinHTTP:

• Uses the Windows certificate store

• Automatically validates certificates

• Supports modern TLS versions

Avoid disabling certificate validation except for testing.

DWORD flags = SECURITY_FLAG_IGNORE_UNKNOWN_CA;
WinHttpSetOption(
    hRequest,
    WINHTTP_OPTION_SECURITY_FLAGS,
    &flags,
    sizeof(flags)
);

Use with extreme caution.

12. Timeouts (Critical in Production)

WinHttpSetTimeouts(
    hSession,
    5000,  // resolve
    5000,  // connect
    5000,  // send
    5000   // receive
);

Never ship a networked application without timeouts.

13. RAII Wrapping (Strongly Recommended)

class WinHttpHandle {
public:
    explicit WinHttpHandle(HINTERNET h = nullptr) : handle(h) {}
    ~WinHttpHandle() {
        if (handle) WinHttpCloseHandle(handle);
    }
    HINTERNET get() const { return handle; }
private:
    HINTERNET handle;
};

RAII is essential to:

• Prevent leaks

• Guarantee cleanup

• Maintain exception safety

14. Synchronous vs Asynchronous Mode

WinHTTP supports:

• Blocking calls (simpler)

• Asynchronous callbacks (advanced)

Asynchronous mode is recommended for:

• High-performance services

• GUI apps avoiding blocking threads

But it requires:

• Callback registration

• State machines

• Careful lifetime management

15. When You Should Use WinHTTP

WinHTTP is an excellent choice if:

• You target Windows only

• You build services or backend tools

• You want zero third-party dependencies

• You want native TLS and proxy handling

• You need predictable, explicit behavior

Final Thoughts

WinHTTP is not outdated, not weak, and not inferior. It is a low-level, professional networking API designed for serious Windows software.

If you approach it with:

• RAII

• Clear separation of layers

• Explicit error handling

You can build robust, secure, high-performance HTTP clients entirely in modern C++ using WinHTTP alone.