FileSystemOperation class

    ''' ----------------------------------------------------------------------------------------------------
    ''' <summary>
    ''' Exposes methods to copy, move, rename, create, and delete single or multiple shell items at once.
    ''' </summary>
    ''' ----------------------------------------------------------------------------------------------------
    ''' <remarks>
    ''' <see href="https://github.com/misterhaan/au.Shared/tree/master/IO/Files.FileOperation"/>
    ''' <para></para>
    ''' <see href="https://github.com/mlaily/MSDNMagazine2007-.NET-Matters-IFileOperation-in-Windows-Vista"/>
    ''' </remarks>
    ''' ----------------------------------------------------------------------------------------------------
    Public Class FileSystemOperation : Implements IDisposable

#Region " Private Fields "

        ''' <summary>
        ''' The <see cref="IFileOperation"/> interface that exposes methods to
        ''' copy, move, rename, create, and delete shell items.
        ''' </summary>
        Private ReadOnly fileOperation As IFileOperation

        ''' <summary>
        ''' CLSID_FileOperation type.
        ''' </summary>
        Private ReadOnly fileOperationType As Type = Type.GetTypeFromCLSID(New Guid("3ad05575-8857-4850-9277-11b85bdb8e09"))

#End Region

#Region " Properties "

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Gets or sets the flags that control the file operation
        ''' when calling <see cref="FileSystemOperation.PerformOperations()"/> function.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <value>
        ''' The flags that control the file operation
        ''' when <see cref="FileSystemOperation.PerformOperations()"/> function.
        ''' </value>
        ''' ----------------------------------------------------------------------------------------------------
        Public Property OperationFlags() As FileOperationFlags
            Get
                Return Me.operationFlags_
            End Get
            Set(value As FileOperationFlags)
                Me.operationFlags_ = value
            End Set
        End Property
        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' The flags that control the file operation
        ''' when <see cref="FileSystemOperation.PerformOperations()"/> function.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        Private operationFlags_ As FileOperationFlags =
            FileOperationFlags.AddUndoRecord Or
            FileOperationFlags.NoConfirmMakeDir


#End Region

