48a8cc3636
Upon receiving a suspend event, the WinHttp provider will automatically tear down any active WebSocket connections. Depending on the current state of the connection, the suspend handler will either call WinHttpWebSocketClose followed by WinHttpCloseHandle, or just call WinHttpCloseHandle directly. If we receive a WinHttp disconnect callback at the same time, the disconnect handler will call WinHttpCloseHandle. This leads to race condition between the two handlers: If the suspend handler runs first and determines that it needs to call WinHttpWebSocketClose (because at that point we believe the WebSocket is still connected) and then the disconnect handler runs and calls WinHttpCloseHandle BEFORE the suspend handler actually calls WinHttpWebSocketClose, the WinHttp handle may be in an invalid state when WebSocketClose finally gets called, leading to a crash. The fix here involves a couple things. First, I updated the suspend handler to forego the call to WinHttpWebSocketClose altogether. This means that during suspend the WebSocket won't be torn down gracefully, but it greatly simplifies the LHC teardown process. Second, there is some additional logic needed to make sure that LHC still raises a disconnected event to clients during suspend, as the flow will change slightly with the removal of the WinHttpWebSocketClose call. This change also contains a fix for a debug assert due to buffer size in FormatTrace |
||
|---|---|---|
| Build | ||
| External | ||
| Include | ||
| Samples | ||
| Source | ||
| Tests | ||
| Utilities | ||
| .gitattributes | ||
| .gitignore | ||
| .gitmodules | ||
| CONTRIBUTING.md | ||
| LICENSE.md | ||
| NOTICE.txt | ||
| README.md | ||
| SECURITY.md | ||
| ThirdPartyNotices.txt | ||
| build.root | ||
| cgmanifest.json | ||
| custom.props | ||
| hc_settings.props.example | ||
| libHttpClient.props | ||
| libHttpClient.vs2019.sln | ||
| libHttpClient.vs2022.sln | ||
| platform_select.props | ||
README.md
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 SDKs, 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
- 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 SDKs
- Builds for GDK, XDK ERA, UWP, Win32 Win7+, iOS, and Android
- 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
- Optionally call HCMemSetFunctions() to control memory allocations
- Call HCInitialize()
- Optionally call HCSettingsSet*()
- Call HCHttpCallCreate() to create a new HCCallHandle
- Call HCHttpCallRequestSet*() to prepare the HCCallHandle
- Call HCHttpCallPerform() to perform an HTTP call using the HCCallHandle.
- 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 ).
- Call HCHttpCallResponseGet*() to get the HTTP response of the HCCallHandle
- Call HCHttpCallCloseHandle() to cleanup the HCCallHandle
- Repeat 4-8 for each new HTTP call
- Call HCCleanup() at shutdown before your memory manager set in step 1 is shutdown
Behavior control
- On GDK, XDK ERA, UWP, iOS, and Android, HCHttpCallPerform() will call native platform APIs
- Optionally call HCSetHttpCallPerformFunction() to do your own HTTP handling using HCHttpCallRequestGet*(), HCHttpCallResponseSet*(), and HCSettingsGet*()
- See sample CustomHttpImplWithCurl for an example of how to use this callback to make your own HTTP implementation.
Build customization
If you are building libHttpClient from source, you can provide an hc_settings.props file with specific MSBuild properties to customize how the library gets built. When built, the libHttpClient projects look for an hc_settings.props file in any directory above the the repository root. Currently, the following build customizations are available:
- Defining HCNoWebSockets will exclude WebSocket APIs (and all their dependencies) from the libHttpClient library
- Defining HCNoZlib will exclude compression APIs and prevent libHttpClient from defining Zlib symbols within libHttpClient
- Defining HCExternalOpenSSL will prevent libHttpClient from referencing our private OpenSSL projects. If this is defined, you will need to manually include your own (compatible) version of OpenSSL when linking.
An example customization file hc_settings.props.example can be found at the root of the repository.
How to clone repo
This repo contains submodules. There are two ways to make sure you get submodules.
When initially cloning, make sure you use the "--recursive" option. i.e.:
git clone --recursive https://github.com/Microsoft/libHttpClient.git
If you already cloned the repo, you can initialize submodules with:
git submodule sync
git submodule update --init --recursive
Note that using GitHub's feature to "Download Zip" does not contain the submodules and will not properly build. Please clone recursively instead.
Contribute Back!
Is there a feature missing that you'd like to see, or have you found a bug that you have a fix for? Or do you have an idea or just interest in helping out in building the library? Let us know and we'd love to work with you. For a good starting point on where we are headed and feature ideas, take a look at our requested features and bugs.
Big or small we'd like to take your contributions back to help improve the libHttpClient for game devs.
Having Trouble?
We'd love to get your review score, whether good or bad, but even more than that, we want to fix your problem. If you submit your issue as a Review, we won't be able to respond to your problem and ask any follow-up questions that may be necessary. The most efficient way to do that is to open a an issue in our issue tracker.
Xbox Live GitHub projects
- Xbox Live Service API for C++
- Xbox Live Samples
- Xbox Live Resiliency Fiddler Plugin
- Xbox Live Trace Analyzer
- libHttpClient
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.