// /***************************************************************************
// Aaru Data Preservation Suite
// ----------------------------------------------------------------------------
//
// Filename       : IArchive.cs
// Author(s)      : Michael Drüing <michael@drueing.de>
//
// Component      : Archives.
//
// --[ Description ] ----------------------------------------------------------
//
//     Defines the interface for implementing archive plugins.
//
// --[ License ] --------------------------------------------------------------
//
//     This library is free software; you can redistribute it and/or modify
//     it under the terms of the GNU Lesser General Public License as
//     published by the Free Software Foundation; either version 2.1 of the
//     License, or (at your option) any later version.
//
//     This library is distributed in the hope that it will be useful, but
//     WITHOUT ANY WARRANTY; without even the implied warranty of
//     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
//     Lesser General Public License for more details.
//
//     You should have received a copy of the GNU Lesser General Public
//     License along with this library; if not, see <http://www.gnu.org/licenses/>.
//
// ----------------------------------------------------------------------------
// Copyright © 2018-2023 Michael Drüing
// Copyright © 2011-2023 Natalia Portillo
// ****************************************************************************/

// ReSharper disable UnusedMember.Global

using System;
using System.Collections.Generic;
using System.IO;
using System.Text;
using Aaru.CommonTypes.Enums;

namespace Aaru.CommonTypes.Interfaces;

/// <summary>Supported archive features</summary>
[Flags]
public enum ArchiveSupportedFeature : uint
{
    /// <summary>The archive supports filenames for its entries. If this flag is not set, files can only be accessed by number.</summary>
    SupportsFilenames = 1 << 0,
    /// <summary>
    ///     The archive supports compression. If this flag is not set, compressed and uncompressed lengths are always the
    ///     same.
    /// </summary>
    SupportsCompression = 1 << 1,
    /// <summary>
    ///     The archive supports subdirectories. If this flag is not set, all filenames are guaranteed to not contain any
    ///     "/" character.
    /// </summary>
    SupportsSubdirectories = 1 << 2,
    /// <summary>
    ///     The archive supports explicit entries for directories (like Zip, for example). If this flag is not set,
    ///     directories are implicit by the relative name of the files.
    /// </summary>
    HasExplicitDirectories = 1 << 3,
    /// <summary>The archive stores a timestamp with each entry if this flag is set.</summary>
    HasEntryTimestamp = 1 << 4,
    /// <summary>If this flag is set, individual files or the whole archive might be encrypted or password-protected.</summary>
    SupportsProtection = 1 << 5, // TODO: not implemented yet

    /// <summary>If this flag is set, the archive supports returning extended attributes (Xattrs) for each entry.</summary>
    SupportsXAttrs = 1 << 6
}

/// <summary>Defines the interface to handle an archive (e.g. ZIP, WAD, etc)</summary>
public interface IArchive
{
    /// <summary>Descriptive name of the plugin</summary>
    string Name { get; }

    /// <summary>Unique UUID of the plugin</summary>
    Guid Id { get; }

    /// <summary>Plugin author</summary>
    string Author { get; }

    /// <summary>Identifies if the specified filter contains data recognizable by this archive instance</summary>
    /// <param name="filter">Filter that contains the archive. This allows use to handle .tar.gz and similars.</param>
    bool Identify(IFilter filter);

    /// <summary>Opens the specified stream with this archive instance</summary>
    /// <param name="filter">Filter that contains the archive. This allows use to handle .tar.gz and similars.</param>
    ErrorNumber Open(IFilter filter, Encoding encoding);

    /// <summary>
    ///     Returns true if the archive has a file/stream/buffer currently opened and no
    ///     <see cref="M:Aaru.Filters.Filter.Close" /> has been issued.
    /// </summary>
    bool IsOpened();

    /// <summary>Closes all opened streams.</summary>
    void Close();

    /// <summary>Return a bitfield indicating the features supported by this archive type.</summary>
    /// <returns>The <c>ArchiveSupportedFeature</c> bitfield.</returns>
    /// <remarks>
    ///     If the archive is not opened, this returns the capabilities of the archive format, otherwise it returns the
    ///     capabilities in use by the currently opened archive.
    /// </remarks>
    ArchiveSupportedFeature GetArchiveFeatures();

    /// <summary>Gets the number of entries (i.e. files) that are contained in this archive.</summary>
    /// <remarks>
    ///     Entries in this context can also mean directories or volume labels, for some types of archives that store
    ///     these explicitly. Do not rely on all entries being regular files!
    /// </remarks>
    /// <returns>The number of files.</returns>
    int GetNumberOfEntries();

