ComWrappers Class

Definition

Namespace:

System.Runtime.InteropServices

Assembly:

System.Runtime.InteropServices.dll

Important

This API is not CLS-compliant.

Class for managing wrappers of COM IUnknown types.

public ref class ComWrappers abstract

[System.CLSCompliant(false)]
[System.Runtime.Versioning.UnsupportedOSPlatform("android")]
[System.Runtime.Versioning.UnsupportedOSPlatform("browser")]
[System.Runtime.Versioning.UnsupportedOSPlatform("ios")]
[System.Runtime.Versioning.UnsupportedOSPlatform("tvos")]
public abstract class ComWrappers

[<System.CLSCompliant(false)>]
[<System.Runtime.Versioning.UnsupportedOSPlatform("android")>]
[<System.Runtime.Versioning.UnsupportedOSPlatform("browser")>]
[<System.Runtime.Versioning.UnsupportedOSPlatform("ios")>]
[<System.Runtime.Versioning.UnsupportedOSPlatform("tvos")>]
type ComWrappers = class

Public MustInherit Class ComWrappers

Inheritance

Object

ComWrappers

Derived

System.Runtime.InteropServices.Marshalling.StrategyBasedComWrappers

Attributes

CLSCompliantAttribute UnsupportedOSPlatformAttribute

Remarks

The ComWrappers API provides support for the IUnknown ABI, independent of the built-in COM interoperability support. The ComWrappers API exposes the minimal runtime support that's needed for developers to replace the built-in version in an efficient manner.

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 and RCW). 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.

"Minimal support" is defined by the following features:

1. Efficient mapping between a managed object and a native proxy (for example, CCW).

2. Efficient mapping between a native IUnknown and its managed proxy (for example, RCW).

3. Integration with the garbage collector through the IReferenceTrackerHost interface contract.

   Leveraging this is an advanced scenario.

Proxy state

This section provides descriptions and illustrations of native and managed proxy state after their respective creation.

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.

The following illustration shows the state of the managed object and native proxy after a call to ComWrappers.GetOrCreateComInterfaceForObject(Object, CreateComInterfaceFlags).

 --------------------                  ----------------------
|   Managed object   |                |     Native proxy     |
|                    |                | Ref count: 1         |
|  ----------------  |                |  ------------------  |
| | Weak reference |=| = = = = = = = >| | Strong reference | |
| |    to proxy    | |<===============|=|    to object     | |
|  ----------------  |                |  ------------------  |
 --------------------                  ----------------------

The next illustration shows the state of the native object and managed proxy after a call to ComWrappers.GetOrCreateObjectForComInstance(IntPtr, CreateObjectFlags). The concept of "identity" follows the rules for IUnknown.

 ------------------               ------------------
|  Native object   |< = = = = = =|                  |
| Ref count: +1    |             | Mapping from     |
 ------------------              | native identity  |
 ------------------------        | to managed proxy |
|   Managed proxy        |< = = =|                  |
| Created by ComWrappers |        ------------------
|   implementer.         |
| Optional AddRef() on   |
|   native object.       |
 ------------------------

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 CreateObjectFlags.TrackerObject. With this optional strong reference, the reference count would be +2.

Constructors

ComWrappers()

Instance constructor.

Methods

ComputeVtables(Object, CreateComInterfaceFlags, Int32)	Computes the desired Vtable for obj, respecting the values of flags.
CreateObject(IntPtr, CreateObjectFlags)	Creates a managed object for the object that externalComObject points to, respecting the values of flags.
Equals(Object)	Determines whether the specified object is equal to the current object. (Inherited from Object)
GetHashCode()	Serves as the default hash function. (Inherited from Object)
GetIUnknownImpl(IntPtr, IntPtr, IntPtr)	Gets the runtime-provided IUnknown implementation.
GetOrCreateComInterfaceForObject(Object, CreateComInterfaceFlags)	Creates a COM representation of the supplied object that can be passed to a non-managed environment.
GetOrCreateObjectForComInstance(IntPtr, CreateObjectFlags)	Gets the currently registered managed object or creates a new managed object and registers it.
GetOrRegisterObjectForComInstance(IntPtr, CreateObjectFlags, Object)	Gets the currently registered managed object or uses the supplied managed object and registers it.
GetOrRegisterObjectForComInstance(IntPtr, CreateObjectFlags, Object, IntPtr)	Get the currently registered managed object or uses the supplied managed object and registers it.
GetType()	Gets the Type of the current instance. (Inherited from Object)
MemberwiseClone()	Creates a shallow copy of the current Object. (Inherited from Object)
RegisterForMarshalling(ComWrappers)	Registers a ComWrappers instance to be used as the global instance for marshalling in the runtime.
RegisterForTrackerSupport(ComWrappers)	Registers a ComWrappers instance to be used as the global instance for reference tracker support.
ReleaseObjects(IEnumerable)	Releases a collection of objects outside of the normal object or COM interface lifetime.
ToString()	Returns a string that represents the current object. (Inherited from Object)