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
Copy file name to clipboardExpand all lines: xml/System.Runtime.InteropServices/ComWrappers.xml
+13-11Lines changed: 13 additions & 11 deletions
Original file line number
Diff line number
Diff line change
@@ -34,23 +34,25 @@ The <xref:System.Runtime.InteropServices.ComWrappers> API provides support for t
34
34
35
35
Traditionally in the runtime, a native proxy to managed object is called a COM Callable Wrapper (CCW), and a managed proxy to a native object is called a Runtime Callable Wrapper (RCW). However, when used here, those terms should not be confused with the built-in features of the same name (that is, [CCW](https://docs.microsoft.com/dotnet/standard/native-interop/com-callable-wrapper) and [RCW](https://docs.microsoft.com/dotnet/standard/native-interop/runtime-callable-wrapper)). Unlike the built-in features, a majority of the responsibility for accurate lifetime management, dispatching methods, and marshalling of arguments and return values is left to the `ComWrappers` implementer.
36
36
37
-
Minimal support is defined by the following features:
38
-
1. Efficient mapping between a managed object and a native proxy (e.g. CCW).
39
-
2. Efficient mapping between a native `IUnknown` and its managed proxy (e.g. RCW).
40
-
3. Integration with the Garbage Collector through the [`IReferenceTrackerHost`](https://docs.microsoft.com/windows/win32/api/windows.ui.xaml.hosting.referencetracker/nn-windows-ui-xaml-hosting-referencetracker-ireferencetrackerhost) interface contract.
41
-
- Leveraging this is a very advanced scenario.
37
+
"Minimal support" is defined by the following features:
38
+
39
+
1. Efficient mapping between a managed object and a native proxy (for example, CCW).
40
+
2. Efficient mapping between a native `IUnknown` and its managed proxy (for example, RCW).
41
+
3. Integration with the garbage collector through the <xref:NN:windows.ui.xaml.hosting.referencetracker.IReferenceTrackerHost> interface contract.
42
+
43
+
Leveraging this is an advanced scenario.
42
44
43
45
### Proxy state
44
46
45
-
Provided below are descriptions and illustrations of proxy state after their respective creation.
47
+
This section provides descriptions and illustrations of native and managed proxy state after their respective creation.
46
48
47
-
In the below illustrations, a strong reference is depicted as a solid line (i.e. `===`) and a weak reference is depicted as a dashed line (i.e. `= = =`). The terms "strong" and "weak" reference should be interpreted as "extending lifetime" and "not extending lifetime" as opposed to implying a specific implementation.
49
+
In the following illustrations, a strong reference is depicted as a solid line (`===`) and a weak reference is depicted as a dashed line (`= = =`). The terms "strong reference" and "weak reference" should be interpreted as "extending lifetime" and "not extending lifetime", as opposed to implying a specific implementation.
48
50
49
-
The state of the managed object and native proxy after a call to [`ComWrappers.GetOrCreateComInterfaceForObject`](https://docs.microsoft.com/dotnet/api/system.runtime.interopservices.comwrappers.getorcreatecominterfaceforobject) is illustrated below.
51
+
The following illustration shows the state of the managed object and native proxy after a call to <xref:System.Runtime.InteropServices.ComWrappers.GetOrCreateComInterfaceForObject(System.Object,System.Runtime.InteropServices.CreateComInterfaceFlags)?displayProperty=nameWithType>.
@@ -59,7 +61,7 @@ The state of the managed object and native proxy after a call to [`ComWrappers.G
59
61
-------------------- ----------------------
60
62
```
61
63
62
-
The state of the native object and managed proxy after a call to [`ComWrappers.GetOrCreateObjectForComInstance`](https://docs.microsoft.com/dotnet/api/system.runtime.interopservices.comwrappers.getorcreateobjectforcominstance) is illustrated below. The concept of "identity" follows the [rules for `IUnknown`](https://docs.microsoft.com/windows/win32/com/rules-for-implementing-queryinterface#objects-must-have-identity).
64
+
The next illustration shows the state of the native object and managed proxy after a call to <xref:System.Runtime.InteropServices.ComWrappers.GetOrCreateObjectForComInstance(System.IntPtr,System.Runtime.InteropServices.CreateObjectFlags)?displayProperty=nameWithType>. The concept of "identity" follows the [rules for `IUnknown`](https://docs.microsoft.com/windows/win32/com/rules-for-implementing-queryinterface#objects-must-have-identity).
63
65
64
66
```
65
67
------------------ ------------------
@@ -74,7 +76,7 @@ The state of the native object and managed proxy after a call to [`ComWrappers.
74
76
| native object. |
75
77
------------------------
76
78
```
77
-
Observe in the above illustration only weak references exist from the runtime perspective. The `+1` reference count on the native object is assumed to be performed by the managed proxy creator (i.e. `ComWrappers` implementer) to ensure the associated lifetime between the native object and its managed proxy. There is an optional strong reference (i.e. `AddRef()`) mentioned in the managed proxy, which is used to support scenario (3) above - see [`CreateObjectFlags.TrackerObject`](https://docs.microsoft.com/dotnet/api/system.runtime.interopservices.createobjectflags). With this optional strong reference the reference count would be `+2`.
79
+
Observe that only weak references exist from the runtime perspective. The `+1` reference count on the native object is assumed to be performed by the managed proxy creator (that is, the `ComWrappers` implementer) to ensure the associated lifetime between the native object and its managed proxy. There is an optional strong reference (that is, `AddRef()`) mentioned in the managed proxy, which is used to support scenario (3) mentioned earlier. See <xref:System.Runtime.InteropServices.CreateObjectFlags.TrackerObject?displayProperty=nameWithType>. With this optional strong reference, the reference count would be `+2`.
0 commit comments