RecycleBin Manager for VB.NET - by Elektro

' ***********************************************************************
' Author   : Elektro
' Created  : 01-17-2014
' Modified : 01-19-2014
' ***********************************************************************
' <copyright file="RecycleBinManager.vb" company="Elektro Studios">
'     Copyright (c) Elektro Studios. All rights reserved.
' </copyright>
' <summary></summary>
' ***********************************************************************

' Instructions
' 1. Add a reference to 'Microsoft.WindowsAPICodePack.dll'.
' 2. Add a reference to 'Microsoft.WindowsAPICodePack.Shell.dll'.

#Region " Public Members Summary "

' ----------
' Properties
' ----------
'
' MainBin.Files
' MainBin.Folders
' MainBin.Items
' MainBin.ItemsCount
' MainBin.LastDeletedFile
' MainBin.LastDeletedFolder
' MainBin.LastDeletedItem
' MainBin.Size

' -------
' Methods
' -------
'
' MainBin.Empty()
' MainBin.RefreshIcon()
'
' Tools.Empty()
' Tools.GetSize()
' Tools.GetDeletedFiles()
' Tools.GetDeletedFolders()
' Tools.GetDeletedItems()
' Tools.GetItemsCount()
' Tools.GetLastDeletedFile()
' Tools.GetLastDeletedFolder()
' Tools.GetLastDeletedItem()
' Tools.DeleteItem
' Tools.UndeleteItem
' Tools.InvokeItemVerb

#End Region

#Region " Usage Examples "

#Region " Example 1 "

'' Empties all the Recycle Bins.
'RecycleBinManager.MainBin.Empty()

'' Empties the Recycle Bin of the "E" drive.
'RecycleBinManager.Tools.Empty("E", RecycleBinManager.Tools.RecycleBinFlags.DontShowConfirmation)

'' Updates the Main Recycle Bin icon.
'RecycleBinManager.MainBin.RefreshIcon()


'' Gets the accumulated size (in bytes) of the Main Recycle Bin.
'Dim RecycledSize As Long = RecycleBinManager.MainBin.Size

'' Gets the accumulated size (in bytes) of the Recycle Bin on "E" drive.
'Dim RecycledSizeE As Long = RecycleBinManager.Tools.GetSize("E")


'' Gets the total deleted items count of the Main recycle bin.
'Dim RecycledItemsCount As Long = RecycleBinManager.MainBin.ItemsCount

'' Gets the total deleted items count of the Recycle Bin on "E" drive.
'Dim RecycledItemsCountE As Long = RecycleBinManager.Tools.GetDeletedItems("E").Count


'' Get all the deleted items inside the Main Recycle Bin.
'Dim RecycledItems As ShellObject() = RecycleBinManager.MainBin.Items

'' Get all the deleted files inside the Main Recycle Bin.
'Dim RecycledFiles As ShellFile() = RecycleBinManager.MainBin.Files

'' Get all the deleted folders inside the Main Recycle Bin.
'Dim RecycledFolders As ShellFolder() = RecycleBinManager.MainBin.Folders


'' Get all the deleted items inside the Recycle Bin on "E" drive.
'Dim RecycledItemsE As ShellObject() = RecycleBinManager.Tools.GetDeletedItems("E")

'' Get all the deleted files inside the Recycle Bin on "E" drive.
'Dim RecycledFilesE As ShellFile() = RecycleBinManager.Tools.GetDeletedFiles("E")

'' Get all the deleted folders inside the Recycle Bin on "E" drive.
'Dim RecycledFoldersE As ShellFolder() = RecycleBinManager.Tools.GetDeletedFolders("E")


'' Gets the Last deleted Item inside the Main Recycle Bin.
'MsgBox(RecycleBinManager.MainBin.LastDeletedItem.Name)

'' Gets the Last deleted Item inside the Recycle Bin on "E" drive
'MsgBox(RecycleBinManager.Tools.GetLastDeletedItem("E").Name)


'' Undeletes an item.
'RecycleBinManager.Tools.UndeleteItem(RecycleBinManager.MainBin.LastDeletedItem)

'' Permanently deletes an item.
'RecycleBinManager.Tools.DeleteItem(RecycleBinManager.MainBin.LastDeletedItem)

'' Invokes an Item-Verb
'RecycleBinManager.Tools.InvokeItemVerb(RecycleBinManager.MainBin.LastDeletedItem, "properties")

#End Region

#Region " Example 2 "

'Private Sub Test() Handles MyBase.Shown

'    Dim sb As New System.Text.StringBuilder

'    ' Get all the deleted items inside all the Recycle Bins.
'    Dim RecycledItems As ShellObject() = RecycleBinManager.MainBin.Items

'    ' Loop through the deleted Items (Ordered by las deleted).
'    For Each Item As ShellFile In (From itm In RecycledItems
'                                   Order By itm.Properties.GetProperty("System.Recycle.DateDeleted").ValueAsObject
'                                   Descending)

'        ' Append the property bags information.
'        sb.AppendLine(String.Format("Full Name....: {0}",
'                                    Item.Name))

