VirtualFS/VirtualFS/IFileSystem.cs

/*
 * VirtualFS - Virtual File System library.
 * Copyright (c) 2013, Grzegorz Russek (grzegorz.russek@gmail.com)
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *
 * Redistributions of source code must retain the above copyright notice,
 * this list of conditions and the following disclaimer.
 *
 * Redistributions in binary form must reproduce the above copyright notice,
 * this list of conditions and the following disclaimer in the documentation
 * and/or other materials provided with the distribution.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
 * THE POSSIBILITY OF SUCH DAMAGE.
 */

using System;
using System.Collections.Generic;
using System.IO;
using System.Text.RegularExpressions;

namespace VirtualFS
{
    /// <summary>Describes basic operations on file system.</summary>
    /// <remarks>All operations involving paths are considered
    /// to include only local file system.</remarks>
    public interface IFileSystem : IDisposable
    {
        /// <summary>Gets reference to root file system.</summary>
        IRootFileSystem RootFileSystem { get; }

        /// <summary>Gets or sets a value indicating whether this file system
        /// has higher priority than others mounted on the same path.</summary>
        /// <remarks>This value must be set corectly before mount.</remarks>
        bool HighPriority { get; set; }

        /// <summary>Gets a value indicating whether this file system is read only.</summary>
        bool IsReadOnly { get; }

        /// <summary>Gets a value indicating whether this file system is busy.</summary>
        /// <remarks>Implementations of file systems should set this flag if any
        /// file is open in this file system.</remarks>
        bool IsBusy { get; }

        #region Common

        /// <summary>Check if given path exists.</summary>
        /// <param name="path">Path to check.</param>
        /// <returns>Returns <c>true</c> if entry does
        /// exist, otherwise <c>false</c>.</returns>
        bool Exists(Path path);

        /// <summary>Get entry located under given path.</summary>
        /// <param name="path">Path to get.</param>
        /// <returns>Returns entry information.</returns>
        Entry GetEntry(Path path);

        /// <summary>Get path to physical file containing entry.</summary>
        /// <remarks>This may not work with all file systems. Implementation
        /// should return null if real path can't be determined.</remarks>
        /// <param name="path">Virtual file system path.</param>
        /// <returns>Real file system path or <c>null</c> if real
        /// path doesn't exist.</returns>
        string EntryRealPath(Path path);

        /// <summary>Copies an existing file or directory to a new location.</summary>
        /// <param name="source">Source path of file or directory.</param>
        /// <param name="destination">Destination path. This path must ba a directory.</param>
        /// <param name="overwrite">If <c>true</c> the destination files and directories
        /// can be overwritten; otherwise, <c>false</c>.</param>
        void Copy(Path source, Path destination, bool overwrite = false);

        /// <summary>Moves an existing file or directory to a new location.</summary>
        /// <param name="source">Source path of file or directory.</param>
        /// <param name="destination">Destination path. This path must ba a directory.</param>
        /// <param name="overwrite">If <c>true</c> the destination files and directories
        /// can be overwritten; otherwise, <c>false</c>. Files that aren't moved
        /// will remain on file system.</param>
        /// <param name="leaveStructure">If <c>true</c> the source directories will be left intact;
        /// otherwise, <c>false</c>.</param>
        void Move(Path source, Path destination, bool overwrite = false, bool leaveStructure = false);

        /// <summary>Change name of the entry under specified path.</summary>
        /// <param name="path">The path to entry which name will be changed.</param>
        /// <param name="newName">The new name of entry.</param>
        void ReName(Path path, string newName);

        #endregion Common

        #region Directory

        /// <summary>Get entries located under given path.</summary>
        /// <param name="path">Path to get.</param>
        /// <param name="mask">Mask to filter out unwanted entries.</param>
        /// <returns>Returns entry information.</returns>
        IEnumerable<Entry> GetEntries(Path path, Regex mask = null);

        /// <summary>Create directory and return new entry.</summary>
        /// <remarks>Parent directory must exist.</remarks>
        /// <param name="path">The directory path to create.</param>
        /// <returns>Created entry.</returns>
        Directory DirectoryCreate(Path path);

        /// <summary>Deletes the specified directory and, if indicated, any subdirectories in the directory.</summary>
        /// <param name="path">The path of the directory to remove.</param>
        /// <param name="recursive">Set <c>true</c> to remove directories, subdirectories, and files in path; otherwise <c>false</c>.</param>
        void DirectoryDelete(Path path, bool recursive = false);

        #endregion Directory

        #region File

        /// <summary>Opens an existing file for reading.</summary>
        /// <param name="path">The file to be opened for reading.</param>
        /// <returns>A read-only <see cref="Stream"/> on the specified path.</returns>
        Stream FileOpenRead(Path path);

        /// <summary>Opens an existing file for writing.</summary>
        /// <param name="path">The file to be opened for writing.</param>
        /// <returns>An unshared <see cref="Stream"/> object on
        /// the specified path with write access.</returns>
        Stream FileOpenWrite(Path path);

        /// <summary>Creates or overwrites a file in the specified path.</summary>
        /// <param name="path">The path and name of the file to create.</param>
        /// <returns>A <see cref="Stream"/> that provides
        /// write access to the file specified in path.</returns>
        Stream FileCreate(Path path);

        /// <summary>Deletes the specified file. An exception is not thrown
        /// if the specified file does not exist.</summary>
        /// <param name="path">The path of the file to be deleted.</param>
        void FileDelete(Path path);

        #endregion File
    }
}