namespace System.Runtime.InteropServices.Marshalling
{
/// <summary>
- /// COM interface marshaller using a StrategyBasedComWrappers instance
+ /// COM interface marshaller using a <see cref="StrategyBasedComWrappers" /> instance
/// </summary>
/// <remarks>
/// This marshaller will always pass the <see cref="CreateObjectFlags.Unwrap"/> flag
{
private static readonly Guid? TargetInterfaceIID = StrategyBasedComWrappers.DefaultIUnknownInterfaceDetailsStrategy.GetIUnknownDerivedDetails(typeof(T).TypeHandle)?.Iid;
+ /// <summary>
+ /// Convert a managed object to a COM interface pointer for the COM interface represented by <typeparamref name="T"/>.
+ /// </summary>
+ /// <param name="managed">The managed object</param>
+ /// <returns>The COM interface pointer</returns>
public static void* ConvertToUnmanaged(T? managed)
{
if (managed == null)
return CastIUnknownToInterfaceType(unknown);
}
+ /// <summary>
+ /// Convert a COM interface pointer to a managed object.
+ /// </summary>
+ /// <param name="unmanaged">The COM interface pointer</param>
+ /// <remarks>
+ /// If the passed in COM interface pointer wraps a managed object, this method returns the underlying object.
+ /// </remarks>
public static T? ConvertToManaged(void* unmanaged)
{
if (unmanaged == null)
return (T)StrategyBasedComWrappers.DefaultMarshallingInstance.GetOrCreateObjectForComInstance((nint)unmanaged, CreateObjectFlags.Unwrap);
}
+ /// <summary>
+ /// Release a reference to the COM interface pointer.
+ /// </summary>
+ /// <param name="unmanaged">A COM interface pointer.</param>
public static void Free(void* unmanaged)
{
if (unmanaged != null)
_instancePointer = IUnknownStrategy.CreateInstancePointer(thisPointer);
}
+ /// <summary>
+ /// Release all references to the underlying COM object.
+ /// </summary>
~ComObject()
{
CacheStrategy.Clear(IUnknownStrategy);
internal bool UniqueInstance { get; init; }
/// <summary>
- /// Releases all references owned by this ComObject if it is a unique instance.
+ /// Releases all references owned by this <see cref="ComObject" /> if it is a unique instance.
/// </summary>
/// <remarks>
- /// This method does nothing if the ComObject was not created with
- /// CreateObjectFlags.UniqueInstance.
+ /// This method does nothing if the <see cref="ComObject" /> was not created with
+ /// <see cref="CreateObjectFlags.UniqueInstance" />.
/// </remarks>
public void FinalRelease()
{
namespace System.Runtime.InteropServices.Marshalling
{
+ /// <summary>
+ /// Specifies that code should be generated to enable exposing the attributed class to COM.
+ /// </summary>
+ /// <remarks>
+ /// This attribute is only valid on types that implement at least one <see cref="GeneratedComInterfaceAttribute"/>-attributed interface.
+ /// </remarks>
[AttributeUsage(AttributeTargets.Class)]
public sealed class GeneratedComClassAttribute : Attribute
{
namespace System.Runtime.InteropServices.Marshalling
{
+ /// <summary>
+ /// Specifies that the attributed type is a COM interface and that the source generator should generate code for it.
+ /// </summary>
[AttributeUsage(AttributeTargets.Interface)]
public class GeneratedComInterfaceAttribute : Attribute
{
[CustomMarshaller(typeof(CustomMarshallerAttribute.GenericPlaceholder), MarshalMode.Default, typeof(UniqueComInterfaceMarshaller<>))]
public static unsafe class UniqueComInterfaceMarshaller<T>
{
+ /// <summary>
+ /// Convert a managed object to a COM interface pointer for the COM interface represented by <typeparamref name="T"/>.
+ /// </summary>
+ /// <param name="managed">The managed object</param>
+ /// <returns>The COM interface pointer</returns>
public static void* ConvertToUnmanaged(T? managed)
{
if (managed == null)
return ComInterfaceMarshaller<T>.CastIUnknownToInterfaceType(unknown);
}
+
+ /// <summary>
+ /// Convert a COM interface pointer to a managed object.
+ /// </summary>
+ /// <param name="unmanaged">The COM interface pointer</param>
+ /// <returns>A managed object that represents the passed in COM interface pointer.</returns>
+ /// <remarks>
+ /// If the passed in COM interface pointer wraps a managed object, this method returns the underlying object.
+ /// </remarks>
public static T? ConvertToManaged(void* unmanaged)
{
if (unmanaged == null)
return (T)StrategyBasedComWrappers.DefaultMarshallingInstance.GetOrCreateObjectForComInstance((nint)unmanaged, CreateObjectFlags.Unwrap | CreateObjectFlags.UniqueInstance);
}
+
+ /// <summary>
+ /// Release a reference to the COM interface pointer.
+ /// </summary>
+ /// <param name="unmanaged">A COM interface pointer.</param>
public static void Free(void* unmanaged)
{
if (unmanaged != null)