'        sb.AppendLine(String.Format("Item Name....: {0}",
'                                    Item.Properties.System.ItemNameDisplay.Value))

'        sb.AppendLine(String.Format("Deleted From.: {0}",
'                                    Item.Properties.GetProperty("System.Recycle.DeletedFrom").ValueAsObject))

'        sb.AppendLine(String.Format("Item Type....: {0}",
'                                   Item.Properties.System.ItemTypeText.Value))

'        sb.AppendLine(String.Format("Item Size....: {0}",
'                                    CStr(Item.Properties.System.Size.Value)))

'        sb.AppendLine(String.Format("Attributes...: {0}",
'                                    [Enum].Parse(GetType(IO.FileAttributes),
'                                                 Item.Properties.System.FileAttributes.Value).ToString))

'        sb.AppendLine(String.Format("Date Deleted.: {0}",
'                                    Item.Properties.GetProperty("System.Recycle.DateDeleted").ValueAsObject))

'        sb.AppendLine(String.Format("Date Modified: {0}",
'                                    CStr(Item.Properties.System.DateModified.Value)))

'        sb.AppendLine(String.Format("Date Created.: {0}",
'                                    CStr(Item.Properties.System.DateCreated.Value)))

'        MsgBox(sb.ToString)
'        sb.Clear()

'    Next Item

'End Sub

#End Region

#End Region

#Region " Imports "

Imports System.ComponentModel
Imports System.Runtime.InteropServices
Imports System.Text
Imports Microsoft.WindowsAPICodePack.Shell

#End Region

''' <summary>
''' Retrieves Recycle Bin's information and performs other operations.
''' </summary>
Public NotInheritable Class RecycleBinManager

#Region " Recycle Bin Folder "

    ''' <summary>
    ''' The Recycle Bin virtual folder object.
    ''' </summary>
    Private Shared ReadOnly RecycleBin As IKnownFolder = KnownFolders.RecycleBin

#End Region

#Region " API "

    ''' <summary>
    ''' WinAPI things.
    ''' </summary>
    Private NotInheritable Class NativeMethods

#Region " Methods "

        ''' <summary>
        ''' Empties the Recycle Bin on the specified drive.
        ''' </summary>
        ''' <param name="hWnd">A handle to the parent window of any dialog boxes that might be displayed during the operation.
        ''' This parameter can be NULL.</param>
        ''' <param name="RootPath">The address of a null-terminated string of maximum length MAX_PATH that contains the path of the
        ''' root drive on which the Recycle Bin is located.
        ''' This parameter can contain the address of a string formatted with the drive, folder, and subfolder names,
        ''' for example 'c:\windows\system\'.
        ''' It can also contain an empty string or NULL.
        ''' If this value is an empty string or NULL, all Recycle Bins on all drives will be emptied.</param>
        ''' <param name="Flags">Specifies the Recycle bin behavior, this parameter can be one or more flags.</param>
        ''' <returns><c>true</c> if operation succeeds, <c>false</c> otherwise.</returns>
        <DllImport("shell32.dll", EntryPoint:="SHEmptyRecycleBin", CharSet:=CharSet.Unicode)>
        Public Shared Function EmptyRecycleBin(
                      Optional ByVal hWnd As IntPtr = Nothing,
                      Optional ByVal RootPath As String = Nothing,
                      Optional ByVal Flags As Tools.RecycleBinFlags = Nothing
        ) As Boolean
        End Function

        ''' <summary>
        ''' Updates the Recycle Bin icon on the desktop to reflect the state of the systemwide Recycle Bin,
        ''' for example if an error occurs during an 'EmptyRecycleBin' operation.
        ''' But since the other Recycle Bin management functions will update this icon on their own,
        ''' there's almost no reason why your applications would need to call this function explicitly.
        ''' </summary>
        ''' <returns><c>true</c> if operation succeeds, <c>false</c> otherwise.</returns>
        <DllImport("shell32.dll", EntryPoint:="SHUpdateRecycleBinIcon")>
        Public Shared Function UpdateRecycleBinIcon(
        ) As Boolean
        End Function

        ''' <summary>
        ''' Retrieves the accumulated size of the Recycle Bin and the number of items in it, for a specified drive.
        ''' </summary>
        ''' <param name="RootPath">The address of a null-terminated string of maximum length MAX_PATH to contain the path of the
        ''' root drive on which the Recycle Bin is located.
        ''' This parameter can contain the address of a string formatted with the drive, folder,
        ''' and subfolder names (C:\Windows\System32\).</param>
        ''' <param name="QueryRBInfo">The address of a SHQUERYRBINFO structure that receives the Recycle Bin information.
        ''' The 'StructSize' member of the structure must be set to the size of the structure before calling this API.</param>
        ''' <returns><c>true</c> if operation succeeds, <c>false</c> otherwise.</returns>
        <DllImport("shell32.dll", EntryPoint:="SHQueryRecycleBin", CharSet:=CharSet.Unicode)>
        Public Shared Function QueryRecycleBin(
                      ByVal RootPath As String,
                      ByRef QueryRBInfo As SHQUERYRBINFO
        ) As Boolean
        End Function

        ''' <summary>
        ''' Determines the number of items in the specified menu.
        ''' </summary>
        ''' <param name="hMenu">A handle to the menu to be examined.</param>
        ''' <returns>
        ''' If the function succeeds, the return value specifies the number of items in the menu.
        ''' If the function fails, the return value is -1.</returns>
        <DllImport("user32.dll")>
        Public Shared Function GetMenuItemCount(
                  ByVal hMenu As IntPtr
        ) As Integer
        End Function

        ''' <summary>
        ''' Retrieves the menu item identifier of a menu item located at the specified position in a menu.
        ''' </summary>
        ''' <param name="hMenu">
        ''' A handle to the menu that contains the item whose identifier is to be retrieved.
        ''' </param>
        ''' <param name="nPos">
        ''' The zero-based relative position of the menu item whose identifier is to be retrieved.
        ''' </param>
        ''' <returns>
        ''' The return value is the identifier of the specified menu item.
        ''' If the menu item identifier is NULL or if the specified item opens a submenu, the return value is -1.
        ''' </returns>
        <DllImport("user32.dll")> _
        Public Shared Function GetMenuItemID(
                  ByVal hMenu As IntPtr,
                  ByVal nPos As Integer
        ) As Integer
        End Function

        ''' <summary>
        ''' Creates and initializes a Shell item object from a parsing name.
        ''' </summary>
        ''' <param name="path">
        ''' A pointer to a display name.
        ''' </param>
        ''' <param name="pbc">
        ''' Optional.
        ''' A pointer to a bind context used to pass parameters as inputs and outputs to the parsing function.
        ''' These passed parameters are often specific to the data source and are documented by the data source owners.
        ''' </param>
        ''' <param name="riid">
        ''' A reference to the IID of the interface to retrieve through ppv,
        ''' typically IID_IShellItem or IID_IShellItem2.
        ''' </param>
        ''' <param name="item">
        ''' When this method returns successfully, contains the interface pointer requested in riid.
        ''' This is typically IShellItem or IShellItem2.</param>
        ''' <returns>System.Int32.</returns>
        <DllImport("shell32.dll", CharSet:=CharSet.Unicode, SetLastError:=True)> _
        Public Shared Function SHCreateItemFromParsingName(
                  ByVal path As String,
                  ByVal pbc As IntPtr, <MarshalAs(UnmanagedType.LPStruct)>
                  ByVal riid As Guid,
                  ByRef item As IShellItem
        ) As Integer
        End Function

