microsoft/libHttpClient

microsoft/libHttpClient

Description: libHttpClient provides a platform abstraction layer for HTTP and WebSocket, and is designed for use by the Microsoft Xbox Live Service API (XSAPI) [https://github.com/Microsoft/xbox-live-api] and game devs. If you want to contribute to the project, please talk to us to avoid overlap.

Language: C++

License: MIT

Stars: 292

Forks: 140

Open issues: 11

Created: 2017-06-11T09:45:05Z

Pushed: 2026-06-22T05:00:24Z

Default branch: main

Fork: no

Archived: no

README:

Welcome!

libHttpClient provides a platform abstraction layer for HTTP and WebSocket, and is designed for use by the Microsoft Xbox Live Service API (XSAPI), PlayFab SDK, and game devs. If you want to contribute to the project, please talk to us to avoid overlap.

Goals

• libHttpClient provides a platform abstraction layer for HTTP and WebSocket
• Stock implementations that call native platform HTTP / WebSocket APIs on GDK, XDK ERA, Win32 Win7+, UWP, iOS, Android, Linux
• Caller can add support for other platforms via callback API
• Sample showing off an **HTTP implementation via Curl** via this callback
• Designed around the needs of professional game developers that use Xbox Live and PlayFab
• used by the Microsoft Xbox Live Service API (XSAPI) and PlayFab SDK
• Builds for GDK, XDK ERA, UWP, Win32 Win7+, iOS, Android, and Linux
• Public API is a flat C API
• Asynchronous API
• Public API supports simple P/Invoke without needing to use the "C#/.NET P/Invoke Interop SDK" or C++/CLI
• Public APIs to manage async tasks
• Async data can be returned to a specific game thread so the game doesn't need to marshal the data between threads
• No dependencies on PPL or Boost
• Does not throw exceptions as a means of non-fatal error reporting
• Caller controlled memory allocation via callback API (similar to GDK's XMemAlloc)
• Built-in logging support to either debug output and/or callback
• Built in retry support according to Xbox Live best practices (obey Retry-After header, jitter wait, etc) according to https://docs.microsoft.com/en-us/windows/uwp/xbox-live/using-xbox-live/best-practices/best-practices-for-calling-xbox-live#retry-logic-best-practices
• Xbox Live throttle handling logic
• Built-in API support to switch to mock layer
• Open source project on GitHub
• Unit tests via TAEF
• End to end samples for UWP C++, XDK ERA, Win32, iOS, and Android

HTTP API Usage

[See public header](../../tree/master/Include/httpClient/httpClient.h)

1. Optionally call HCMemSetFunctions() to control memory allocations 1. Call HCInitialize() 1. Optionally call HCSettingsSet*() 1. Call HCHttpCallCreate() to create a new HCCallHandle 1. Call HCHttpCallRequestSet*() to prepare the HCCallHandle 1. Call HCHttpCallPerform() to perform an HTTP call using the HCCallHandle. 1. The perform call is asynchronous, so the work will be done on a background thread which calls DispatchAsyncQueue( ..., AsyncQueueCallbackType_Work ). The results will return to the callback on the thread that calls DispatchAsyncQueue( ..., AsyncQueueCallbackType_Completion ). 1. Call HCHttpCallResponseGet*() to get the HTTP response of the HCCallHandle 1. Call HCHttpCallCloseHandle() to cleanup the HCCallHandle 1. Repeat 4-8 for each new HTTP call 1. Call HCCleanup() at shutdown before your memory manager set in step 1 is shutdown

WebSocket API Usage

[See public header](../../tree/master/Include/httpClient/httpClient.h) and [Win32 WebSocket sample](../../tree/master/Samples/Win32WebSocket)

1. Follow steps 1-3 from HTTP API setup above 1. Call HCWebSocketCreate() to create a new HCWebsocketHandle with message/binary message/close event callbacks 1. Optionally call HCWebSocketSetOptions() before connect to explicitly preserve legacy behavior or select deterministic behavior and compression requests 1. On Win32 and GDK legacy behavior, for payloads that may exceed the receive buffer (>20KB by default): Call HCWebSocketSetBinaryMessageFragmentEventFunction() to handle oversized incoming payloads 1. Optionally call HCWebSocketSetMaxReceiveBufferSize() before connect to adjust the deterministic inbound message-size limit, or on Win32 / GDK legacy behavior the fragment threshold 1. Optionally call HCWebSocketSetPingInterval() to adjust keepalive behavior 1. Call HCWebSocketConnectAsync() to connect to the WebSocket server 1. Call HCWebSocketSendMessageAsync() or HCWebSocketSendBinaryMessageAsync() to send messages 1. Handle incoming messages via your registered callbacks 1. Call HCWebSocketDisconnect() or HCWebSocketDisconnectWithStatus() when done 1. Call HCWebSocketCloseHandle() to cleanup 1. Call HCCleanup() at shutdown

Important WebSocket Notes

• No call to HCWebSocketSetOptions(): The socket uses the platform's legacy behavior.
• Legacy Win32 / GDK default buffer: The legacy receive buffer defaults to 20KB (20,480 bytes).
• Legacy Win32 / GDK oversized payload path: When an incoming payload exceeds the configured receive buffer, it is surfaced through HCWebSocketSetBinaryMessageFragmentEventFunction() as raw bytes.
• Legacy Win32 / GDK text overflow behavior: Oversized UTF-8 payloads use that same raw-byte fragment callback path.
• Legacy Win32 / GDK without a fragment handler: Oversized incoming payloads are not surfaced through the public whole-message callbacks unless a fragment handler is installed.
• Legacy macOS / iOS and Linux max: On macOS / iOS and Linux legacy behavior, the provider continues using its configured 32,000,000-byte maximum; HCWebSocketSetMaxReceiveBufferSize() does not become a caller-controlled hard cap there.
• Deterministic behavior: Calling HCWebSocketSetOptions(HCWebSocketOptions::None) or any non-legacy compression flag selects deterministic behavior on supported built-in implementations. Fragment callbacks are not supported there.
• Deterministic inbound limit: HCWebSocketSetMaxReceiveBufferSize() becomes a hard inbound message-size cap for deterministic behavior. If not set before connect, the deterministic default is 32,000,000 bytes, and oversized messages...