<commit_before>## Welcome!

libHttpClient is still under construction and is not ready to use.  
You can review the goals below to see what shape the project will have in its final form.
If you want to contribute on the project, please talk to us to avoid overlap.

## Goals

- libHttpClient provides an **platform abstraction layer** for **HTTP** and **WebSocket**
- Stock implementations that call **native platform HTTP / WebSocket APIs** on UWP, XDK ERA, iOS, Android 
- Caller can add support for **other platforms via callback** API
- Sample showing off an **HTTP implementation via Curl** https://github.com/curl/curl via this callback
- Designed around the needs of **professional game developers** that use Xbox Live
- Will be **used by** the Microsoft Xbox Live Service API (XSAPI) [https://github.com/Microsoft/xbox-live-api]
- Builds for **UWP, XDK ERA, Win32, iOS, and Android**
- **Similar to the C++ REST SDK** (aka Casablanca) [https://github.com/Microsoft/cpprestsdk] but with key differences
- Public API is a **flat C API**
- Public API **supports simple P/Invoke** without needing to use the "C#/.NET P/Invoke Interop SDK" [https://en.wikipedia.org/wiki/Platform_Invocation_Services#C.23.2F.NET_P.2FInvoke_Interop_SDK]
- **Synchronous** API similar to Curl https://github.com/curl/curl
- **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 XDK'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://developer.microsoft.com/en-us/games/xbox/docs/xboxlive/using-xbox-live/best-practices/best-practices-for-calling-xbox-live
- **Xbox Live throttle** handling logic
- Built-in API support to switch to **mock layer**
- Does **not require C++/CX** to build on UWP or ERA
- **Open source** project on GitHub
- Binaries eventually on Nuget.org as **Nuget packages**
- Unit tests via TAEF
- End to end samples for UWP C++, UWP C# (with P/Invoke layer), XDK ERA, iOS, and Android
- [Needed?] Public APIs to **manage internal threads**

## HTTP API Usage

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

1. Optionally call HCMemSetFunctions() to control memory allocations
1. Call HCGlobalInitialize()
1. Optionally call HCSettingsSet*()
1. Call HCHttpCallCreate() to create a new HC_CALL_HANDLE
1. Call HCHttpCallRequestSet*() to prepare the HC_CALL_HANDLE
1. Call HCHttpCallPerform() to perform HTTP call using the HC_CALL_HANDLE.  This call is synchronous, so call it from a task thread
1. Call HCHttpCallResponseGet*() to get the HTTP response of the HC_CALL_HANDLE
1. Call HCHttpCallCleanup() to cleanup the HC_CALL_HANDLE
1. Repeat 4-8 for each new HTTP call
1. Call HCGlobalCleanup() at shutdown before your memory manager set in step 1 is shutdown

## Behavior control

* On UWP, XDK ERA, iOS, and Android, HCHttpCallPerform() will call native platform APIs
* Optionally call HCGlobalSetHttpCallPerformCallback() to create do your own HTTP handling using HCHttpCallRequestGet*(), HCHttpCallResponseSet*(), and HCSettingsGet*()
* See sample CustomHttpImplWithCurl how to use this callback plus Curl https://github.com/curl/curl to make an HTTP implementation using Curl.

## 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. IE:
<commit_msg>Adding TODO section to readme (#6)<commit_after>## Welcome!

libHttpClient is still under construction and is not ready to use.  
You can review the goals below to see what shape the project will have in its final form.
If you want to contribute on the project, please talk to us to avoid overlap.

## Goals

- libHttpClient provides an **platform abstraction layer** for **HTTP** and **WebSocket**
- Stock implementations that call **native platform HTTP / WebSocket APIs** on UWP, XDK ERA, iOS, Android 
- Caller can add support for **other platforms via callback** API
- Sample showing off an **HTTP implementation via Curl** https://github.com/curl/curl via this callback
- Designed around the needs of **professional game developers** that use Xbox Live
- Will be **used by** the Microsoft Xbox Live Service API (XSAPI) [https://github.com/Microsoft/xbox-live-api]
- Builds for **UWP, XDK ERA, Win32, iOS, and Android**
- **Similar to the C++ REST SDK** (aka Casablanca) [https://github.com/Microsoft/cpprestsdk] but with key differences
- Public API is a **flat C API**
- Public API **supports simple P/Invoke** without needing to use the "C#/.NET P/Invoke Interop SDK" [https://en.wikipedia.org/wiki/Platform_Invocation_Services#C.23.2F.NET_P.2FInvoke_Interop_SDK]
- **Synchronous** API similar to Curl https://github.com/curl/curl
- **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 XDK'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://developer.microsoft.com/en-us/games/xbox/docs/xboxlive/using-xbox-live/best-practices/best-practices-for-calling-xbox-live
- **Xbox Live throttle** handling logic
- Built-in API support to switch to **mock layer**
- Does **not require C++/CX** to build on UWP or ERA
- **Open source** project on GitHub
- Binaries eventually on Nuget.org as **Nuget packages**
- Unit tests via TAEF
- End to end samples for UWP C++, UWP C# (with P/Invoke layer), XDK ERA, iOS, and Android
- [Needed?] Public APIs to **manage internal threads**

## HTTP API Usage

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

1. Optionally call HCMemSetFunctions() to control memory allocations
1. Call HCGlobalInitialize()
1. Optionally call HCSettingsSet*()
1. Call HCHttpCallCreate() to create a new HC_CALL_HANDLE
1. Call HCHttpCallRequestSet*() to prepare the HC_CALL_HANDLE
1. Call HCHttpCallPerform() to perform HTTP call using the HC_CALL_HANDLE.  This call is synchronous, so call it from a task thread
1. Call HCHttpCallResponseGet*() to get the HTTP response of the HC_CALL_HANDLE
1. Call HCHttpCallCleanup() to cleanup the HC_CALL_HANDLE
1. Repeat 4-8 for each new HTTP call
1. Call HCGlobalCleanup() at shutdown before your memory manager set in step 1 is shutdown

## Behavior control

* On UWP, XDK ERA, iOS, and Android, HCHttpCallPerform() will call native platform APIs
* Optionally call HCGlobalSetHttpCallPerformCallback() to create do your own HTTP handling using HCHttpCallRequestGet*(), HCHttpCallResponseSet*(), and HCSettingsGet*()
* See sample CustomHttpImplWithCurl how to use this callback plus Curl https://github.com/curl/curl to make an HTTP implementation using Curl.

## TODO

Big things that still need to be done:

APIs:
* WebSocket APIs
* API for binary response data 
* APIs for controling mock layer

Implementation:
* Retry logic
* Throttling logic
* UWP implementation calling UWP platform HTTP / WebSocket APIs
* XDK project & XDK implementation calling XDK platform HTTP / WebSocket APIs
* iOS project & iOS implementation calling iOS platform HTTP / WebSocket APIs
* Android project & Android implementation calling Android platform HTTP / WebSocket APIs

Samples:
* XDK ERA sample
* iOS sample
* Android sample
* P/Invoke layer and UWP C# sample

## 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. IE:

{'fraction_non_alphanumeric': 0.09149236494289748, 'fraction_numerical': 0.005004491210060311, 'mean_word_length': 4.603163191948239, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 14, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2903508', 'n_tokens_mistral': 2326, 'n_tokens_neox': 2185, 'n_words': 1008}