diff --git a/DiscImageChef.Devices/ChangeLog b/DiscImageChef.Devices/ChangeLog index bd4362bf2..92ed40547 100644 --- a/DiscImageChef.Devices/ChangeLog +++ b/DiscImageChef.Devices/ChangeLog @@ -1,3 +1,16 @@ +2015-10-12 Natalia Portillo + + * Enums.cs: + * Command.cs: + * Linux/Command.cs: + * Device/Commands.cs: + * Windows/Command.cs: + * Device/Variables.cs: + * Device/Destructor.cs: + * Device/Constructor.cs: + * Device/ScsiCommands.cs: + Added XML documentation. + 2015-10-12 Natalia Portillo * Enums.cs: diff --git a/DiscImageChef.Devices/Command.cs b/DiscImageChef.Devices/Command.cs index 0a03bcc7a..857c0de0a 100644 --- a/DiscImageChef.Devices/Command.cs +++ b/DiscImageChef.Devices/Command.cs @@ -44,6 +44,18 @@ namespace DiscImageChef.Devices { public static class Command { + /// + /// Sends a SCSI command + /// + /// 0 if no error occurred, otherwise, errno + /// File handle + /// SCSI CDB + /// Buffer for SCSI command response + /// Buffer with the SCSI sense + /// Timeout in seconds + /// SCSI command transfer direction + /// Time it took to execute the command in milliseconds + /// True if SCSI error returned non-OK status and contains SCSI sense public static int SendScsiCommand(object fd, byte[] cdb, ref byte[] buffer, out byte[] senseBuffer, uint timeout, Enums.ScsiDirection direction, out double duration, out bool sense) { Interop.PlatformID ptID = DetectOS.GetRealPlatformID(); @@ -51,6 +63,19 @@ namespace DiscImageChef.Devices return SendScsiCommand(ptID, (SafeFileHandle)fd, cdb, ref buffer, out senseBuffer, timeout, direction, out duration, out sense); } + /// + /// Sends a SCSI command + /// + /// 0 if no error occurred, otherwise, errno + /// Platform ID for executing the command + /// File handle + /// SCSI CDB + /// Buffer for SCSI command response + /// Buffer with the SCSI sense + /// Timeout in seconds + /// SCSI command transfer direction + /// Time it took to execute the command in milliseconds + /// True if SCSI error returned non-OK status and contains SCSI sense public static int SendScsiCommand(Interop.PlatformID ptID, object fd, byte[] cdb, ref byte[] buffer, out byte[] senseBuffer, uint timeout, Enums.ScsiDirection direction, out double duration, out bool sense) { switch (ptID) diff --git a/DiscImageChef.Devices/Device/Commands.cs b/DiscImageChef.Devices/Device/Commands.cs index f43a13a73..1a3497499 100644 --- a/DiscImageChef.Devices/Device/Commands.cs +++ b/DiscImageChef.Devices/Device/Commands.cs @@ -41,6 +41,17 @@ namespace DiscImageChef.Devices { public partial class Device { + /// + /// Sends a SCSI command to this device + /// + /// 0 if no error occurred, otherwise, errno + /// SCSI CDB + /// Buffer for SCSI command response + /// Buffer with the SCSI sense + /// Timeout in seconds + /// SCSI command transfer direction + /// Time it took to execute the command in milliseconds + /// True if SCSI error returned non-OK status and contains SCSI sense public int SendScsiCommand(byte[] cdb, ref byte[] buffer, out byte[] senseBuffer, uint timeout, Enums.ScsiDirection direction, out double duration, out bool sense) { return Command.SendScsiCommand(platformID, fd, cdb, ref buffer, out senseBuffer, timeout, direction, out duration, out sense); diff --git a/DiscImageChef.Devices/Device/Constructor.cs b/DiscImageChef.Devices/Device/Constructor.cs index d64b06d75..8f102e5ea 100644 --- a/DiscImageChef.Devices/Device/Constructor.cs +++ b/DiscImageChef.Devices/Device/Constructor.cs @@ -42,6 +42,10 @@ namespace DiscImageChef.Devices { public partial class Device { + /// + /// Opens the device for sending direct commands + /// + /// Device path public Device(string devicePath) { platformID = Interop.DetectOS.GetRealPlatformID(); diff --git a/DiscImageChef.Devices/Device/Destructor.cs b/DiscImageChef.Devices/Device/Destructor.cs index db670532b..1072196fb 100644 --- a/DiscImageChef.Devices/Device/Destructor.cs +++ b/DiscImageChef.Devices/Device/Destructor.cs @@ -42,6 +42,10 @@ namespace DiscImageChef.Devices { public partial class Device { + /// + /// Releases unmanaged resources and performs other cleanup operations before the + /// is reclaimed by garbage collection. + /// ~Device() { if (fd != null) diff --git a/DiscImageChef.Devices/Device/ScsiCommands.cs b/DiscImageChef.Devices/Device/ScsiCommands.cs index 00b9aa687..646edc67f 100644 --- a/DiscImageChef.Devices/Device/ScsiCommands.cs +++ b/DiscImageChef.Devices/Device/ScsiCommands.cs @@ -41,22 +41,50 @@ namespace DiscImageChef.Devices { public partial class Device { + /// + /// Sends the SCSI INQUIRY command to the device using default device timeout. + /// + /// true if the command failed and contains the sense buffer. + /// Buffer where the SCSI INQUIRY response will be stored + /// Sense buffer. public bool ScsiInquiry(out byte[] buffer, out byte[] senseBuffer) { return ScsiInquiry(out buffer, out senseBuffer, Timeout); } + /// + /// Sends the SCSI INQUIRY command to the device using default device timeout. + /// + /// true if the command failed and contains the sense buffer. + /// Buffer where the SCSI INQUIRY response will be stored + /// Sense buffer. + /// Duration in milliseconds it took for the device to execute the command. public bool ScsiInquiry(out byte[] buffer, out byte[] senseBuffer, out double duration) { return ScsiInquiry(out buffer, out senseBuffer, Timeout, out duration); } + /// + /// Sends the SCSI INQUIRY command to the device. + /// + /// true if the command failed and contains the sense buffer. + /// Buffer where the SCSI INQUIRY response will be stored + /// Sense buffer. + /// Timeout in seconds. public bool ScsiInquiry(out byte[] buffer, out byte[] senseBuffer, uint timeout) { double duration; return ScsiInquiry(out buffer, out senseBuffer, timeout, out duration); } + /// + /// Sends the SCSI INQUIRY command to the device. + /// + /// true if the command failed and contains the sense buffer. + /// Buffer where the SCSI INQUIRY response will be stored + /// Sense buffer. + /// Timeout in seconds. + /// Duration in milliseconds it took for the device to execute the command. public bool ScsiInquiry(out byte[] buffer, out byte[] senseBuffer, uint timeout, out double duration) { buffer = new byte[5]; @@ -80,22 +108,54 @@ namespace DiscImageChef.Devices return sense; } + /// + /// Sends the SCSI INQUIRY command to the device with an Extended Vital Product Data page using default device timeout. + /// + /// true if the command failed and contains the sense buffer. + /// Buffer where the SCSI INQUIRY response will be stored + /// Sense buffer. + /// The Extended Vital Product Data public bool ScsiInquiry(out byte[] buffer, out byte[] senseBuffer, byte page) { return ScsiInquiry(out buffer, out senseBuffer, page, Timeout); } + /// + /// Sends the SCSI INQUIRY command to the device with an Extended Vital Product Data page using default device timeout. + /// + /// true if the command failed and contains the sense buffer. + /// Buffer where the SCSI INQUIRY response will be stored + /// Sense buffer. + /// Duration in milliseconds it took for the device to execute the command. + /// The Extended Vital Product Data public bool ScsiInquiry(out byte[] buffer, out byte[] senseBuffer, byte page, out double duration) { return ScsiInquiry(out buffer, out senseBuffer, page, Timeout, out duration); } + /// + /// Sends the SCSI INQUIRY command to the device with an Extended Vital Product Data page. + /// + /// true if the command failed and contains the sense buffer. + /// Buffer where the SCSI INQUIRY response will be stored + /// Sense buffer. + /// Timeout in seconds. + /// The Extended Vital Product Data public bool ScsiInquiry(out byte[] buffer, out byte[] senseBuffer, byte page, uint timeout) { double duration; return ScsiInquiry(out buffer, out senseBuffer, page, timeout, out duration); } + /// + /// Sends the SCSI INQUIRY command to the device with an Extended Vital Product Data page. + /// + /// true if the command failed and contains the sense buffer. + /// Buffer where the SCSI INQUIRY response will be stored + /// Sense buffer. + /// Timeout in seconds. + /// Duration in milliseconds it took for the device to execute the command. + /// The Extended Vital Product Data public bool ScsiInquiry(out byte[] buffer, out byte[] senseBuffer, byte page, uint timeout, out double duration) { buffer = new byte[5]; diff --git a/DiscImageChef.Devices/Device/Variables.cs b/DiscImageChef.Devices/Device/Variables.cs index f68594596..ffa2c04de 100644 --- a/DiscImageChef.Devices/Device/Variables.cs +++ b/DiscImageChef.Devices/Device/Variables.cs @@ -45,6 +45,10 @@ namespace DiscImageChef.Devices Interop.PlatformID platformID; object fd; + /// + /// Gets the Platform ID for this device + /// + /// The Platform ID public Interop.PlatformID PlatformID { get @@ -53,6 +57,10 @@ namespace DiscImageChef.Devices } } + /// + /// Gets the file handle representing this device + /// + /// The file handle public object FileHandle { get @@ -61,6 +69,10 @@ namespace DiscImageChef.Devices } } + /// + /// Gets or sets the standard timeout for commands sent to this device + /// + /// The timeout in seconds public uint Timeout { get; diff --git a/DiscImageChef.Devices/Enums.cs b/DiscImageChef.Devices/Enums.cs index b07de94e2..e766fe150 100644 --- a/DiscImageChef.Devices/Enums.cs +++ b/DiscImageChef.Devices/Enums.cs @@ -43,6 +43,9 @@ namespace DiscImageChef.Devices public static class Enums { #region ATA Commands + /// + /// All known ATA commands + /// public enum AtaCommands : byte { #region Commands defined on Western Digital WD1000 Winchester Disk Controller @@ -657,6 +660,9 @@ namespace DiscImageChef.Devices #endregion ATA Commands #region ATA SMART SubCommands + /// + /// All known ATA SMART sub-commands + /// public enum AtaSmartSubCommands : byte { #region Commands defined on ATA-3 rev. 7b @@ -715,6 +721,9 @@ namespace DiscImageChef.Devices #endregion ATA SMART SubCommands #region ATA Device Configuration Overlay SubCommands + /// + /// All known ATA DEVICE CONFIGURATION sub-commands + /// public enum AtaDeviceConfigurationSubCommands : byte { #region Commands defined on ATA/ATAPI-6 rev. 3b @@ -739,6 +748,9 @@ namespace DiscImageChef.Devices #endregion ATA Device Configuration Overlay SubCommands #region ATA SET MAX SubCommands + /// + /// All known ATA SET MAX sub-commands + /// public enum AtaSetMaxSubCommands : byte { #region Commands defined on ATA/ATAPI-6 rev. 3b @@ -767,6 +779,9 @@ namespace DiscImageChef.Devices #endregion ATA SET MAX SubCommands #region ATA Non Volatile Cache SubCommands + /// + /// All known ATA NV CACHE sub-commands + /// public enum AtaNonVolatileCacheSubCommands : byte { #region Commands defined on ATA/ATAPI-8 rev. 3f @@ -804,6 +819,9 @@ namespace DiscImageChef.Devices #endregion ATA Non Volatile Cache SubCommands #region ATA Sanitize SubCommands + /// + /// All known ATA SANITIZE sub-commands + /// public enum AtaSanitizeSubCommands : ushort { #region Commands defined on ATA/ATAPI Command Set 2 (ACS-2) rev. 2 @@ -839,6 +857,9 @@ namespace DiscImageChef.Devices #endregion ATA Sanitize SubCommands #region ATA NCQ Queue Management SubCommands + /// + /// All known ATA NCQ QUEUE MANAGEMENT sub-commands + /// public enum AtaNCQQueueManagementSubcommands : byte { #region Commands defined on ATA/ATAPI Command Set 3 (ACS-3) rev. 5 @@ -855,7 +876,7 @@ namespace DiscImageChef.Devices #endregion ATA NCQ Queue Management SubCommands /// - /// SASI commands + /// All known SASI commands /// Commands 0x00 to 0x1F are 6-byte /// Commands 0x20 to 0x3F are 10-byte /// Commands 0x40 to 0x5F are 8-byte @@ -1199,6 +1220,9 @@ namespace DiscImageChef.Devices #endregion SASI Commands #region SCSI Commands + /// + /// All known SCSI and ATAPI commands + /// public enum ScsiCommands : byte { #region SCSI Primary Commands (SPC) @@ -2347,6 +2371,9 @@ namespace DiscImageChef.Devices } #endregion SCSI Commands + /// + /// SCSI command transfer direction + /// public enum ScsiDirection { /// diff --git a/DiscImageChef.Devices/Linux/Command.cs b/DiscImageChef.Devices/Linux/Command.cs index 728b728d1..161de8e72 100644 --- a/DiscImageChef.Devices/Linux/Command.cs +++ b/DiscImageChef.Devices/Linux/Command.cs @@ -44,6 +44,18 @@ namespace DiscImageChef.Devices.Linux { static class Command { + /// + /// Sends a SCSI command + /// + /// 0 if no error occurred, otherwise, errno + /// File handle + /// SCSI CDB + /// Buffer for SCSI command response + /// Buffer with the SCSI sense + /// Timeout in seconds + /// SCSI command transfer direction + /// Time it took to execute the command in milliseconds + /// True if SCSI error returned non-OK status and contains SCSI sense internal static int SendScsiCommand(int fd, byte[] cdb, ref byte[] buffer, out byte[] senseBuffer, uint timeout, ScsiIoctlDirection direction, out double duration, out bool sense) { senseBuffer = null; diff --git a/DiscImageChef.Devices/Windows/Command.cs b/DiscImageChef.Devices/Windows/Command.cs index 7afc61010..804a20c7f 100644 --- a/DiscImageChef.Devices/Windows/Command.cs +++ b/DiscImageChef.Devices/Windows/Command.cs @@ -45,6 +45,18 @@ namespace DiscImageChef.Devices.Windows { static class Command { + /// + /// Sends a SCSI command + /// + /// 0 if no error occurred, otherwise, errno + /// File handle + /// SCSI CDB + /// Buffer for SCSI command response + /// Buffer with the SCSI sense + /// Timeout in seconds + /// SCSI command transfer direction + /// Time it took to execute the command in milliseconds + /// True if SCSI error returned non-OK status and contains SCSI sense internal static int SendScsiCommand(SafeFileHandle fd, byte[] cdb, ref byte[] buffer, out byte[] senseBuffer, uint timeout, ScsiIoctlDirection direction, out double duration, out bool sense) { senseBuffer = null;