#End Region

#Region " Interfaces "

        ''' <summary>
        ''' Exposes methods that retrieve information about a Shell item.
        ''' IShellItem and IShellItem2 are the preferred representations of items in any new code.
        ''' </summary>
        <ComImport, Guid("43826D1E-E718-42EE-BC55-A1E261C37BFE"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)>
        Interface IShellItem

            REM NOTE: This interface is only partially defined, don't use it in other contexts.

            ''' <summary>
            ''' Binds to a handler for an item as specified by the handler ID value (BHID).
            ''' </summary>
            ''' <param name="pbc">
            ''' A pointer to an IBindCtx interface on a bind context object.
            ''' Used to pass optional parameters to the handler.
            ''' The contents of the bind context are handler-specific.
            ''' For example, when binding to BHID_Stream, the STGM flags in the bind context indicate the
            ''' mode of access desired (read or read/write).</param>
            ''' <param name="bhid">
            ''' Reference to a GUID that specifies which handler will be created.
            ''' One of the following values defined in Shlguid.h.</param>
            ''' <param name="riid">
            ''' IID of the object type to retrieve.
            ''' </param>
            ''' <param name="ppv">
            ''' When this method returns,
            ''' contains a pointer of type riid that is returned by the handler specified by rbhid.
            ''' </param>
            ''' <returns>System.Int32.</returns>
            <PreserveSig>
            Function BindToHandler(
                 ByVal pbc As IntPtr,
                 <MarshalAs(UnmanagedType.LPStruct)> ByVal bhid As Guid,
                 <MarshalAs(UnmanagedType.LPStruct)> ByVal riid As Guid,
                 ByRef ppv As IContextMenu
        ) As Integer
        End Interface

        ''' <summary>
        ''' Exposes methods that either create or merge a shortcut menu associated with a Shell object.
        ''' </summary>
        <ComImport, Guid("000214e4-0000-0000-c000-000000000046"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)>
        Interface IContextMenu

            ''' <summary>
            ''' Adds commands to a shortcut menu.
            ''' </summary>
            ''' <param name="hmenu">
            ''' A handle to the shortcut menu.
            ''' The handler should specify this handle when adding menu items.
            ''' </param>
            ''' <param name="iMenu">
            ''' The zero-based position at which to insert the first new menu item.
            ''' </param>
            ''' <param name="idCmdFirst">
            ''' The minimum value that the handler can specify for a menu item identifier.
            ''' </param>
            ''' <param name="idCmdLast">
            ''' The maximum value that the handler can specify for a menu item identifier.
            ''' </param>
            ''' <param name="uFlags">
            ''' Optional flags that specify how the shortcut menu can be changed.
            ''' The remaining bits of the low-order word are reserved by the system.
            ''' The high-order word can be used for context-specific communications.
            ''' The CMF_RESERVED value can be used to mask the low-order word.</param>
            ''' <returns>System.Int32.</returns>
            <PreserveSig>
            Function QueryContextMenu(
                 ByVal hmenu As IntPtr,
                 ByVal iMenu As Integer,
                 ByVal idCmdFirst As Integer,
                 ByVal idCmdLast As Integer,
                 ByVal uFlags As QueryContextMenuFlags
        ) As Integer

            ''' <summary>
            ''' Carries out the command associated with a shortcut menu item.
            ''' </summary>
            ''' <param name="pici">
            ''' A pointer to a CMINVOKECOMMANDINFO or CMINVOKECOMMANDINFOEX structure that contains
            ''' specifics about the command.</param>
            ''' <returns>System.Int32.</returns>
            <PreserveSig>
            Function InvokeCommand(
                 ByRef pici As CMINVOKECOMMANDINFO
        ) As Integer

            ''' <summary>
            ''' Gets information about a shortcut menu command,
            ''' including the help string and the language-independent, or canonical, name for the command.
            ''' </summary>
            ''' <param name="idCmd">
            ''' Menu command identifier offset.
            ''' </param>
            ''' <param name="uFlags">
            ''' Flags specifying the information to return.
            ''' </param>
            ''' <param name="pwReserved">
            ''' Reserved.
            ''' Applications must specify NULL when calling this method and
            ''' handlers must ignore this parameter when called.
            ''' </param>
            ''' <param name="pszName">
            ''' The address of the buffer to receive the null-terminated string being retrieved.
            ''' </param>
            ''' <param name="cchMax">
            ''' Size of the buffer, in characters, to receive the null-terminated string.
            ''' </param>
            ''' <returns>System.Int32.</returns>
            <PreserveSig>
            Function GetCommandString(
                 ByVal idCmd As Integer,
                 ByVal uFlags As GetCommandStringFlags,
                 ByVal pwReserved As IntPtr,
                 <MarshalAs(UnmanagedType.LPWStr)> ByVal pszName As StringBuilder,
                 ByVal cchMax As Integer) As Integer
        End Interface

