WindowsStorable

Represents storage objects that reside in NTFS, FAT32, ExFAT, UDF, ReFS, SMB, and CSVFS. Almost all of features are provided by Windows API.

Definition

public interface IWindowsStorable {} :  IStorable, IDisposable /* and some base abstraction layer interfaces */ {}
public abstract class WindowsStorable : IWindowsStorable {}
public class WindowsFile :              WindowsStorable, IFile {}
public class WindowsFolder :            WindowsStorable, IFolder {}

Initialization

// See the next code block for what parameters to be input.
new WindowsFile(/* parameters */);
new WindowsFolder(/* parameters */);

If the path you're having isn't obvious whether it's a file or a folder, you can use NativeStorable.Parse() static method instead of respective constructors, which, in fact, also use this method internally. The parsing method only can parse back paths returned from shell item name methods with SHGDN_FORPARSING, and some display paths that the File Explorer's path box can parse.

// Shell namespace with known folder ID (you can prepend "Shell:" optionally)
WindowsStorable.Parse(/* Guid */ PInvoke.FOLDERID_ComputerFolder);
WindowsStorable.Parse(@"::{679F85CB-0220-4080-B29B-5540CC05AAB6}");
WindowsStorable.Parse(@"::{031E4825-7B94-4DC3-B131-E946B44C8DD5}\Documents.library-ms");

// Known folder names (if the former is input, it would be converted into canocical name first and then parsed)
WindowsStorable.Parse(@"This PC");          // Display name of a known folder
WindowsStorable.Parse(@"MyComputerFolder"); // Canonical name of a known folder

// LFS (local file system)
WindowsStorable.Parse(@"C:\Windows");
WindowsStorable.Parse(@"C:\Windows\notepad.exe");

// UNC
WindowsStorable.Parse(@"\\?\C:\Window");
WindowsStorable.Parse(@"\\?\C:\Windows\notepad.exe");

Implementations

Locatability

Parsabe string path

What this returns can be parsed back through WindowsStorable.Parse and so can be used as a handy locatable object.

WindowsStorableHelper.GetDisplayName(storable, SHGDN.SHGDN_FORPARSING);

IShellItem instance

This provides a pointer to unmanaged COM onjects, lifecycle of which must not be managed in any other places than IWindowsStorable.Dispose.

INativeStorable storable = new NativeStorable(...);
IShellItem* pShellItem = storable.GetDangerousPtr();

Children enumeration

Utilizes IShellFolder::EnumObjects() and IAsyncEnumerable to yield an item for each.

await (var item in storable.GetChildrenAsync())
{
    // Do something
}

File system operations

Utilizes legacy Win32 API for objects reside in LFS and Windows Shell API only for objects reside in shell namespace.

Here's the implementation example of Copy operation:

public IAsyncOperationWithProgress<StorageOperationResult,uint> CopyAsync(
    IStorable target,
    IModifiableStorable destination,
    StorageOperationFlags flags,
    CancellationToken token);

For more detailed info, visit the storage operations

Disposal

The storable retains a pointer object to IShellItem as a field as ahorementioned and it has to be released when it's no longer needed.

private ComPtr<IShellItem> _dengerousPtr;

/// <inheritdoc/>
public void IDisposable.Dispose()
{
    _dengerousPtr.Release();
}

Usage scenarios

This sample shows usage in Windows Shell folder services, utilizing its helper.

// Enumerating shell objects

IFolder folder = new WindowsFolder("::{679F85CB-0220-4080-B29B-5540CC05AAB6}");

List<IStandardStorageItem> items = [];
await foreach (var storable in folder.GetChildrenAsync())
{
    if (item is IFolder)
        continue;

    items.Add(new WidgetRecentItem(storable));
}

// Removing it from the shell folder

public async Task<bool> RemoveAsync(INativeStorable storable)
{
    try
    {
        await WindowsStorableHelper.InvokeVerbAsync(storable, "unpinfromhome");
        return true;
    }
    catch (COMException ex)
    {
        return false;
    }
}

public WidgetRecentItem(INativeStorable storable)
{
    Storable = storable;
    Path = WindowsStorableHelper.GetDisplayName(storable, SIGDN.SIGDN_DESKTOPABSOLUTEEDITING);
    Name = WindowsStorableHelper.GetDisplayName(storable, SIGDN.SIGDN_NORMALDISPLAY);
    LastModified = WindowsStorableHelper.GetPropertyValue<DateTime>(storable, "System.DateModified");
}

WindowsStorableHelper

This provides a bunch of methods that supply the various requirements in NativeStorable without messing INativeStorables.

Basic definition of the methods is as follows:

public string GetDisplayName(INativeStorable storable/*, ... */)
{
    try
    {
        // This returns IShellItem pointer and should not be disposed within this scope, just use pointer and leave as is.
        var pShellItem = storable.GetDangerousInstance();

        // TODO: Use this instance to get display name, for example.
    }
    catch (Exception ex)
    {
    }
}