#Region " Constructors "

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Initializes a new instance of the <see cref="FileSystemOperation"/> class.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        Public Sub New()
            Me.New(Nothing)
        End Sub

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Initializes a new instance of the <see cref="FileSystemOperation"/> class.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="owner">
        ''' The parent or owner window for progress and dialog windows.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        Public Sub New(owner As IWin32Window)
            Me.fileOperation = DirectCast(Activator.CreateInstance(Me.fileOperationType), IFileOperation)

            If owner IsNot Nothing Then
                Me.fileOperation.SetOwnerWindow(CUInt(owner.Handle))
            End If
        End Sub

#End Region

#Region " Public Methods "

#Region " Queue Copy "

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Queues a copy operation of a source directory into its own directory.
        ''' <para></para>
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="srcDir">
        ''' Source directory to copy into its own directory.
        ''' </param>
        '''
        ''' <param name="newDirName">
        ''' Gives a new name for the copied directory.
        ''' <para></para>
        ''' If null, the new directory name is the same as the source directory name.
        ''' <para></para>
        ''' Note that for directory duplication to take effect,
        ''' the <see cref="FileSystemOperation.OperationFlags"/> property
        ''' must have the <see cref="FileOperationFlags.RenameCollision"/> flag set
        ''' before calling <see cref="FileSystemOperation.PerformOperations()"/> function.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Sub QueueCopy(srcDir As DirectoryInfo, Optional newDirName As String = "")

            Me.QueueCopy(srcDir, srcDir.Parent, newDirName)

        End Sub

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Queues a copy operation of a source directory to a destination directory.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="srcDir">
        ''' Source directory to copy from.
        ''' </param>
        '''
        ''' <param name="dstDir">
        ''' Destination directory to copy to.
        ''' </param>
        '''
        ''' <param name="newDirName">
        ''' Gives a new name for the copied directory.
        ''' <para></para>
        ''' If null, the new directory name is the same as the source directory name.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Sub QueueCopy(srcDir As DirectoryInfo, dstDir As DirectoryInfo, Optional newDirName As String = "")

            If srcDir Is Nothing Then
                Throw New ArgumentNullException(paramName:=NameOf(srcDir))
            End If

            If Not srcDir.Exists Then
                Throw New DirectoryNotFoundException(message:=$"Source directory does not exist. ({srcDir.FullName})")
            End If

            If dstDir Is Nothing Then
                Throw New ArgumentNullException(paramName:=NameOf(dstDir))
            End If

            If Not dstDir.Exists Then
                Throw New DirectoryNotFoundException(message:=$"Destination directory does not exist. ({dstDir.FullName})")
            End If

            Me.QueueCopy(srcDir.FullName, dstDir.FullName, newDirName)

        End Sub

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Queues a copy operation of a source directory to a destination directory.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="srcDir">
        ''' Source directory to copy from.
        ''' </param>
        '''
        ''' <param name="dstDirPath">
        ''' Destination directory path to copy to.
        ''' </param>
        '''
        ''' <param name="newDirName">
        ''' Gives a new name for the copied directory.
        ''' <para></para>
        ''' If null, the new directory name is the same as the source directory name.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Sub QueueCopy(srcDir As DirectoryInfo, dstDirPath As String, Optional newDirName As String = "")
            Me.QueueCopy(srcDir, New DirectoryInfo(dstDirPath), newDirName)
        End Sub

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Queues a copy operation of a source file into its own directory.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="srcFile">
        ''' Source file to copy into its own directory.
        ''' </param>
        '''
        ''' <param name="newFileName">
        ''' Gives a new name for the copied file.
        ''' <para></para>
        ''' If null, the new file name is the same as the source file name.
        ''' <para></para>
        ''' Note that for file duplication to take effect,
        ''' the <see cref="FileSystemOperation.OperationFlags"/> property
        ''' must have the <see cref="FileOperationFlags.RenameCollision"/> flag set
        ''' before calling <see cref="FileSystemOperation.PerformOperations()"/> function.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Sub QueueCopy(srcFile As FileInfo, Optional newFileName As String = "")

            Me.QueueCopy(srcFile, srcFile.Directory, newFileName)

        End Sub

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Queues a copy operation of a source file to a destination file.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="srcFile">
        ''' Source file to copy from.
        ''' </param>
        '''
        ''' <param name="dstFile">
        ''' Destination file to copy to.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Sub QueueCopy(srcFile As FileInfo, dstFile As FileInfo)

            Me.QueueCopy(srcFile, dstFile?.Directory, dstFile?.Name)

        End Sub

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Queues a copy operation of a source file to a destination directory.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="srcFile">
        ''' Source file to copy from.
        ''' </param>
        '''
        ''' <param name="dstDir">
        ''' Destination directory to copy to.
        ''' </param>
        '''
        ''' <param name="newFileName">
        ''' Gives a new name for the copied file.
        ''' <para></para>
        ''' If null, the new file name is the same as the source file name.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Sub QueueCopy(srcFile As FileInfo, dstDir As DirectoryInfo, Optional newFileName As String = "")

            If srcFile Is Nothing Then
                Throw New ArgumentNullException(paramName:=NameOf(srcFile))
            End If

            If Not srcFile.Exists Then
                Throw New FileNotFoundException(message:="Source file does not exist.", fileName:=srcFile.FullName)
            End If

            If dstDir Is Nothing Then
                Throw New ArgumentNullException(paramName:=NameOf(dstDir))
            End If

            If Not dstDir.Exists Then
                Throw New DirectoryNotFoundException(message:=$"Destination directory does not exist. ({dstDir.FullName})")
            End If

            Me.QueueCopy(srcFile.FullName, dstDir.FullName, newFileName)

        End Sub

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Queues a copy operation of a source file to a destination directory.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="srcFile">
        ''' Source file to copy from.
        ''' </param>
        '''
        ''' <param name="dstDirPath">
        ''' Destination directory path to copy to.
        ''' </param>
        '''
        ''' <param name="newFileName">
        ''' Gives a new name for the copied file.
        ''' <para></para>
        ''' If null, the new file name is the same as the source file name.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Sub QueueCopy(srcFile As FileInfo, dstDirPath As String, Optional newFileName As String = "")

            Me.QueueCopy(srcFile, New DirectoryInfo(dstDirPath), newFileName)

        End Sub

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Queues a copy operation of a source file or directory to a destination directory.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="srcItem">
        ''' Full path to the source file or directory to copy from.
        ''' </param>
        '''
        ''' <param name="dstDir">
        ''' Destination directory to copy to.
        ''' </param>
        '''
        ''' <param name="newItemName">
        ''' Gives a new name for the copied item.
        ''' <para></para>
        ''' If null, the new item name is the same as the source item name.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Sub QueueCopy(srcItem As String, dstDir As DirectoryInfo, Optional newItemName As String = "")

            Me.QueueCopy(srcItem, dstDir?.FullName, newItemName)

        End Sub

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Queues a copy operation of a source file or directory to a destination directory.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="srcItem">
        ''' Full path to the source file or directory to copy from.
        ''' </param>
        '''
        ''' <param name="dstDirPath">
        ''' Destination directory path to copy to.
        ''' </param>
        '''
        ''' <param name="newItemName">
        ''' Gives a new name for the copied item.
        ''' <para></para>
        ''' If null, the new item name is the same as the source item name.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Sub QueueCopy(srcItem As String, dstDirPath As String, Optional newItemName As String = "")

            If String.IsNullOrWhiteSpace(srcItem) Then
                Throw New ArgumentNullException(paramName:=NameOf(srcItem))
            End If

            If String.IsNullOrWhiteSpace(dstDirPath) Then
                Throw New ArgumentNullException(paramName:=NameOf(dstDirPath))
            End If

            Using sourceItem As ComObjectDisposer(Of IShellItem) = Me.GetShellItem(srcItem),
                  destinationDir As ComObjectDisposer(Of IShellItem) = Me.GetShellItem(dstDirPath)

                If sourceItem.Value Is Nothing Then
                    Throw New IOException(message:="Source file or directory does not exist.")
                End If

                If destinationDir.Value Is Nothing Then
                    Throw New IOException(message:="Destination directory does not exist.")
                End If

                Me.fileOperation.SetOperationFlags(Me.operationFlags_)
                Me.fileOperation.CopyItem(sourceItem.Value, destinationDir.Value, newItemName, Nothing)
            End Using

        End Sub

#End Region

#Region " Queue Move "

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Queues a move operation of a source directory to a destination directory.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="srcDir">
        ''' Source directory to move from.
        ''' </param>
        '''
        ''' <param name="dstDir">
        ''' Destination directory to move to.
        ''' </param>
        '''
        ''' <param name="newDirName">
        ''' Gives a new name for the moved directory.
        ''' <para></para>
        ''' If null, the new directory name is the same as the source directory name.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Sub QueueMove(srcDir As DirectoryInfo, dstDir As DirectoryInfo, Optional newDirName As String = "")

            If srcDir Is Nothing Then
                Throw New ArgumentNullException(paramName:=NameOf(srcDir))
            End If

            If Not srcDir.Exists Then
                Throw New DirectoryNotFoundException(message:=$"Source directory does not exist. ({srcDir.FullName})")
            End If

            If dstDir Is Nothing Then
                Throw New ArgumentNullException(paramName:=NameOf(dstDir))
            End If

            If Not dstDir.Exists Then
                Throw New DirectoryNotFoundException(message:=$"Destination directory does not exist. ({dstDir.FullName})")
            End If

            Me.QueueMove(srcDir.FullName, dstDir.FullName, newDirName)

        End Sub

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Queues a move operation of a source directory to a destination directory.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="srcDir">
        ''' Source directory to move from.
        ''' </param>
        '''
        ''' <param name="dstDirPath">
        ''' Destination directory path to move to.
        ''' </param>
        '''
        ''' <param name="newDirName">
        ''' Gives a new name for the moved directory.
        ''' <para></para>
        ''' If null, the new directory name is the same as the source directory name.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Sub QueueMove(srcDir As DirectoryInfo, dstDirPath As String, Optional newDirName As String = "")
            Me.QueueMove(srcDir, New DirectoryInfo(dstDirPath), newDirName)
        End Sub

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Queues a move operation of a source file to a destination file.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="srcFile">
        ''' Source file to move from.
        ''' </param>
        '''
        ''' <param name="dstFile">
        ''' Destination file to move to.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Sub QueueMove(srcFile As FileInfo, dstFile As FileInfo)

            Me.QueueMove(srcFile, dstFile?.Directory, dstFile?.Name)

        End Sub

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Queues a move operation of a source file to a destination directory.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="srcFile">
        ''' Source file to move from.
        ''' </param>
        '''
        ''' <param name="dstDir">
        ''' Destination directory to move to.
        ''' </param>
        '''
        ''' <param name="newFileName">
        ''' Gives a new name for the moved file.
        ''' <para></para>
        ''' If null, the new file name is the same as the source file name.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Sub QueueMove(srcFile As FileInfo, dstDir As DirectoryInfo, Optional newFileName As String = "")

            If srcFile Is Nothing Then
                Throw New ArgumentNullException(paramName:=NameOf(srcFile))
            End If

            If Not srcFile.Exists Then
                Throw New FileNotFoundException(message:="Source file does not exist.", fileName:=srcFile.FullName)
            End If

            If dstDir Is Nothing Then
                Throw New ArgumentNullException(paramName:=NameOf(dstDir))
            End If

            If Not dstDir.Exists Then
                Throw New DirectoryNotFoundException(message:=$"Destination directory does not exist. ({dstDir.FullName})")
            End If

            Me.QueueMove(srcFile.FullName, dstDir.FullName, newFileName)

        End Sub

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Queues a move operation of a source file to a destination directory.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="srcFile">
        ''' Source file to move from.
        ''' </param>
        '''
        ''' <param name="dstDirPath">
        ''' Destination directory path to move to.
        ''' </param>
        '''
        ''' <param name="newFileName">
        ''' Gives a new name for the moved file.
        ''' <para></para>
        ''' If null, the new file name is the same as the source file name.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Sub QueueMove(srcFile As FileInfo, dstDirPath As String, Optional newFileName As String = "")

            Me.QueueMove(srcFile, New DirectoryInfo(dstDirPath), newFileName)

        End Sub

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Queues a move operation of a source file or directory to a destination directory.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="srcItem">
        ''' Full path to the source file or directory to move from.
        ''' </param>
        '''
        ''' <param name="dstDir">
        ''' Destination directory to move to.
        ''' </param>
        '''
        ''' <param name="newItemName">
        ''' Gives a new name for the moved item.
        ''' <para></para>
        ''' If null, the new item name is the same as the source item name.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Sub QueueMove(srcItem As String, dstDir As DirectoryInfo, Optional newItemName As String = "")

            Me.QueueMove(srcItem, dstDir?.FullName, newItemName)

        End Sub

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Queues a move operation of a source file or directory to a destination directory.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="srcItem">
        ''' Full path to the source file or directory to move from.
        ''' </param>
        '''
        ''' <param name="dstDirPath">
        ''' Destination directory path to move to.
        ''' </param>
        '''
        ''' <param name="newItemName">
        ''' Gives a new name for the moved item.
        ''' <para></para>
        ''' If null, the new item name is the same as the source item name.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Sub QueueMove(srcItem As String, dstDirPath As String, Optional newItemName As String = "")

            If String.IsNullOrWhiteSpace(srcItem) Then
                Throw New ArgumentNullException(paramName:=NameOf(srcItem))
            End If

            If String.IsNullOrWhiteSpace(dstDirPath) Then
                Throw New ArgumentNullException(paramName:=NameOf(dstDirPath))
            End If

            Using sourceItem As ComObjectDisposer(Of IShellItem) = Me.GetShellItem(srcItem),
                  destinationDir As ComObjectDisposer(Of IShellItem) = Me.GetShellItem(dstDirPath)

                If sourceItem.Value Is Nothing Then
                    Throw New IOException(message:="Source file or directory does not exist.")
                End If

                If destinationDir.Value Is Nothing Then
                    Throw New IOException(message:="Destination directory does not exist.")
                End If

                Me.fileOperation.SetOperationFlags(Me.operationFlags_)
                Me.fileOperation.MoveItem(sourceItem.Value, destinationDir.Value, newItemName, Nothing)
            End Using

        End Sub