#End Region

#Region " Enumerations "

        ''' <summary>
        ''' Optional flags that specify how a shortcut menu can be changed.
        ''' </summary>
        <Description("'uFlags' parameter used in 'QueryContextMenu' function")>
        Public Enum QueryContextMenuFlags As Integer

            REM NOTE: This Enum is only partially defined, don't use it in other contexts.

            ''' <summary>
            ''' Indicates normal operation.
            ''' A shortcut menu extension, namespace extension, or drag-and-drop handler can add all menu items.
            ''' </summary>
            CMF_NORMAL = &H0

        End Enum

        ''' <summary>
        ''' Flags specifying the information to return.
        ''' </summary>
        <Description("'uFlags' parameter used in 'GetCommandString' function")>
        Public Enum GetCommandStringFlags As Integer

            REM NOTE: This Enum is only partially defined, don't use it in other contexts.

            ''' <summary>
            ''' Sets pszName to a Unicode string containing the language-independent command name for the menu item.
            ''' </summary>
            GCS_VERBW = &H4

        End Enum

#End Region

#Region " Structures "

        ''' <summary>
        ''' Contains the accumulated size and item count information retrieved by the 'QueryRecycleBin' function.
        ''' </summary>
        <Description("'QueryRBInfo' parameter of 'QueryRecycleBin' function.")>
        <StructLayout(LayoutKind.Sequential)> _
        Public Structure SHQUERYRBINFO

            ''' <summary>
            ''' The size of the structure, in bytes.
            ''' This member must be filled in prior to calling the function.
            ''' </summary>
            Public StructSize As Integer

            ''' <summary>
            ''' The total size of all the objects in the specified Recycle Bin, in bytes.
            ''' </summary>
            Public BinSize As Long

            ''' <summary>
            ''' The total number of items in the specified Recycle Bin.
            ''' </summary>
            Public ItemCount As Long

        End Structure

        ''' <summary>
        ''' Contains information needed by IContextMenu::InvokeCommand to invoke a shortcut menu command.
        ''' </summary>
        <Description("'pici' parameter used in 'InvokeCommand' function")>
        <StructLayout(LayoutKind.Sequential, CharSet:=CharSet.Unicode)>
        Structure CMINVOKECOMMANDINFO

            ''' <summary>
            ''' The size of this structure, in bytes.
            ''' </summary>
            Public cbSize As Integer

            ''' <summary>
            ''' Zero, or one or more of the CMINVOKECOMMANDINFO flags.
            ''' </summary>
            Public fMask As Integer

            ''' <summary>
            ''' A handle to the window that is the owner of the shortcut menu.
            ''' An extension can also use this handle as the owner of any message boxes or dialog boxes it displays.
            ''' </summary>
            Public hwnd As IntPtr

            ''' <summary>
            ''' The address of a null-terminated string that specifies the language-independent name
            ''' of the command to carry out.
            ''' This member is typically a string when a command is being activated by an application.
            ''' The system provides predefined constant values for the following command strings.
            ''' </summary>
            Public lpVerb As IntPtr

            ''' <summary>
            ''' An optional string containing parameters that are passed to the command.
            ''' The format of this string is determined by the command that is to be invoked.
            ''' This member is always NULL for menu items inserted by a Shell extension.
            ''' </summary>
            Public lpParameters As String

            ''' <summary>
            ''' An optional working directory name.
            ''' This member is always NULL for menu items inserted by a Shell extension.
            ''' </summary>
            Public lpDirectory As String

            ''' <summary>
            ''' A set of SW_ values to pass to the ShowWindow function if the command
            ''' displays a window or starts an application.
            ''' </summary>
            Public nShow As Integer

            ''' <summary>
            ''' An optional keyboard shortcut to assign to any application activated by the command.
            ''' If the fMask parameter does not specify CMIC_MASK_HOTKEY, this member is ignored.
            ''' </summary>
            Public dwHotKey As Integer

            ''' <summary>
            ''' An icon to use for any application activated by the command.
            ''' If the fMask member does not specify CMIC_MASK_ICON, this member is ignored.
            ''' </summary>
            Public hIcon As IntPtr

        End Structure

