Update docs to reflect C++ API exposure changes

Author: jehumb-havok

CHANGELOG.md

@@ -15,6 +15,7 @@ Those changes are available on the `master` branch but have not yet been release
 
 ### Changed
 
+- (89fc337) Promoted the C++ classes headers as public API by moving them to the `include/` folder of `libs/Microsoft.MixedReality.WebRTC.Native/`. Conversely, demoted `api.h` to private and renamed to `interop_api.h` to reflect the fact it is an internal API for interop with C# and it is not part of the MixedReality-WebRTC public API (as in, changes in the interop API do not constitute a breaking change from the point of view of MixedReality-WebRTC release versioning).
 - (5740ab7,d26706d) Make the local peer ID for `node-dss` configurable by the user, and default the local peer ID to the machine name. Drop usage of generated IDs to make it clear that the user is in charge of chosing those IDs and ensure their unicity. (#38)
 - (1d34965) Make the `AudioSource` and `VideoSource` Unity components, which serve as base classes, abstract to prevent Unity from listing them in the list of components and prevent the user from trying to instantiate them. (#103)
 - (2b44e67) Replaced all uses of `std::lock_guard` with `std::scoped_lock`.

README.md

@@ -92,7 +92,7 @@ The `Microsoft.MixedReality.WebRTC.sln` Visual Studio 2019 solution located at t
 - A C# unit tests project `Microsoft.MixedReality.WebRTC.Tests`
 - A UWP C# sample app project `Microsoft.MixedReality.WebRTC.TestAppUWP` based on WPF and XAML which demonstrates audio / video / data communication by mean of a simple video chat app.
 
-_Note_ - Currently due to CI limitations some projects are downgraded to VS 2017, but will be reverted to VS 2019 eventually (see [#14](https://github.com/microsoft/MixedReality-WebRTC/issues/14)).
+_Note_ - Currently due to CI limitations some projects are downgraded to VS 2017, as the Google M71 milestone the `master` branch is building upon does not support VS 2019, and Azure DevOps CI agents do not support multiple Visual Studio versions on the same agent. This will be reverted to VS 2019 eventually (see [#14](https://github.com/microsoft/MixedReality-WebRTC/issues/14)).
 
 ## Building MixedReality-WebRTC
 
@@ -113,9 +113,9 @@ The current version is a public preview under active development, which contains
 
 - HoloLens 2 exhibits some small performance penalty due to the [missing support (#157)](https://github.com/webrtc-uwp/webrtc-uwp-sdk/issues/157) for SIMD-accelerated YUV conversion in WebRTC UWP SDK on ARM.
 - H.264 hardware video encoding (UWP only) exhibits some video freeze and quality degrading (blockiness). See #74 and #101 for details.
-- There is currently no clean C++ API; instead the C API used for C# P/Invoke can be used from C++ code, and opaque handles cast to C++ objects. An actual C++ API will eventually be exposed.
+- There is currently no clean C++ API; instead the C API used for C# P/Invoke can be used from C++ code, and opaque handles cast to C++ objects. An actual C++ API will eventually be exposed. The C++ library public API is found in [`libs\Microsoft.MixedReality.WebRTC.Native\include`](https://github.com/microsoft/MixedReality-WebRTC/tree/master/libs/Microsoft.MixedReality.WebRTC.Native/include) and already contains some classes, but is not 100% functional at this time (cannot create a peer connection for example).
 
-In addition, the Debug config of WebRTC core implementation is known to exhibit some performance issues on most devices, including some higher end PCs. Using the Release config of the core WebRTC implementation usually prevents this.
+In addition, the Debug config of WebRTC core implementation is known to exhibit some performance issues on most devices, including some higher-end PCs. Using the Release config of the core WebRTC implementation usually prevents this.
 
 ## Contributing
 

libs/Microsoft.MixedReality.WebRTC.Native/docs/design.md

@@ -10,7 +10,7 @@ The library takes a dependency on `webrtc.lib`, which already depends on numerou
 
 The library uses `clang-format`. This is the reference and only accepted code formatting.
 
-## API rules
+## Interop API rules
 
 The library provides a set of C functions which can be invoked directly from both C++ and C# (P-invoke). This means that the following restrictions should apply:
 
@@ -23,7 +23,9 @@ The library provides a set of C functions which can be invoked directly from bot
 - Callbacks take an opaque `void* user_data` argument to allow the language wrapper to convert from static function to object method. See the **Callbacks** section more details.
 - Functions are designed in such a way as to avoid as much as possible calls during performance intensive operations. For example, try to pass as much data as possible in a single call instead of performing multiple calls. This reduces the overhead of language transition, which can be high in some cases. See _e.g._ the **Enumeration** section.
 
-Those rules apply to the API surface only (`api.h`). Within the library itself, C++ constructs can be used as needed.
+Those rules apply to the API surface only (`interop_api.h`). Within the library itself, C++ constructs can be used as needed.
+
+Note that the interop API is an **internal API**. Breaking changes to the interop API are considered internal and do not constitute a breaking change from the point of view of the MixedReality-WebRTC API semantic versioning (the major version will _not_ be bumped with those changes).
 
 ## Lifetime and ownership
 
@@ -45,11 +47,17 @@ C* ptr = new C();
 
 ## Strings
 
-To simplify interop with C#, the intent is that strings be passed in C# as `DllImport(CharSet.Ansi)`, meaning UTF-8 in practice. So conversion happens from the native UTF-16 C# `string` type. This means that strings passed as arguments are passed as null-terminated `const char*`.
+### C++ library API
+
+Due to limitations in inlining rules, in particular with templates, and the fact the MSVC compiler ships potentially incompatible versions of `std::string` between its releases, the `std::string` type MUST NOT be used in the C++ library public API. Instead, the convenience wrapper class `str` MUST be used, which exposes the exact same interface as `std::string` (and internally derives from it) while exclusively exposing out-of-line methods, ensuring safety for calls across DLL boundaries.
+
+### Interop API
+
+To simplify interop with C#, the intent is that strings be passed in C# as `DllImport(CharSet.Ansi)`, meaning UTF-8 in practice. So conversion happens from the native UTF-16 C# `string` type. This means that strings passed as arguments MUST be passed as null-terminated `const char*`.
 
 Because of this marshaling, where performance matters string parameters should be avoided.
 
-Returning strings from native side back to wrapper side is more problematic. In general try to use a buffer `char*` allocated by the wrapper, with an explicit capacity `const int`, and return the used size `int*`.
+Returning strings from the native side back to the wrapper side is more problematic. In general, try to use a buffer `char*` allocated by the wrapper, with an explicit capacity `const int`, and return the used size `int*`.
 
 ```cpp
 int GetString(char* buffer, const int capacity);