Merge pull request #254 from MicrosoftDocs/stwhi-master/cppwinrt-170

more tips

Author: ktoliver

windows-apps-src/cpp-and-winrt-apis/author-coclasses.md

@@ -55,9 +55,9 @@ The good news is that all it takes to cause **winrt::implements** to support cla
 
 You could do that explicitly, or indirectly by including some other header file such as `ole2.h`. One recommended method is to include the `wil\cppwinrt.h` header file, which is part of the [Windows Implementation Libraries (WIL)](https://github.com/Microsoft/wil). The `wil\cppwinrt.h` header file not only makes sure that `unknwn.h` is included before `winrt/base.h`, it also sets things up so that C++/WinRT and WIL understand each other's exceptions and error codes.
 
-## A basic example
+## A simple example of a COM component
 
-Here's a simple example, which you can test out if you paste the code into the `pch.h` and `main.cpp` of a new **Windows Console Application (C++/WinRT)** project.
+Here's a simple example of a COM component written using C++/WinRT. This is a full listing of a mini-application, so you can the code out if you paste it into the `pch.h` and `main.cpp` of a new **Windows Console Application (C++/WinRT)** project.
 
 ```cppwinrt
 // pch.h

windows-apps-src/cpp-and-winrt-apis/index.md

@@ -49,6 +49,7 @@ C++/WinRT performs better and produces smaller binaries than any other language
 | [XAML controls; bind to a C++/WinRT property](binding-property.md) | A property that can be effectively bound to a XAML control is known as an *observable* property. This topic shows how to implement and consume an observable property, and how to bind a XAML control to it. |
 | [XAML items controls; bind to a C++/WinRT collection](binding-collection.md) | A collection that can be effectively bound to a XAML items control is known as an *observable* collection. This topic shows how to implement and consume an observable collection, and how to bind a XAML items control to it. |
 | [XAML custom (templated) controls with C++/WinRT](xaml-cust-ctrl.md) | This topic walks you through the steps of creating a simple custom control using C++/WinRT. You can build on the info here to create your own feature-rich and customizable UI controls. |
+| [Passing parameters into the ABI boundary](pass-parms-to-abi.md) | C++/WinRT simplifies passing parameters into the ABI boundary by providing automatic conversions for common cases. |
 | [Consume COM components with C++/WinRT](consume-com.md) | This topic uses a full Direct2D code example to show how to use C++/WinRT to consume COM classes and interfaces. |
 | [Author COM components with C++/WinRT](author-coclasses.md) | C++/WinRT can help you to author classic COM components, just as it helps you to author Windows Runtime classes. |
 | [Move to C++/WinRT from C++/CX](move-to-winrt-from-cx.md) | This topic shows how to port C++/CX code to its equivalent in C++/WinRT. |

windows-apps-src/cpp-and-winrt-apis/interop-winrt-abi.md

@@ -11,6 +11,8 @@ ms.localizationpriority: medium
 
 This topic shows how to convert between SDK application binary interface (ABI) and [C++/WinRT](/windows/uwp/cpp-and-winrt-apis/intro-to-using-cpp-with-winrt) objects. You can use these techniques to interop between code that uses these two ways of programming with the Windows Runtime, or you can use them as you gradually move your code from the ABI to C++/WinRT.
 
+In general, C++/WinRT exposes ABI types as **void\***, so that you don't need to include platform header files.
+
 ## What is the Windows Runtime ABI, and what are ABI types?
 A Windows Runtime class (runtime class) is really an abstraction. This abstraction defines a binary interface (the Application Binary Interface, or ABI) that allows various programming languages to interact with an object. Regardless of programming language, client code interaction with a Windows Runtime object happens at the lowest level, with client language constructs translated into calls into the object's ABI.
 
@@ -240,9 +242,77 @@ int main()
 }
 ```
 
+## Interoperating with ABI COM interface pointers
+
+The helper function template below illustrates how to copy an ABI COM interface pointer of a given type to its equivalent C++/WinRT projected smart pointer type.
+
+```cppwinrt
+template<typename To, typename From>
+To to_winrt(From* ptr)
+{
+    To result{ nullptr };
+    winrt::check_hresult(ptr->QueryInterface(winrt::guid_of<To>(), winrt::put_abi(result)));
+    return result;
+}
+...
+ID2D1Factory1* com_ptr{ ... };
+auto cppwinrt_ptr {to_winrt<winrt::com_ptr<ID2D1Factory1>>(com_ptr)};
+```
+
+This next helper function template is equivalent, except that it copies from the smart pointer type from the [Windows Implementation Libraries (WIL)](https://github.com/Microsoft/wil).
+
+```cppwinrt
+template<typename To, typename From, typename ErrorPolicy>
+To to_winrt(wil::com_ptr_t<From, ErrorPolicy> const& ptr)
+{
+    To result{ nullptr };
+    if constexpr (std::is_same_v<typename ErrorPolicy::result, void>)
+    {
+        ptr.query_to(winrt::guid_of<To>(), winrt::put_abi(result));
+    }
+    else
+    {
+        winrt::check_result(ptr.query_to(winrt::guid_of<To>(), winrt::put_abi(result)));
+    }
+    return result;
+}
+```
+
+Also see [Consume COM components with C++/WinRT](/windows/uwp/cpp-and-winrt-apis/consume-com).
+
+### Unsafe interop with ABI COM interface pointers
+
+The table that follows shows (in addition to other operations) unsafe conversions between an ABI COM interface pointer of a given type and its equivalent C++/WinRT projected smart pointer type. For the code in the table, assume these declarations.
+
+```cppwinrt
+winrt::Sample s;
+ISample* p;
+
+void GetSample(_Out_ ISample** pp);
+```
+
+Assume further that **ISample** is the default interface for **Sample**.
+
+You can assert that at compile time with this code.
+
+```cppwinrt
+static_assert(std::is_same_v<winrt::default_interface<winrt::Sample>, winrt::ISample>);
+```
+
+| Operation | How to do it | Notes |
+|-|-|-|
+| Extract **ISample\*** from **winrt::Sample** | `p = reinterpret_cast<ISample*>(get_abi(s));` | *s* still owns the object. |
+| Detach **ISample\*** from **winrt::Sample** | `p = reinterpret_cast<ISample*>(detach_abi(s));` | *s* no longer owns the object. |
+| Transfer **ISample\*** to new **winrt::Sample** | `winrt::Sample s{ p, winrt::take_ownership_from_abi };` | *s* takes ownership of the object. |
+| Set **ISample\*** into **winrt::Sample** | `*put_abi(s) = p;` | *s* takes ownership of the object. Any object previously owned by *s* is leaked (will assert in debug). |
+| Receive **ISample\*** into **winrt::Sample** | `GetSample(reinterpret_cast<ISample**>(put_abi(s)));` | *s* takes ownership of the object. Any object previously owned by *s* is leaked (will assert in debug). |
+| Replace **ISample\*** in **winrt::Sample** | `attach_abi(s, p);` | *s* takes ownership of the object. The object previously owned by *s* is freed. |
+| Copy **ISample\*** to **winrt::Sample** | `copy_from_abi(s, p);` | *s* makes a new reference to the object. The object previously owned by *s* is freed. |
+| Copy **winrt::Sample** to **ISample\*** | `copy_to_abi(s, reinterpret_cast<void*&>(p));` | *p* receives a copy of the object. Any object previously owned by *p* is leaked. |
+
 ## Interoperating with the ABI's GUID struct
 
-**GUID** is projected as **winrt::guid**. For APIs that you implement, you must use **winrt::guid** for GUID parameters. Otherwise, there are automatic conversions between **winrt::guid** and **GUID** as long as you include `unknwn.h` (implicitly included by <windows.h> and many other header files) before you include any C++/WinRT headers.
+[**GUID**](/previous-versions/aa373931(v%3Dvs.80)) is projected as **winrt::guid**. For APIs that you implement, you must use **winrt::guid** for GUID parameters. Otherwise, there are automatic conversions between **winrt::guid** and **GUID** as long as you include `unknwn.h` (implicitly included by <windows.h> and many other header files) before you include any C++/WinRT headers.
 
 If you don't do that, then you can hard-`reinterpret_cast` between them. For the table that follows, assume these declarations.
 
@@ -256,6 +326,27 @@ GUID abiguid;
 | From **winrt::guid** to **GUID** | `abiguid = winrtguid;` | `abiguid = reinterpret_cast<GUID&>(winrtguid);` |
 | From **GUID** to **winrt::guid** | `winrtguid = abiguid;` | `winrtguid = reinterpret_cast<winrt::guid&>(abiguid);` |
 
+## Interoperating with the ABI's HSTRING
+
+The table that follows shows conversions between **winrt::hstring** and [**HSTRING**](/windows/win32/winrt/hstring), and other operations. For the code in the table, assume these declarations.
+
+```cppwinrt
+winrt::hstring s;
+HSTRING h;
+
+void GetString(_Out_ HSTRING* value);
+```
+
+| Operation | How to do it | Notes |
+|-|-|-|
+| Extract **HSTRING** from **hstring** | `h = static_cast<HSTRING>(get_abi(s));` | *s* still owns the string. |
+| Detach **HSTRING** from **hstring** | `h = reinterpret_cast<HSTRING>(detach_abi(s));` | *s* no longer owns the string. |
+| Set **HSTRING** into **hstring** | `*put_abi(s) = h;` | *s* takes ownership of string. Any string previously owned by *s* is leaked (will assert in debug). |
+| Receive **HSTRING** into **hstring** | `GetString(reinterpret_cast<HSTRING*>(put_abi(s)));` | *s* takes ownership of string. Any string previously owned by *s* is leaked (will assert in debug). |
+| Replace **HSTRING** in **hstring** | `attach_abi(s, h);` | *s* takes ownership of string. The string previously owned by *s* is freed. |
+| Copy **HSTRING** to **hstring** | `copy_from_abi(s, h);` | *s* makes a private copy of the string. The string previously owned by *s* is freed. |
+| Copy **hstring** to **HSTRING** | `copy_to_abi(s, reinterpret_cast<void*&>(h));` | *h* receives a copy of the string. Any string previously owned by *h* is leaked. |
+
 ## Important APIs
 * [AddRef function](https://docs.microsoft.com/windows/desktop/api/unknwn/nf-unknwn-iunknown-addref)
 * [QueryInterface function](https://docs.microsoft.com/windows/desktop/api/unknwn/nf-unknwn-iunknown-queryinterface(q_))

windows-apps-src/cpp-and-winrt-apis/intro-to-using-cpp-with-winrt.md

@@ -133,6 +133,8 @@ In your C++/WinRT programming, you can use standard C++ language features and [S
 
 > [!WARNING]
 > There are also types that you might see if you closely study the C++/WinRT Windows namespace headers. An example is **winrt::param::hstring**, but there are collection examples too. These exist solely to optimize the binding of input parameters, and they yield big performance improvements and make most calling patterns "just work" for related standard C++ types and containers. These types are only ever used by the projection in cases where they add most value. They're highly optimized and they're not for general use; don't be tempted to use them yourself. Nor should you use anything from the `winrt::impl` namespace, since those are implementation types, and therefore subject to change. You should continue to use standard types, or types from the [winrt namespace](/uwp/cpp-ref-for-winrt/winrt).
+>
+> Also see [Passing parameters into the ABI boundary](/windows/uwp/cpp-and-winrt-apis/pass-parms-to-abi).
 
 ## Important APIs
 * [winrt::hstring struct](/uwp/cpp-ref-for-winrt/hstring)

windows-apps-src/cpp-and-winrt-apis/news.md

@@ -284,8 +284,8 @@ The table below contains news and changes for C++/WinRT in the Windows SDK versi
 
 Other changes.
 
-- **Breaking change**. [**winrt::get_abi(winrt::hstring const&)**](/uwp/cpp-ref-for-winrt/get-abi) now returns `void*` instead of `HSTRING`. You can use `static_cast<HSTRING>(get_abi(my_hstring));` to get an HSTRING.
-- **Breaking change**. [**winrt::put_abi(winrt::hstring&)**](/uwp/cpp-ref-for-winrt/put-abi) now returns `void**` instead of `HSTRING*`. You can use `reinterpret_cast<HSTRING*>(put_abi(my_hstring));` to get an HSTRING*.
+- **Breaking change**. [**winrt::get_abi(winrt::hstring const&)**](/uwp/cpp-ref-for-winrt/get-abi) now returns `void*` instead of `HSTRING`. You can use `static_cast<HSTRING>(get_abi(my_hstring));` to get an HSTRING. See [Interoperating with the ABI's HSTRING](interop-winrt-abi.md#interoperating-with-the-abis-hstring).
+- **Breaking change**. [**winrt::put_abi(winrt::hstring&)**](/uwp/cpp-ref-for-winrt/put-abi) now returns `void**` instead of `HSTRING*`. You can use `reinterpret_cast<HSTRING*>(put_abi(my_hstring));` to get an HSTRING*. See [Interoperating with the ABI's HSTRING](interop-winrt-abi.md#interoperating-with-the-abis-hstring).
 - **Breaking change**. HRESULT is now projected as **winrt::hresult**. If you need an HRESULT (to do type checking, or to support type traits), then you can `static_cast` a **winrt::hresult**. Otherwise, **winrt::hresult** converts to HRESULT, as long as you include `unknwn.h` before you include any C++/WinRT headers.
 - **Breaking change**. GUID is now projected as **winrt::guid**. For APIs that you implement, you must use **winrt::guid** for GUID parameters. Otherwise, **winrt::guid** converts to GUID, as long as you include `unknwn.h` before you include any C++/WinRT headers. See [Interoperating with the ABI's GUID struct](interop-winrt-abi.md#interoperating-with-the-abis-guid-struct).
 - **Breaking change**. The [**winrt::handle_type constructor**](/uwp/cpp-ref-for-winrt/handle-type#handle_typehandle_type-constructor) has been hardened by making it explicit (it's now harder to write incorrect code with it). If you need to assign a raw handle value, call the [**handle_type::attach function**](/uwp/cpp-ref-for-winrt/handle-type#handle_typeattach-function) instead.