#End Region

    End Class

#End Region

#Region " MainBin CLASS "

    ''' <summary>
    ''' Retrieves information about the Main Recycle Bin, and perform other operations.
    ''' The Main Recycle Bin is that one that also contains all the deleted items of the other recycle bins.
    ''' </summary>
    Public Class MainBin

#Region " Members "

#Region " Properties "

        ''' <summary>
        ''' Gets all the items inside the Main recycle bin.
        ''' </summary>
        ''' <value>All the items.</value>
        Public Shared ReadOnly Property Items As ShellObject()
            Get
                Return Tools.GetDeletedItems(Nothing)
            End Get
        End Property

        ''' <summary>
        ''' Gets all the files inside the Main recycle bin.
        ''' </summary>
        ''' <value>The files.</value>
        Public Shared ReadOnly Property Files As ShellFile()
            Get
                Return Tools.GetDeletedFiles(Nothing)
            End Get
        End Property

        ''' <summary>
        ''' Gets all the folders inside the Main recycle bin.
        ''' </summary>
        ''' <value>The folders.</value>
        Public Shared ReadOnly Property Folders As ShellFolder()
            Get
                Return Tools.GetDeletedFolders(Nothing)
            End Get
        End Property

        ''' <summary>
        ''' Gets the last deleted item inside the Main recycle bin.
        ''' </summary>
        ''' <value>The folders.</value>
        Public Shared ReadOnly Property LastDeletedItem As ShellObject
            Get
                Return Tools.GetLastDeletedItem(Nothing)
            End Get
        End Property

        ''' <summary>
        ''' Gets the last deleted file inside the Main recycle bin.
        ''' </summary>
        ''' <value>The folders.</value>
        Public Shared ReadOnly Property LastDeletedFile As ShellFile
            Get
                Return Tools.GetLastDeletedFile(Nothing)
            End Get
        End Property

        ''' <summary>
        ''' Gets the last deleted folder inside the Main recycle bin.
        ''' </summary>
        ''' <value>The folders.</value>
        Public Shared ReadOnly Property LastDeletedFolder As ShellFolder
            Get
                Return Tools.GetLastDeletedFolder(Nothing)
            End Get
        End Property

        ''' <summary>
        ''' Gets the accumulated size of the Main recycle bin.
        ''' </summary>
        ''' <value>The folders.</value>
        Public Shared ReadOnly Property Size As Long
            Get
                Return Tools.GetSize(Nothing)
            End Get
        End Property

        ''' <summary>
        ''' Gets the total deleted items count of the Main recycle bin.
        ''' </summary>
        ''' <value>The folders.</value>
        Public Shared ReadOnly Property ItemsCount As Long
            Get
                Return Tools.GetItemsCount(Nothing)
            End Get
        End Property

#End Region

#End Region

