ComObjectDisposer class

' ***********************************************************************
' Author   : ElektroStudios
' Modified : 30-March-2022
' ***********************************************************************

#Region " Option Statements "

Option Strict On
Option Explicit On
Option Infer Off

#End Region

#Region " Usage Examples "

' Dim shellItem As IShellItem = Nothing
' NativeMethods.SHCreateItemFromParsingName("C:\", IntPtr.Zero, GetType(IShellItem).GUID, shellItem)
'
' Using comObjectDisposer As New ComObjectDisposer(Of IShellItem)(shellItem)
'     Console.WriteLine(comObjectDisposer.Value.GetDisplayName(ShellItemGetDisplayName.NormalDisplay).ToString())
' End Using

#End Region

#Region " Imports "

Imports System.Runtime.InteropServices

#End Region

#Region " ComObjectDisposer "

' ReSharper disable once CheckNamespace

Namespace DevCase.Interop.Unmanaged

    ''' ----------------------------------------------------------------------------------------------------
    ''' <summary>
    ''' A wrapper for COM objects, which implements <see cref="IDisposable"/>.
    ''' </summary>
    ''' ----------------------------------------------------------------------------------------------------
    ''' <typeparam name="T">
    ''' The type of COM object.
    ''' </typeparam>
    ''' ----------------------------------------------------------------------------------------------------
    ''' <remarks>
    ''' Original implementation: <see href="https://github.com/misterhaan/au.Shared/blob/master/IO/Files.FileOperation/ComDisposer.cs"/>
    ''' </remarks>
    ''' ----------------------------------------------------------------------------------------------------
    ''' <example> This is a code example that demonstrates how to adapt a C# code that uses pointers to VB.NET language.
    ''' <code language="VB.NET">
    ''' Dim shellItem As IShellItem = Nothing
    ''' NativeMethods.SHCreateItemFromParsingName("C:\", IntPtr.Zero, GetType(IShellItem).GUID, shellItem)
    '''
    ''' Using comObjectDisposer As New ComObjectDisposer(Of IShellItem)(shellItem)
    '''     Console.WriteLine(comObjectDisposer.Value.GetDisplayName(ShellItemGetDisplayName.NormalDisplay).ToString())
    ''' End Using
    ''' </code>
    ''' </example>
    ''' ----------------------------------------------------------------------------------------------------
    Public Class ComObjectDisposer(Of T As Class) : Implements IDisposable

#Region " Properties "

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Gets the wrapped COM object.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <value>
        ''' The wrapped COM object.
        ''' </value>
        ''' ----------------------------------------------------------------------------------------------------
        Public Property Value As T
            Get
                Return Me.privateValue
            End Get
            Private Set(value As T)
                Me.privateValue = value
            End Set
        End Property
        ''' <summary>
        ''' The wrapped COM object.
        ''' </summary>
        Private privateValue As T

#End Region

#Region " Constructors "

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Prevents a default instance of the <see cref="ComObjectDisposer(Of T)"/> class from being created.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        Private Sub New()
        End Sub

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Initializes a new instance of the <see cref="ComObjectDisposer(Of T)"/> class.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="obj">
        ''' The COM object to wrap.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <exception cref="ArgumentException">
        ''' obj - Object must be a COM object.
        ''' </exception>
        ''' ----------------------------------------------------------------------------------------------------
        Public Sub New(obj As T)

            If obj IsNot Nothing AndAlso Not obj.GetType().IsCOMObject Then
                Throw New ArgumentException(paramName:=NameOf(obj), message:="Object must be a COM object.")
            End If

            Me.privateValue = obj

        End Sub

#End Region

#Region " IDisposable Implementation "

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Flag to detect redundant calls when disposing.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        Private isDisposed As Boolean = False

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Releases all the resources used by this instance.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Sub Dispose() Implements IDisposable.Dispose
            Me.Dispose(isDisposing:=True)
        End Sub

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.
        ''' Releases unmanaged and, optionally, managed resources.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="isDisposing">
        ''' <see langword="True"/>  to release both managed and unmanaged resources;
        ''' <see langword="False"/> to release only unmanaged resources.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Protected Overridable Sub Dispose(isDisposing As Boolean)

            If (Not Me.isDisposed) AndAlso isDisposing Then

                If Me.Value IsNot Nothing Then
                    Marshal.FinalReleaseComObject(Value)
                    Me.Value = Nothing
                End If

            End If

            Me.isDisposed = True

        End Sub

#End Region

    End Class

End Namespace

#End Region