You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The base library provides a set of helper functions that are used within the projection to deal with type conversion generically between the ABI and the projected API surface. While this remains their primary purpose, they are also useful in cases where you might need to interop between C++/WinRT and other APIs or libraries that may not have any knowledge of C++/WinRT. This document briefly describes these helper functions and how you might use them to perform various common operations related to interop. Unless otherwise noted, all of the functions below are free functions available in the winrt namespace.
5
5
6
-
`winrt::get`
6
+
`winrt::get_abi`
7
7
---
8
8
9
-
The `get` function returns the ABI representation for a given value. C++/WinRT does not provide implicit conversions to the ABI types, so you might call this function to get a raw pointer to the COM interface backing a runtime class or interface. For example:
9
+
The `get_abi` function returns the ABI representation for a given value. C++/WinRT does not provide implicit conversions to the ABI types, so you might call this function to get a raw pointer to the COM interface backing a runtime class or interface. For example:
Note that the `get` function does not increment the reference count so it is a useful and efficient way to pass the pointer to some other function, provided it is synchronous in nature. You can also save some typing by using the `abi` alias template to avoid uttering the name of the ABI type:
18
+
Note that the `get_abi` function does not increment the reference count so it is a useful and efficient way to pass the pointer to some other function, provided it is synchronous in nature. You can also save some typing by using the `abi` alias template to avoid uttering the name of the ABI type:
19
19
20
20
```C++
21
21
using namespace Windows::Foundation;
22
22
IAsyncInfo info;
23
23
24
-
abi<IAsyncInfo> * ptr = winrt::get(info);
24
+
abi<IAsyncInfo> * ptr = winrt::get_abi(info);
25
25
```
26
26
27
-
The `get` function works equally with other types like hstring:
27
+
The `get_abi` function works equally with other types like hstring:
28
28
29
29
```C++
30
30
HRESULT LogMessage(HSTRING value);
@@ -33,24 +33,24 @@ int main()
33
33
{
34
34
winrt::hstring message = L"hello world";
35
35
36
-
HRESULT hr = LogMessage(winrt::get(message));
36
+
HRESULT hr = LogMessage(winrt::get_abi(message));
37
37
}
38
38
```
39
39
40
-
`winrt::put`
40
+
`winrt::put_abi`
41
41
---
42
42
43
-
The `put` function returns the address of the ABI representation for a given value. This supports the COM convention of returning references as `out` parameters and is useful for safely taking ownership of a value returned from a classic COM or C-style function. For example:
43
+
The `put_abi` function returns the address of the ABI representation for a given value. This supports the COM convention of returning references as `out` parameters and is useful for safely taking ownership of a value returned from a classic COM or C-style function. For example:
The `attach` function takes ownership of an ABI value. Assuming you have a value, such as a COM interface pointer that is not owned, you can use the `attach` function to give ownership of it to a C++/WinRT type. The `attach` function is complemented by the `detach` function that does the inverse. For example:
73
+
The `attach_abi` function takes ownership of an ABI value. Assuming you have a value, such as a COM interface pointer that is not owned, you can use the `attach_abi` function to give ownership of it to a C++/WinRT type. The `attach_abi` function is complemented by the `detach_abi` function that does the inverse.
74
+
75
+
For example:
74
76
75
77
```C++
76
78
IAsyncInfo info = ...
77
79
78
-
abi<IAsyncInfo> * ptr = winrt::detach(info);
80
+
abi<IAsyncInfo> * ptr = winrt::detach_abi(info);
79
81
80
-
winrt::attach(info, ptr);
82
+
winrt::attach_abi(info, ptr);
81
83
```
82
84
83
-
This may be useful if you need to pass ownership between C++/WinRT and some other library like WRL or C++/CX. The same is possible with other types like `winrt::hstring`:
85
+
This may be useful if you need to pass ownership between C++/WinRT and some other library like WRL or C++/CX.
86
+
87
+
The same is possible with other types like `winrt::hstring`:
84
88
85
89
```C++
86
90
winrt::hstring message = L"hello world";
87
91
88
-
HSTRING handle = winrt::detach(message);
92
+
HSTRING handle = winrt::detach_abi(message);
89
93
uint32_t size = WindowsGetStringLen(handle);
90
94
91
-
winrt::attach(message, handle);
95
+
winrt::attach_abi(message, handle);
92
96
assert(message.size() == size);
93
97
```
94
98
95
-
`winrt::copy_to` & `winrt::copy_from`
99
+
`winrt::copy_to_abi` & `winrt::copy_from_abi`
96
100
-------------------
97
101
98
-
The `copy_to` and `copy_from` functions are similar to `attach` and `detach` except that they don't transfer ownership. Instead, they copy the underlying reference effectively calling `AddRef` or some equivalent. This is useful if you need to hold on to a reference but also need to return a reference-counted object to the caller. For example:
102
+
The `copy_to_abi` and `copy_from_abi` functions are similar to `attach_abi` and `detach_abi` except that they don't transfer ownership. Instead, they copy the underlying reference effectively calling `AddRef` or some equivalent. This is useful if you need to hold on to a reference but also need to return a reference-counted object to the caller.
103
+
104
+
For example:
99
105
100
106
```C++
101
107
abi<IAsyncInfo> * ptr = ...
102
108
103
109
IAsyncInfo info;
104
-
winrt::copy_from(info, ptr);
110
+
winrt::copy_from_abi(info, ptr);
105
111
```
106
112
107
-
In this example, the `copy_from` function first releases any reference held by the `info` object before acquiring a copy of `ptr`. If `ptr` does not hold a `nullptr` then `AddRef` is called so that the `info` variable has its own reference to the instance.
113
+
In the preceding example, the `copy_from_abi` function first releases any reference held by the `info` object before acquiring a copy of `ptr`. If `ptr` does not hold a `nullptr` then `AddRef` is called so that the `info` variable has its own reference to the instance.
108
114
109
115
```C++
110
116
IAsyncInfo info = ...
111
117
112
118
abi<IAsyncInfo> * ptr = nullptr;
113
-
winrt::copy_to(info, ptr);
119
+
winrt::copy_to_abi(info, ptr);
114
120
```
115
121
116
-
In this example, the `info` object presumably holds a reference to some instance and would like to give `ptr` its own reference. If `info` is not holding a reference then `ptr` will be assigned a `nullptr` value.
122
+
In the preceding example, the `info` object presumably holds a reference to some instance and would like to give `ptr` its own reference. If `info` is not holding a reference then `ptr` will be assigned a `nullptr` value.
117
123
118
-
`copy_to` and `copy_from` are thus very useful for dealing with ABI parameters as they follow the rules of COM and make it very convenient for interoperability.
124
+
The `copy_to_abi` and `copy_from_abi` functions are thus very useful for dealing with ABI parameters as they follow the rules of COM and make it very convenient for interoperability.
0 commit comments