#End Region

#Region " Queue Rename "

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Queues a rename operation for a directory.
        ''' <para></para>
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="dir">
        ''' Directory to rename.
        ''' </param>
        '''
        ''' <param name="newDirName">
        ''' Gives a new name for the directory.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Sub QueueRename(dir As DirectoryInfo, newDirName As String)

            Me.QueueRename(dir?.FullName, newDirName)

        End Sub

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Queues a rename operation for a file.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="file">
        ''' File to rename.
        ''' </param>
        '''
        ''' <param name="newFileName">
        ''' Gives a new name for the file.
        ''' </param>
        '''
        ''' <param name="newFileExtension">
        ''' Optionally, gives a new extension for the file.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Sub QueueRename(file As FileInfo, newFileName As String, Optional newFileExtension As String = "")

            Me.QueueRename(file?.FullName, newFileName, newFileExtension)

        End Sub

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Queues a rename operation for a file or directory.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="item">
        ''' Full path to the file or directory to rename.
        ''' </param>
        '''
        ''' <param name="newItemName">
        ''' Gives a new name for the file or directory.
        ''' </param>
        '''
        ''' <param name="newFileExtension">
        ''' Optionally, and if the item is a file, gives a new extension to it.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Sub QueueRename(item As String, newItemName As String, Optional newFileExtension As String = "")

            If String.IsNullOrWhiteSpace(item) Then
                Throw New ArgumentNullException(paramName:=NameOf(item))
            End If

            newFileExtension = newFileExtension.TrimStart(". ".ToCharArray())

            If File.Exists(item) AndAlso Not String.IsNullOrWhiteSpace(newFileExtension) Then
                Me.QueueMove(item, Path.GetDirectoryName(item), $"{newItemName}.{newFileExtension}")

            Else
                Using sourceItem As ComObjectDisposer(Of IShellItem) = Me.GetShellItem(item)
                    If sourceItem.Value Is Nothing Then
                        Throw New IOException(message:="File or directory does not exist.")
                    End If

                    Me.fileOperation.SetOperationFlags(Me.operationFlags_)
                    Me.fileOperation.RenameItem(sourceItem.Value, newItemName, Nothing)
                End Using

            End If

        End Sub

