diff --git a/Aaru.CommonTypes.csproj b/Aaru.CommonTypes.csproj index 46c6893..210ce9e 100644 --- a/Aaru.CommonTypes.csproj +++ b/Aaru.CommonTypes.csproj @@ -76,6 +76,9 @@ + + + diff --git a/Interfaces/IBaseImage.cs b/Interfaces/IBaseImage.cs new file mode 100644 index 0000000..c01aca0 --- /dev/null +++ b/Interfaces/IBaseImage.cs @@ -0,0 +1,75 @@ +// /*************************************************************************** +// Aaru Data Preservation Suite +// ---------------------------------------------------------------------------- +// +// Filename : IBaseImage.cs +// Author(s) : Natalia Portillo +// +// Component : Disc image plugins. +// +// --[ Description ] ---------------------------------------------------------- +// +// Defines the interface to be implemented by image plugins. +// +// --[ License ] -------------------------------------------------------------- +// +// Permission is hereby granted, free of charge, to any person obtaining a +// copy of this software and associated documentation files (the +// "Software"), to deal in the Software without restriction, including +// without limitation the rights to use, copy, modify, merge, publish, +// distribute, sublicense, and/or sell copies of the Software, and to +// permit persons to whom the Software is furnished to do so, subject to +// the following conditions: +// +// The above copyright notice and this permission notice shall be included +// in all copies or substantial portions of the Software. +// +// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS +// OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +// MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +// IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +// CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, +// TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE +// SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. +// +// ---------------------------------------------------------------------------- +// Copyright © 2011-2021 Natalia Portillo +// ****************************************************************************/ + +using System; +using System.Collections.Generic; +using Aaru.CommonTypes.Enums; +using Aaru.CommonTypes.Structs; +using Schemas; + +namespace Aaru.CommonTypes.Interfaces; + +/// Base interface for all images +public interface IBaseImage +{ + /// Plugin author + string Author { get; } + /// Gets the CICM XML metadata for the image + CICMMetadataType CicmMetadata { get; } + /// List of dump hardware used to create the image from real media + List DumpHardware { get; } + /// Gets the image format. + /// The image format. + string Format { get; } + /// Plugin UUID. + Guid Id { get; } + /// Image information + ImageInfo Info { get; } + /// Plugin name. + string Name { get; } + + /// Identifies the image. + /// true, if image was identified, false otherwise. + /// Image filter. + bool Identify(IFilter imageFilter); + + /// Opens the image. + /// true, if image was opened, false otherwise. + /// Image filter. + ErrorNumber Open(IFilter imageFilter); +} \ No newline at end of file diff --git a/Interfaces/IBaseWritableImage.cs b/Interfaces/IBaseWritableImage.cs new file mode 100644 index 0000000..eb6c1af --- /dev/null +++ b/Interfaces/IBaseWritableImage.cs @@ -0,0 +1,91 @@ +// /*************************************************************************** +// Aaru Data Preservation Suite +// ---------------------------------------------------------------------------- +// +// Filename : IBaseWritableImage.cs +// Author(s) : Natalia Portillo +// +// Component : Disc image plugins. +// +// --[ Description ] ---------------------------------------------------------- +// +// Defines the base interface to be implemented by writable image plugins. +// +// --[ License ] -------------------------------------------------------------- +// +// Permission is hereby granted, free of charge, to any person obtaining a +// copy of this software and associated documentation files (the +// "Software"), to deal in the Software without restriction, including +// without limitation the rights to use, copy, modify, merge, publish, +// distribute, sublicense, and/or sell copies of the Software, and to +// permit persons to whom the Software is furnished to do so, subject to +// the following conditions: +// +// The above copyright notice and this permission notice shall be included +// in all copies or substantial portions of the Software. +// +// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS +// OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +// MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +// IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +// CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, +// TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE +// SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. +// +// ---------------------------------------------------------------------------- +// Copyright © 2011-2021 Natalia Portillo +// ****************************************************************************/ + +using System; +using System.Collections.Generic; +using Aaru.CommonTypes.Enums; +using Aaru.CommonTypes.Structs; +using Schemas; + +namespace Aaru.CommonTypes.Interfaces; + +/// Base interface for all writable images +public interface IBaseWritableImage : IBaseImage +{ + /// Contains a description of the last error + string ErrorMessage { get; } + /// If set to true means the image is opened for writing + bool IsWriting { get; } + /// Gets a list of known extensions for format auto-choosing + IEnumerable KnownExtensions { get; } + /// Gets a list of that are supported by the media image format + IEnumerable SupportedMediaTags { get; } + /// Gets a list of that are supported by the media image format + IEnumerable SupportedMediaTypes { get; } + /// Retrieves a list of options supported by the filesystem, with name, type and description + IEnumerable<(string name, Type type, string description, object @default)> SupportedOptions { get; } + /// Gets a list of that are supported by the media image format + IEnumerable SupportedSectorTags { get; } + + /// + /// Creates a new image in the specified path, for the specified , with the specified + /// options to hold a media with the specified number of sectors + /// + /// Path to the new image, with extension + /// that will be written in the image + /// Options to be used when creating new image + /// How many sectors the media has. + /// + /// true if operating completed successfully, false otherwise + bool Create(string path, MediaType mediaType, Dictionary options, ulong sectors, uint sectorSize); + + /// Closes the image and flushes all data to disk + /// Error number + bool Close(); + + /// Sets the CICM XML metadata for the image + bool SetCicmMetadata(CICMMetadataType metadata); + + /// Sets the list of dump hardware used to create the image from real media + bool SetDumpHardware(List dumpHardware); + + /// Sets image metadata + /// containing image metadata + /// true if operating completed successfully, false otherwise + bool SetMetadata(ImageInfo metadata); +} \ No newline at end of file diff --git a/Interfaces/IByteAddressableImage.cs b/Interfaces/IByteAddressableImage.cs new file mode 100644 index 0000000..52c42b5 --- /dev/null +++ b/Interfaces/IByteAddressableImage.cs @@ -0,0 +1,143 @@ +// /*************************************************************************** +// Aaru Data Preservation Suite +// ---------------------------------------------------------------------------- +// +// Filename : IByteAddressableImage.cs +// Author(s) : Natalia Portillo +// +// Component : Disc image plugins. +// +// --[ Description ] ---------------------------------------------------------- +// +// Defines the interface to be implemented by byte-addressable image plugins. +// +// --[ License ] -------------------------------------------------------------- +// +// Permission is hereby granted, free of charge, to any person obtaining a +// copy of this software and associated documentation files (the +// "Software"), to deal in the Software without restriction, including +// without limitation the rights to use, copy, modify, merge, publish, +// distribute, sublicense, and/or sell copies of the Software, and to +// permit persons to whom the Software is furnished to do so, subject to +// the following conditions: +// +// The above copyright notice and this permission notice shall be included +// in all copies or substantial portions of the Software. +// +// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS +// OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +// MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +// IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +// CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, +// TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE +// SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. +// +// ---------------------------------------------------------------------------- +// Copyright © 2011-2021 Natalia Portillo +// ****************************************************************************/ + +using System.Collections.Generic; +using Aaru.CommonTypes.Enums; + +namespace Aaru.CommonTypes.Interfaces; + +/// Interface defining linear media (chips, game carts, etc) images +public interface IByteAddressableImage : IBaseImage +{ + /// Gets or sets the current position + long Position { get; set; } + + /// Creates a linear media image + /// Path where to create the media image + /// Media type + /// Image options + /// Maximum size in bytes + /// Error number + ErrorNumber Create(string path, MediaType mediaType, Dictionary options, long maximumSize); + + /// Gets the media image header (really needed?) + /// Header, interchange format still undecided + /// Error message + ErrorNumber GetHeader(out byte[] header); + + /// Gets the linear memory mappings, e.g. interleaving, starting address, etc. + /// Format still not decided + /// Error number + ErrorNumber GetMappings(out object mappings); + + /// Reads a byte from the image + /// The byte read + /// Set to true to advance position, false otherwise. + /// Error number + ErrorNumber ReadByte(out byte b, bool advance = true); + + /// Reads a byte from the image at the specified position + /// Position + /// The byte read + /// Set to true to advance position, false otherwise. + /// Error number + ErrorNumber ReadByteAt(long position, out byte b, bool advance = true); + + /// Reads several bytes from the image + /// Buffer to store the data in + /// Offset in buffer where to place the byte in + /// How many bytes to read from image + /// How many bytes were read + /// Set to true to advance position, false otherwise. + /// Error number + ErrorNumber ReadBytes(byte[] buffer, int offset, int bytesToRead, out int bytesRead, bool advance = true); + + /// Reads several bytes from the image at the specified position + /// Position + /// Buffer to store the data in + /// Offset in buffer where to place the byte in + /// How many bytes to read from image + /// How many bytes were read + /// Set to true to advance position, false otherwise. + /// Error number + ErrorNumber ReadBytesAt(long position, byte[] buffer, int offset, int bytesToRead, out int bytesRead, + bool advance = true); + + /// Sets the media image header (really needed?) + /// Header, interchange format still undecided + /// Error message + ErrorNumber SetHeader(byte[] header); + + /// Sets the linear memory mappings, e.g. interleaving, starting address, etc. + /// Format still not decided + /// Error number + ErrorNumber SetMappings(object mappings); + + /// Writes a byte to the image + /// The byte to be written + /// Set to true to advance position, false otherwise. + /// Error number + ErrorNumber WriteByte(byte b, bool advance = true); + + /// Writes a byte to the image at the specified position + /// Position + /// The byte read + /// Set to true to advance position, false otherwise. + /// Error number + ErrorNumber WriteByteAt(long position, byte b, bool advance = true); + + /// Writes several bytes to the image + /// Buffer to store the data in + /// Offset in buffer where the bytes start in + /// How many bytes to write to image + /// How many bytes were written + /// Set to true to advance position, false otherwise. + /// Error number + ErrorNumber WriteBytes(byte[] buffer, int offset, int bytesToWrite, out int bytesWritten, bool advance = true); + + /// Writes several bytes to the image at the specified position + /// Position + /// Buffer to store the data in + /// Offset in buffer where the bytes start in + /// How many bytes to write to image + /// How many bytes were written + /// Set to true to advance position, false otherwise. + /// Error number + ErrorNumber WriteBytesAt(long position, byte[] buffer, int offset, int bytesToWrite, out int bytesWritten, + bool advance = true); +} \ No newline at end of file diff --git a/Interfaces/IMediaImage.cs b/Interfaces/IMediaImage.cs index e18f95f..7649b65 100644 --- a/Interfaces/IMediaImage.cs +++ b/Interfaces/IMediaImage.cs @@ -37,88 +37,57 @@ // Copyright © 2011-2021 Natalia Portillo // ****************************************************************************/ -using System; -using System.Collections.Generic; using Aaru.CommonTypes.Enums; -using Aaru.CommonTypes.Structs; -using Schemas; -namespace Aaru.CommonTypes.Interfaces +namespace Aaru.CommonTypes.Interfaces; + +/// Abstract class to implement disk image reading plugins. +public interface IMediaImage : IBaseImage { - /// Abstract class to implement disk image reading plugins. - public interface IMediaImage - { - /// Image information - ImageInfo Info { get; } - /// Plugin name. - string Name { get; } - /// Plugin UUID. - Guid Id { get; } - /// Plugin author - string Author { get; } - /// Gets the image format. - /// The image format. - string Format { get; } - /// List of dump hardware used to create the image from real media - List DumpHardware { get; } - /// Gets the CICM XML metadata for the image - CICMMetadataType CicmMetadata { get; } + /// Reads a disk tag. + /// + /// Tag type to read. + /// Disk tag + ErrorNumber ReadMediaTag(MediaTagType tag, out byte[] buffer); - /// Identifies the image. - /// true, if image was identified, false otherwise. - /// Image filter. - bool Identify(IFilter imageFilter); + /// Reads a sector's user data. + /// The sector's user data. + /// Sector address (LBA). + /// + ErrorNumber ReadSector(ulong sectorAddress, out byte[] buffer); - /// Opens the image. - /// true, if image was opened, false otherwise. - /// Image filter. - ErrorNumber Open(IFilter imageFilter); + /// Reads a complete sector (user data + all tags). + /// The complete sector. Format depends on disk type. + /// Sector address (LBA). + /// + ErrorNumber ReadSectorLong(ulong sectorAddress, out byte[] buffer); - /// Reads a disk tag. - /// - /// Tag type to read. - /// Disk tag - ErrorNumber ReadMediaTag(MediaTagType tag, out byte[] buffer); + /// Reads user data from several sectors. + /// The sectors user data. + /// Starting sector address (LBA). + /// How many sectors to read. + /// + ErrorNumber ReadSectors(ulong sectorAddress, uint length, out byte[] buffer); - /// Reads a sector's user data. - /// The sector's user data. - /// Sector address (LBA). - /// - ErrorNumber ReadSector(ulong sectorAddress, out byte[] buffer); + /// Reads several complete sector (user data + all tags). + /// The complete sectors. Format depends on disk type. + /// Starting sector address (LBA). + /// How many sectors to read. + /// + ErrorNumber ReadSectorsLong(ulong sectorAddress, uint length, out byte[] buffer); - /// Reads a sector's tag. - /// The sector's tag. - /// Sector address (LBA). - /// Tag type. - /// - ErrorNumber ReadSectorTag(ulong sectorAddress, SectorTagType tag, out byte[] buffer); + /// Reads tag from several sectors. + /// The sectors tag. + /// Starting sector address (LBA). + /// How many sectors to read. + /// Tag type. + /// + ErrorNumber ReadSectorsTag(ulong sectorAddress, uint length, SectorTagType tag, out byte[] buffer); - /// Reads user data from several sectors. - /// The sectors user data. - /// Starting sector address (LBA). - /// How many sectors to read. - /// - ErrorNumber ReadSectors(ulong sectorAddress, uint length, out byte[] buffer); - - /// Reads tag from several sectors. - /// The sectors tag. - /// Starting sector address (LBA). - /// How many sectors to read. - /// Tag type. - /// - ErrorNumber ReadSectorsTag(ulong sectorAddress, uint length, SectorTagType tag, out byte[] buffer); - - /// Reads a complete sector (user data + all tags). - /// The complete sector. Format depends on disk type. - /// Sector address (LBA). - /// - ErrorNumber ReadSectorLong(ulong sectorAddress, out byte[] buffer); - - /// Reads several complete sector (user data + all tags). - /// The complete sectors. Format depends on disk type. - /// Starting sector address (LBA). - /// How many sectors to read. - /// - ErrorNumber ReadSectorsLong(ulong sectorAddress, uint length, out byte[] buffer); - } + /// Reads a sector's tag. + /// The sector's tag. + /// Sector address (LBA). + /// Tag type. + /// + ErrorNumber ReadSectorTag(ulong sectorAddress, SectorTagType tag, out byte[] buffer); } \ No newline at end of file diff --git a/Interfaces/IWritableImage.cs b/Interfaces/IWritableImage.cs index f4be123..8c22294 100644 --- a/Interfaces/IWritableImage.cs +++ b/Interfaces/IWritableImage.cs @@ -9,7 +9,7 @@ // // --[ Description ] ---------------------------------------------------------- // -// Defines the interface to be implemented by writable image plugins. +// Defines the interface to be implemented by writable block addressable image plugins. // // --[ License ] -------------------------------------------------------------- // @@ -36,119 +36,69 @@ // Copyright © 2011-2021 Natalia Portillo // ****************************************************************************/ -using System; -using System.Collections.Generic; using Aaru.CommonTypes.Enums; -using Aaru.CommonTypes.Structs; -using Schemas; -namespace Aaru.CommonTypes.Interfaces +namespace Aaru.CommonTypes.Interfaces; + +/// +/// Abstract class to implement disk image writing plugins. TODO: This interface is subject to change until +/// notice. +/// +public interface IWritableImage : IMediaImage, IBaseWritableImage { - /// - /// - /// Abstract class to implement disk image writing plugins. TODO: This interface is subject to change until - /// notice. - /// - public interface IWritableImage : IMediaImage - { - /// Gets a list of that are supported by the media image format - IEnumerable SupportedMediaTags { get; } - /// Gets a list of that are supported by the media image format - IEnumerable SupportedSectorTags { get; } - /// Gets a list of that are supported by the media image format - IEnumerable SupportedMediaTypes { get; } - /// Retrieves a list of options supported by the filesystem, with name, type and description - IEnumerable<(string name, Type type, string description, object @default)> SupportedOptions { get; } - /// Gets a list of known extensions for format auto-choosing - IEnumerable KnownExtensions { get; } + /// Sets media geometry + /// Cylinders + /// Heads + /// Sectors per track + /// true if operating completed successfully, false otherwise + bool SetGeometry(uint cylinders, uint heads, uint sectorsPerTrack); - /// If set to true means the image is opened for writing - bool IsWriting { get; } - /// Contains a description of the last error - string ErrorMessage { get; } + /// Writes a media tag to the image + /// Media tag + /// + /// + /// + /// true if operating completed successfully, false otherwise + bool WriteMediaTag(byte[] data, MediaTagType tag); - /// - /// Creates a new image in the specified path, for the specified , with the specified - /// options to hold a media with the specified number of sectors - /// - /// Path to the new image, with extension - /// that will be written in the image - /// Options to be used when creating new image - /// How many sectors the media has. - /// - /// true if operating completed successfully, false otherwise - bool Create(string path, MediaType mediaType, Dictionary options, ulong sectors, - uint sectorSize); + /// Writes a sector to the image + /// Sector data + /// Sector address + /// true if operating completed successfully, false otherwise + bool WriteSector(byte[] data, ulong sectorAddress); - /// Writes a media tag to the image - /// Media tag - /// - /// - /// - /// true if operating completed successfully, false otherwise - bool WriteMediaTag(byte[] data, MediaTagType tag); + /// Writes a sector to the image with main channel tags attached + /// Sector data with its main channel tags attached + /// Sector address + /// true if operating completed successfully, false otherwise + bool WriteSectorLong(byte[] data, ulong sectorAddress); - /// Writes a sector to the image - /// Sector data - /// Sector address - /// true if operating completed successfully, false otherwise - bool WriteSector(byte[] data, ulong sectorAddress); + /// Writes several sectors to the image + /// Sectors data + /// Sector starting address + /// How many sectors to write + /// true if operating completed successfully, false otherwise + bool WriteSectors(byte[] data, ulong sectorAddress, uint length); - /// Writes several sectors to the image - /// Sectors data - /// Sector starting address - /// How many sectors to write - /// true if operating completed successfully, false otherwise - bool WriteSectors(byte[] data, ulong sectorAddress, uint length); + /// Writes several sectors to the image + /// Sector data with their main channel tags attached + /// Sector starting address + /// How many sectors to write + /// true if operating completed successfully, false otherwise + bool WriteSectorsLong(byte[] data, ulong sectorAddress, uint length); - /// Writes a sector to the image with main channel tags attached - /// Sector data with its main channel tags attached - /// Sector address - /// true if operating completed successfully, false otherwise - bool WriteSectorLong(byte[] data, ulong sectorAddress); + /// Writes parallel or subchannel sector tag for several sector + /// Tag data to write + /// Starting sector address + /// How many sectors to write + /// Tag type + /// true if operating completed successfully, false otherwise + bool WriteSectorsTag(byte[] data, ulong sectorAddress, uint length, SectorTagType tag); - /// Writes several sectors to the image - /// Sector data with their main channel tags attached - /// Sector starting address - /// How many sectors to write - /// true if operating completed successfully, false otherwise - bool WriteSectorsLong(byte[] data, ulong sectorAddress, uint length); - - /// Closes and flushes to disk the image - /// true if operating completed successfully, false otherwise - bool Close(); - - /// Sets image metadata - /// containing image metadata - /// true if operating completed successfully, false otherwise - bool SetMetadata(ImageInfo metadata); - - /// Sets media geometry - /// Cylinders - /// Heads - /// Sectors per track - /// true if operating completed successfully, false otherwise - bool SetGeometry(uint cylinders, uint heads, uint sectorsPerTrack); - - /// Writes parallel or subchannel sector tag for one sector - /// Tag data to write - /// Sector address - /// Tag type - /// true if operating completed successfully, false otherwise - bool WriteSectorTag(byte[] data, ulong sectorAddress, SectorTagType tag); - - /// Writes parallel or subchannel sector tag for several sector - /// Tag data to write - /// Starting sector address - /// How many sectors to write - /// Tag type - /// true if operating completed successfully, false otherwise - bool WriteSectorsTag(byte[] data, ulong sectorAddress, uint length, SectorTagType tag); - - /// Sets the list of dump hardware used to create the image from real media - bool SetDumpHardware(List dumpHardware); - - /// Sets the CICM XML metadata for the image - bool SetCicmMetadata(CICMMetadataType metadata); - } + /// Writes parallel or subchannel sector tag for one sector + /// Tag data to write + /// Sector address + /// Tag type + /// true if operating completed successfully, false otherwise + bool WriteSectorTag(byte[] data, ulong sectorAddress, SectorTagType tag); } \ No newline at end of file