#Region " Public Methods "

        ''' <summary>
        ''' Empties the Master Recycle Bin.
        ''' </summary>
        ''' <param name="Flags">Indicates the recycle bin behavior.</param>
        ''' <returns><c>true</c> if operation succeeds, <c>false</c> otherwise.</returns>
        Public Shared Function Empty(Optional ByVal Flags As Tools.RecycleBinFlags =
                                                             Tools.RecycleBinFlags.DontShowConfirmation) As Boolean

            Return NativeMethods.EmptyRecycleBin(IntPtr.Zero, Nothing, Flags)

        End Function

        ''' <summary>
        ''' Refreshes the Recycle bin icon.
        ''' </summary>
        ''' <returns><c>true</c> if operation succeeds, <c>false</c> otherwise.</returns>
        Public Shared Function RefreshIcon() As Boolean

            Return NativeMethods.UpdateRecycleBinIcon()

        End Function

#End Region

#Region " Hidden methods "

        ' These methods are purposely hidden from Intellisense just to look better without unneeded methods.
        ' NOTE: The methods can be re-enabled at any-time if needed.

        ''' <summary>
        ''' Equalses this instance.
        ''' </summary>
        <EditorBrowsable(EditorBrowsableState.Never)>
        Public Shadows Sub Equals()
        End Sub

        ''' <summary>
        ''' References the equals.
        ''' </summary>
        <EditorBrowsable(EditorBrowsableState.Never)>
        Public Shadows Sub ReferenceEquals()
        End Sub

#End Region

    End Class

#End Region

#Region " Tools CLASS "

    ''' <summary>
    ''' Retrieves information about the Recycle Bin of an specific drive,
    ''' and perform other operations.
    ''' </summary>
    Public Class Tools

#Region " Members "

#Region " Enumerations "

        ''' <summary>
        ''' Specifies the Recycle bin behavior.
        ''' </summary>
        <Description("'RecycleBinFlags' parameter used in 'EmptyRecycleBin' function.")>
        <Flags>
        Public Enum RecycleBinFlags As Integer

            ''' <summary>
            ''' The dont show confirmation
            ''' </summary>
            DontShowConfirmation = &H1

            ''' <summary>
            ''' The dont show progress UI
            ''' </summary>
            DontShowProgressUI = &H2

            ''' <summary>
            ''' The dont play sound
            ''' </summary>
            DontPlaySound = &H4

        End Enum

        ''' <summary>
        ''' A verb is a string used to specify a particular action that an item supports.
        ''' Invoking a verb is equivalent to selecting a command from an item's context menu.
        ''' Typically, invoking a verb launches a related application.
        ''' For example, invoking the "open" verb on a ".txt" file opens the file with a text editor, usually Notepad.
        ''' </summary>
        <Description("'Verb' parameter used in 'InvokeItemVerb' method.")>
        Public Enum ItemVerbs As Integer
            Open = 0
            Delete = 1
            Undelete = 2
            Properties = 3
        End Enum

#End Region

#End Region

#Region " Public Methods "

        ''' <summary>
        ''' Empties the Recycle Bin of an specific Drive.
        ''' </summary>
        ''' <param name="DriveLetter">
        ''' Indicates an specific recycle bin drive letter.
        ''' If this parameter is 'Nothing' then it empties all the Recycle Bins.
        ''' </param>
        ''' <param name="Flags">Indicates the recycle bin behavior.</param>
        ''' <returns><c>true</c> if operation succeeds, <c>false</c> otherwise.</returns>
        Public Shared Function Empty(Optional ByVal DriveLetter As Char = Nothing,
                                     Optional ByVal Flags As RecycleBinFlags =
                                                             RecycleBinFlags.DontShowConfirmation) As Boolean

            Return NativeMethods.EmptyRecycleBin(IntPtr.Zero, DriveLetter, Flags)

        End Function

        ''' <summary>
        ''' Gets the recycle bin accumulated size (in bytes) of an specific Drive.
        ''' </summary>
        ''' <param name="DriveLetter">Indicates an specific recycle bin drive letter.</param>
        ''' <returns>System.Int64.</returns>
        Public Shared Function GetSize(ByVal DriveLetter As Char) As Long

            Dim sqrbi As New NativeMethods.SHQUERYRBINFO() With
                {
                    .StructSize = Marshal.SizeOf(GetType(NativeMethods.SHQUERYRBINFO))
                }

            Select Case DriveLetter = Nothing

                Case True
                    NativeMethods.QueryRecycleBin(String.Empty, sqrbi)

                Case Else
                    NativeMethods.QueryRecycleBin(String.Format("{0}:\", DriveLetter), sqrbi)

            End Select

            Return sqrbi.BinSize

        End Function

        ''' <summary>
        ''' Gets the total item count inside the recycle bin of an specific Drive.
        ''' </summary>
        ''' <param name="DriveLetter">Indicates an specific recycle bin drive letter.</param>
        ''' <returns>System.Int64.</returns>
        Public Shared Function GetItemsCount(ByVal DriveLetter As Char) As Long

            Dim sqrbi As New NativeMethods.SHQUERYRBINFO() With
                {
                    .StructSize = Marshal.SizeOf(GetType(NativeMethods.SHQUERYRBINFO))
                }

            Select Case DriveLetter = Nothing

                Case True
                    NativeMethods.QueryRecycleBin(String.Empty, sqrbi)

                Case Else
                    NativeMethods.QueryRecycleBin(String.Format("{0}:\", DriveLetter), sqrbi)

            End Select

            Return sqrbi.ItemCount

        End Function

        ''' <summary>
        ''' Gets all the deleted items inside the recycle bin of an specific Drive,
        ''' this means all Files and Folders.
        ''' </summary>
        ''' <param name="DriveLetter">Indicates an specific recycle bin drive letter.</param>
        ''' <returns>ShellObject[][].</returns>
        Public Shared Function GetDeletedItems(ByVal DriveLetter As Char) As ShellObject()

            Return (From Item As ShellObject In RecycleBin
                    Where If(DriveLetter = Nothing,
                             Item.Name = Item.Name,
                             Item.Name.StartsWith(DriveLetter,
                                                  StringComparison.InvariantCultureIgnoreCase))).
                    ToArray()

        End Function

        ''' <summary>
        ''' Gets the deleted files inside the recycle bin of an specific Drive.
        ''' </summary>
        ''' <param name="DriveLetter">Indicates an specific recycle bin drive letter.</param>
        ''' <returns>ShellFile[][].</returns>
        Public Shared Function GetDeletedFiles(ByVal DriveLetter As Char) As ShellFile()

            Return GetDeletedItems(Of ShellFile)(DriveLetter)

        End Function

        ''' <summary>
        ''' Gets the deleted folders inside the recycle bin of an specific Drive.
        ''' </summary>
        ''' <param name="DriveLetter">Indicates an specific recycle bin drive letter.</param>
        ''' <returns>IKnownFolder[][].</returns>
        Public Shared Function GetDeletedFolders(ByVal DriveLetter As Char) As ShellFolder()

            Return GetDeletedItems(Of FileSystemKnownFolder)(DriveLetter).
                   Cast(Of ShellFolder).
                   Concat(GetDeletedItems(Of NonFileSystemKnownFolder)(DriveLetter)).
                   Cast(Of ShellFolder).ToArray

        End Function

        ''' <summary>
        ''' Gets the last deleted item inside the recycle bin of an specific Drive.
        ''' </summary>
        ''' <param name="DriveLetter">Indicates an specific recycle bin drive letter.</param>
        ''' <returns>ShellObject.</returns>
        Public Shared Function GetLastDeletedItem(ByVal DriveLetter As Char) As ShellObject

            Return (From Item As ShellObject
                    In GetDeletedItems(DriveLetter)
                    Order By Item.Properties.GetProperty("DateDeleted").ValueAsObject
                    Descending).
                    First

        End Function

        ''' <summary>
        ''' Gets the last deleted file inside the recycle bin of an specific Drive.
        ''' </summary>
        ''' <param name="DriveLetter">Indicates an specific recycle bin drive letter.</param>
        ''' <returns>ShellFile.</returns>
        Public Shared Function GetLastDeletedFile(ByVal DriveLetter As Char) As ShellFile

            Return (From Item As ShellFile
                    In GetDeletedItems(Of ShellFile)(DriveLetter)
                    Order By Item.Properties.GetProperty("DateDeleted").ValueAsObject
                    Descending).
                    First

        End Function

        ''' <summary>
        ''' Gets the last deleted folder inside the recycle bin of an specific Drive.
        ''' </summary>
        ''' <param name="DriveLetter">Indicates an specific recycle bin drive letter.</param>
        ''' <returns>ShellFolder.</returns>
        Public Shared Function GetLastDeletedFolder(ByVal DriveLetter As Char) As ShellFolder

            Return (From Item As ShellFolder
                    In GetDeletedFolders(DriveLetter)
                    Order By Item.Properties.GetProperty("DateDeleted").ValueAsObject
                    Descending).
                    First

        End Function

        ''' <summary>
        ''' Permanently deletes a deleted Item.
        ''' </summary>
        ''' <param name="Item">The item to permanently delete.</param>
        Public Shared Sub DeleteItem(ByVal Item As ShellObject)

            InvokeItemVerb(Item, ItemVerbs.Delete)

        End Sub

        ''' <summary>
        ''' Undeletes a deleted Item.
        ''' </summary>
        ''' <param name="Item">The item to undelete.</param>
        Public Shared Sub UndeleteItem(ByVal Item As ShellObject)

            InvokeItemVerb(Item, ItemVerbs.Undelete)

        End Sub

        ''' <summary>
        ''' Invokes a verb on a ShellObject item.
        ''' </summary>
        ''' <param name="ShellObject">
        ''' Indicates the item.
        ''' </param>
        ''' <param name="Verb">
        ''' Indicates the verb to invoke on the item.
        ''' </param>
        ''' <exception cref="System.ArgumentNullException">ParsingPath</exception>
        ''' <exception cref="System.ComponentModel.Win32Exception">
        ''' </exception>
        Public Shared Sub InvokeItemVerb(ByVal [ShellObject] As ShellObject,
                                          ByVal Verb As String)

            Dim [ShellItem] As NativeMethods.IShellItem = Nothing
            Dim menu As NativeMethods.IContextMenu = Nothing
            Dim BHID_SFUIObject As New Guid("{3981e225-f559-11d3-8e3a-00c04f6837d5}")
            Dim ci As New NativeMethods.CMINVOKECOMMANDINFO
            Dim cm As New ContextMenu
            Dim sb As New StringBuilder(256)
            Dim hr As Integer = -1
            Dim VerbId As Integer = -1
            Dim MenuItemId As Integer = -1

            ' Get an item from the item parsing-path
            hr = NativeMethods.SHCreateItemFromParsingName([ShellObject].Properties.System.ParsingPath.Value,
                                                           IntPtr.Zero,
                                                           GetType(NativeMethods.IShellItem).GUID,
                                                           [ShellItem])

            If hr < 0 Then
                Throw New Win32Exception(hr)
            End If

            ' Get the context menu from the item
            hr = [ShellItem].BindToHandler(IntPtr.Zero, BHID_SFUIObject,
                                           GetType(NativeMethods.IContextMenu).GUID,
                                           menu)

            If hr < 0 Then
                Throw New Win32Exception(hr)
            End If

            ' Build a fake context menu so we can scan it for the verb's menu id.
            hr = menu.QueryContextMenu(cm.Handle, 0, 0, -1,
                                       NativeMethods.QueryContextMenuFlags.CMF_NORMAL)

            If hr < 0 Then
                Throw New Win32Exception(hr)
            End If

            For i As Integer = 0 To (NativeMethods.GetMenuItemCount(cm.Handle) - 1)

                MenuItemId = NativeMethods.GetMenuItemID(cm.Handle, i)

                If MenuItemId < 0 Then
                    Continue For
                End If

                hr = menu.GetCommandString(MenuItemId, NativeMethods.GetCommandStringFlags.GCS_VERBW,
                                           IntPtr.Zero, sb, sb.Capacity)

                If sb.ToString().Equals(Verb, StringComparison.InvariantCultureIgnoreCase) Then
                    VerbId = MenuItemId
                    Exit For
                End If

            Next i

            If VerbId < 0 Then
                Throw New Win32Exception(String.Format("Verb '{0}' is not supported by the item.", Verb))
            End If

            ' Invoke the Verb.
            With ci
                .cbSize = Marshal.SizeOf(GetType(NativeMethods.CMINVOKECOMMANDINFO))
                .lpVerb = New IntPtr(VerbId)
            End With

            hr = menu.InvokeCommand(ci)

            If hr < 0 Then
                Throw New Win32Exception(hr)
            End If

        End Sub

#End Region

#Region " Private Methods "

        ''' <summary>
        ''' Gets the deleted items inside the recycle bin.
        ''' </summary>
        ''' <typeparam name="T">Indicates the kind of deleted items to retrieve (Files, Folders, etc...)</typeparam>
        ''' <param name="DriveLetter">Indicates an specific recycle bin drive letter.
        ''' If this parameter is 'Nothing' then it returns the merged contents of all the Recycle Bins.</param>
        ''' <returns>``0[][].</returns>
        Private Shared Function GetDeletedItems(Of T)(Optional ByVal DriveLetter As Char = Nothing) As T()

            Return (From Item As ShellObject In RecycleBin
                    Where If(DriveLetter = Nothing,
                             Item.GetType = GetType(T),
                             Item.GetType = GetType(T) _
                                  AndAlso Item.Name.StartsWith(DriveLetter,
                                                               StringComparison.InvariantCultureIgnoreCase))).
                    Cast(Of T).
                    ToArray()

        End Function

        ''' <summary>
        ''' Invokes a verb on a ShellObject item.
        ''' </summary>
        ''' <param name="ShellObject">
        ''' Indicates the item.
        ''' </param>
        ''' <param name="Verb">
        ''' Indicates the verb to invoke on the item.
        ''' </param>
        Private Shared Sub InvokeItemVerb(ByVal [ShellObject] As ShellObject,
                                          ByVal Verb As ItemVerbs)

            InvokeItemVerb([ShellObject], Verb.ToString)

        End Sub

#End Region

#Region " Hidden methods "

        ' These methods are purposely hidden from Intellisense just to look better without unneeded methods.
        ' NOTE: The methods can be re-enabled at any-time if needed.

        ''' <summary>
        ''' Equalses this instance.
        ''' </summary>
        <EditorBrowsable(EditorBrowsableState.Never)>
        Public Shadows Sub Equals()
        End Sub

        ''' <summary>
        ''' References the equals.
        ''' </summary>
        <EditorBrowsable(EditorBrowsableState.Never)>
        Public Shadows Sub ReferenceEquals()
        End Sub

#End Region

    End Class

#End Region

#Region " Hidden methods "

    ' These methods are purposely hidden from Intellisense just to look better without unneeded methods.
    ' NOTE: The methods can be re-enabled at any-time if needed.

    ''' <summary>
    ''' Equalses this instance.
    ''' </summary>
    <EditorBrowsable(EditorBrowsableState.Never)>
    Public Shadows Sub Equals()
    End Sub

    ''' <summary>
    ''' References the equals.
    ''' </summary>
    <EditorBrowsable(EditorBrowsableState.Never)>
    Public Shadows Sub ReferenceEquals()
    End Sub

#End Region

End Class