#End Region

#Region " Queue Create "

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Queues a create operation for a directory.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="newDir">
        ''' Directory to create.
        ''' </param>
        '''
        ''' <param name="attribs">
        ''' Optionally, gives the specified attributes to the created directory.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Sub QueueCreate(newDir As DirectoryInfo,
                               Optional attribs As FileAttributes = FileAttributes.Normal Or
                                                                    FileAttributes.Directory)

            Me.QueueCreate(newDir?.Parent?.FullName, newDir?.FullName, attribs)

        End Sub

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Queues a create operation for a file.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="newFile">
        ''' File to create.
        ''' </param>
        '''
        ''' <param name="attribs">
        ''' Optionally, gives the specified attributes to the created file.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Sub QueueCreate(newFile As FileInfo, Optional attribs As FileAttributes = FileAttributes.Normal)

            Me.QueueCreate(newFile?.Directory?.FullName, newFile?.FullName, attribs)

        End Sub

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Queues a create operation for a file or directory.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="dstDirPath">
        ''' Destination directory path to create the file or directory.
        ''' </param>
        '''
        ''' <param name="newItemName">
        ''' File or directory to create.
        ''' <para></para>
        ''' To create a directory, you must set the <see cref="FileAttributes.Directory"/> flag
        ''' in <paramref name="attribs"/> parameter.
        ''' </param>
        '''
        ''' <param name="attribs">
        ''' Optionally, gives the specified attributes to the created file or directory.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Sub QueueCreate(dstDirPath As String, newItemName As String,
                               Optional attribs As FileAttributes = FileAttributes.Normal)

            If String.IsNullOrWhiteSpace(dstDirPath) Then
                Throw New ArgumentNullException(paramName:=NameOf(dstDirPath))
            End If

            If String.IsNullOrWhiteSpace(newItemName) Then
                Throw New ArgumentNullException(paramName:=NameOf(newItemName))
            End If

            Using destinationDir As ComObjectDisposer(Of IShellItem) = Me.GetShellItem(dstDirPath)

                If destinationDir.Value Is Nothing Then
                    Throw New IOException(message:="Destination directory does not exist.")
                End If

                Me.fileOperation.SetOperationFlags(Me.operationFlags_)
                Me.fileOperation.NewItem(destinationDir.Value, attribs, newItemName, Nothing, Nothing)
            End Using

        End Sub