    /// <summary>Gets the file name (and path) of the given entry in the archive.</summary>
    /// <remarks>
    ///     The path components are separated by a forward slash "/". <br /> The path should not start with a leading
    ///     slash (i.e. it should be relative, not absolute).
    /// </remarks>
    /// <seealso cref="Stat(int)" />
    /// <param name="entryNumber">The entry in the archive for which to return the file name.</param>
    /// <returns>The file name, with (relative) path</returns>
    string GetFilename(int entryNumber);

    /// <summary>
    ///     Gets the entry number for a particular file path in the archive. <c>fileName</c> is the relative path of the
    ///     file in the archive. If the file cannot be found, -1 is returned.
    /// </summary>
    /// <remarks>
    ///     The path should be relative (no leading slash), using regular slashes as path separator, and be normalized,
    ///     i.e. no "foo//bar" or "foo/../bar" path components.
    /// </remarks>
    /// <param name="fileName">The relative path for which to get the entry number.</param>
    /// <param name="caseInsensitiveMatch">If set, do a case insensitive matching and return the first file that matches.</param>
    /// <returns>The number of the entry corresponding to the given path, or -1 if the path does not exist.</returns>
    int GetEntryNumber(string fileName, bool caseInsensitiveMatch);

    /// <summary>Gets the (compressed) size of the given entry.</summary>
    /// <param name="entryNumber">The entry for which to get the compressed size.</param>
    /// <returns>The compressed size of the entry, or 0 if the entry is not a regular file.</returns>
    /// <remarks>The return value is equal to the return value of <c>GetUncompressedSize()</c> if the file is not compressed.</remarks>
    /// <seealso cref="GetUncompressedSize(int)" />
    long GetCompressedSize(int entryNumber);

    /// <summary>Gets the uncompressed size of the given entry.</summary>
    /// <param name="entryNumber">The entry for which to get the uncompressed size.</param>
    /// <returns>The uncompressed size of the entry, or 0 if the entry is not a regular file.</returns>
    /// <remarks>The return value is equal to the return value of <c>GetCompressedSize()</c> if the file is not compressed.</remarks>
    /// <seealso cref="GetCompressedSize(int)" />
    long GetUncompressedSize(int entryNumber);

    /// <summary>Gets the attributes of a file or directory.</summary>
    /// <seealso cref="Stat(int)" />
    /// <returns>Error number.</returns>
    /// <param name="entryNumber">The entry in the archive for which to retrieve the attributes.</param>
    /// <returns>File attributes, or zero if the archive does not support attributes.</returns>
    FileAttributes GetAttributes(int entryNumber);

    /// <summary>Lists all extended attributes, alternate data streams and forks of the given file.</summary>
    /// <param name="entryNumber">The entry in the archive for which to retrieve the list of attributes.</param>
    /// <returns>List of extended attributes, alternate data streams and forks.</returns>
    List<string> GetXAttrs(int entryNumber);

    /// <summary>Reads an extended attribute, alternate data stream or fork from the given file.</summary>
    /// <returns>Error number.</returns>
    /// <param name="entryNumber">The entry in the archive for which to retrieve the XAttr.</param>
    /// <param name="xattr">Extended attribute, alternate data stream or fork name.</param>
    /// <param name="buffer">Buffer where the extended attribute data will be stored.</param>
    /// <returns>Buffer with the XAttr data.</returns>
    ErrorNumber GetXattr(int entryNumber, string xattr, out byte[] buffer);

    /// <summary>Gets information about an entry in the archive.</summary>
    /// <remarks>Note that some of the data might be incomplete or not available at all, depending on the type of archive.</remarks>
    /// <seealso cref="GetAttributes(int)" />
    /// <seealso cref="GetFilename(int)" />
    /// <param name="entryNumber">The entry int he archive for which to get the information</param>
    /// <returns>The available information about the entry in the archive</returns>
    FileSystemInfo Stat(int entryNumber);

    /// <summary>
    ///     Returns the Filter for the given entry. It will return <c>null</c> if the entry in question is not a regular
    ///     file (i.e. directory, volume label, etc.)
    /// </summary>
    /// <param name="entryNumber">The entry for which the Filter should be returned.</param>
    /// <returns>The Filter for the given entry.</returns>
    IFilter GetEntry(int entryNumber);

    void GetInformation(IFilter filter, Encoding encoding, out string information);
}