From 18f762786bbec9c15caf753289cec227a635c058 Mon Sep 17 00:00:00 2001 From: Natalia Portillo Date: Sat, 7 Oct 2023 18:27:13 +0100 Subject: [PATCH] [Archive interface] Refactor methods to follow same conventions as `IReadOnlyFilesystem`. --- Interfaces/IArchive.cs | 101 +++++++++++++++++++++++------------------ 1 file changed, 58 insertions(+), 43 deletions(-) diff --git a/Interfaces/IArchive.cs b/Interfaces/IArchive.cs index 16a7e7d..469be5d 100644 --- a/Interfaces/IArchive.cs +++ b/Interfaces/IArchive.cs @@ -35,9 +35,10 @@ using System; using System.Collections.Generic; -using System.IO; using System.Text; using Aaru.CommonTypes.Enums; +using Aaru.CommonTypes.Structs; +using FileAttributes = System.IO.FileAttributes; namespace Aaru.CommonTypes.Interfaces; @@ -83,48 +84,51 @@ public interface IArchive /// Plugin author string Author { get; } - /// Identifies if the specified filter contains data recognizable by this archive instance - /// Filter that contains the archive. This allows use to handle .tar.gz and similars. - bool Identify(IFilter filter); - - /// Opens the specified stream with this archive instance - /// Filter that contains the archive. This allows use to handle .tar.gz and similars. - ErrorNumber Open(IFilter filter, Encoding encoding); - /// /// Returns true if the archive has a file/stream/buffer currently opened and no /// has been issued. /// - bool IsOpened(); - - /// Closes all opened streams. - void Close(); + /// true if the archive is opened, false otherwise. + bool Opened { get; } /// Return a bitfield indicating the features supported by this archive type. - /// The ArchiveSupportedFeature bitfield. + /// The ArchiveSupportedFeature bitfield. /// /// 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. /// - ArchiveSupportedFeature GetArchiveFeatures(); + ArchiveSupportedFeature ArchiveFeatures { get; } /// Gets the number of entries (i.e. files) that are contained in this archive. /// /// 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! /// - /// The number of files. - int GetNumberOfEntries(); + /// The number of files. + int NumberOfEntries { get; } + + /// Identifies if the specified filter contains data recognizable by this archive instance + /// Filter that contains the archive. This allows use to handle .tar.gz and similars. + bool Identify(IFilter filter); + + /// Opens the specified stream with this archive instance + /// Filter that contains the archive. This allows use to handle .tar.gz and similars. + /// The encoding codepage to use for this archive. + ErrorNumber Open(IFilter filter, Encoding encoding); + + /// Closes the archive. + void Close(); /// Gets the file name (and path) of the given entry in the archive. /// /// The path components are separated by a forward slash "/".
The path should not start with a leading /// slash (i.e. it should be relative, not absolute). /// - /// + /// /// The entry in the archive for which to return the file name. - /// The file name, with (relative) path - string GetFilename(int entryNumber); + /// The file name, with (relative) path + /// Error number. + ErrorNumber GetFilename(int entryNumber, out string fileName); /// /// Gets the entry number for a particular file path in the archive. fileName is the relative path of the @@ -136,58 +140,69 @@ public interface IArchive /// /// The relative path for which to get the entry number. /// If set, do a case insensitive matching and return the first file that matches. - /// The number of the entry corresponding to the given path, or -1 if the path does not exist. - int GetEntryNumber(string fileName, bool caseInsensitiveMatch); + /// The number of the entry corresponding to the given path, or -1 if the path does not exist. + /// Error number. + ErrorNumber GetEntryNumber(string fileName, bool caseInsensitiveMatch, out int entryNumber); /// Gets the (compressed) size of the given entry. /// The entry for which to get the compressed size. - /// The compressed size of the entry, or 0 if the entry is not a regular file. + /// The compressed size of the entry, or 0 if the entry is not a regular file. + /// Error number. /// The return value is equal to the return value of GetUncompressedSize() if the file is not compressed. - /// - long GetCompressedSize(int entryNumber); + /// + ErrorNumber GetCompressedSize(int entryNumber, out long length); /// Gets the uncompressed size of the given entry. /// The entry for which to get the uncompressed size. - /// The uncompressed size of the entry, or 0 if the entry is not a regular file. + /// The uncompressed size of the entry, or 0 if the entry is not a regular file. + /// Error number. /// The return value is equal to the return value of GetCompressedSize() if the file is not compressed. - /// - long GetUncompressedSize(int entryNumber); + /// + ErrorNumber GetUncompressedSize(int entryNumber, out long length); /// Gets the attributes of a file or directory. - /// - /// Error number. /// The entry in the archive for which to retrieve the attributes. - /// File attributes, or zero if the archive does not support attributes. - FileAttributes GetAttributes(int entryNumber); + /// File attributes, or zero if the archive does not support attributes. + /// Error number. + /// + ErrorNumber GetAttributes(int entryNumber, out FileAttributes attributes); /// Lists all extended attributes, alternate data streams and forks of the given file. /// The entry in the archive for which to retrieve the list of attributes. - /// List of extended attributes, alternate data streams and forks. - List GetXAttrs(int entryNumber); + /// List of extended attributes, alternate data streams and forks. + /// Error number. + ErrorNumber ListXAttr(int entryNumber, out List xattrs); /// Reads an extended attribute, alternate data stream or fork from the given file. - /// Error number. /// The entry in the archive for which to retrieve the XAttr. /// Extended attribute, alternate data stream or fork name. /// Buffer where the extended attribute data will be stored. - /// Buffer with the XAttr data. - ErrorNumber GetXattr(int entryNumber, string xattr, out byte[] buffer); + /// Error number. + ErrorNumber GetXattr(int entryNumber, string xattr, ref byte[] buffer); /// Gets information about an entry in the archive. /// Note that some of the data might be incomplete or not available at all, depending on the type of archive. - /// - /// /// The entry int he archive for which to get the information - /// The available information about the entry in the archive - FileSystemInfo Stat(int entryNumber); + /// The available information about the entry in the archive + /// Error number. + /// + /// + ErrorNumber Stat(int entryNumber, out FileEntryInfo stat); /// /// Returns the Filter for the given entry. It will return null if the entry in question is not a regular /// file (i.e. directory, volume label, etc.) /// /// The entry for which the Filter should be returned. - /// The Filter for the given entry. - IFilter GetEntry(int entryNumber); + /// The Filter for the given entry. + /// Error number. + ErrorNumber GetEntry(int entryNumber, out IFilter filter); + /// + /// Gets user readable information about the archive. The exact contents depend on the archive plugin implementation. + /// + /// Filter that handles the archive. + /// The encoding codepage to use with the archive. + /// Variable that holds the user readable information. void GetInformation(IFilter filter, Encoding encoding, out string information); } \ No newline at end of file