#End Region

#Region " Queue Delete "

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Queues a delete operation for a directory.
        ''' <para></para>
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="dir">
        ''' Directory to delete.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Sub QueueDelete(dir As DirectoryInfo)

            Me.QueueDelete(dir?.FullName)

        End Sub

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Queues a delete operation for a file.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="file">
        ''' File to delete.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Sub QueueDelete(file As FileInfo)

            Me.QueueDelete(file?.FullName)

        End Sub

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Queues a delete operation for a file or directory.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="item">
        ''' Full path to the file or directory to delete.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Sub QueueDelete(item As String)

            If String.IsNullOrWhiteSpace(item) Then
                Throw New ArgumentNullException(paramName:=NameOf(item))
            End If

            Using sourceItem As ComObjectDisposer(Of IShellItem) = Me.GetShellItem(item)
                If sourceItem.Value Is Nothing Then
                    Throw New IOException(message:="File or directory does not exist.")
                End If

                Me.fileOperation.SetOperationFlags(Me.operationFlags_)
                Me.fileOperation.DeleteItem(sourceItem.Value, Nothing)
            End Using

        End Sub

#End Region

#Region " Other "

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Executes all the queued operations.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <returns>
        ''' If this method succeeds, it returns <see cref="HResult.S_OK"/>.
        ''' Otherwise, it returns an <see cref="HResult"/> error code.
        ''' <para></para>
        ''' Note that if the operation was canceled by the user, this method can still return a success code.
        ''' <para></para>
        ''' Use the <see cref="FileSystemOperation.GetAnyOperationsAborted"/> function to determine if this was the case.
        '''</returns>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Function PerformOperations() As HResult

            Dim result As HResult = HResult.S_OK
            Try
                result = Me.fileOperation.PerformOperations()
            Catch ex As Exception
                ' If something goes wrong the IFileOperation UI will tell the user so we don't have to.
            End Try

            Return result

        End Function

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Gets a value that states whether any file operations initiated
        ''' by a call to <see cref="FileSystemOperation.PerformOperations()"/> were stopped before they were complete.
        ''' <para></para>
        ''' The operations could be stopped either by user action or silently by the system.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <returns>
        ''' <see langword="True"/> if any file operations were aborted before they were complete;
        ''' otherwise, <see langword="False"/>.
        ''' </returns>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Function GetAnyOperationsAborted() As Boolean
            Dim result As Boolean
            Me.fileOperation.GetAnyOperationsAborted(result)
            Return result
        End Function

#End Region

#End Region

#Region " Private Methods "

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Converts a file or directory path to <see cref="IShellItem"/>.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="itemPath">
        ''' The source file or directory path.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <returns>
        ''' The resulting <see cref="ComObjectDisposer(Of IShellItem)"/>.
        ''' </returns>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Private Function GetShellItem(itemPath As String) As ComObjectDisposer(Of IShellItem)
            Dim shellItem As IShellItem = Nothing
            NativeMethods.SHCreateItemFromParsingName(itemPath, IntPtr.Zero, GetType(IShellItem).GUID, shellItem)
            Return New ComObjectDisposer(Of IShellItem)(shellItem)
        End Function

#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.fileOperation IsNot Nothing Then
                    Marshal.FinalReleaseComObject(Me.fileOperation)
                    GC.SuppressFinalize(Me)
                End If

            End If

            Me.isDisposed = True

        End Sub

#End Region

    End Class