diff --git a/docs/CodeDoc/Atc.Network/Atc.Network.Helpers.md b/docs/CodeDoc/Atc.Network/Atc.Network.Helpers.md index 2dd8d48..9d95fcb 100644 --- a/docs/CodeDoc/Atc.Network/Atc.Network.Helpers.md +++ b/docs/CodeDoc/Atc.Network/Atc.Network.Helpers.md @@ -8,6 +8,7 @@
## ArpHelper +Provides utilities for fetching and parsing ARP (Address Resolution Protocol) table results. >```csharp >public static class ArpHelper @@ -19,10 +20,16 @@ >```csharp >ArpEntity[] GetArpResult() >``` +>Summary: Retrieves the ARP table results, caching them for 90 seconds to limit frequent lookups. +> +>Returns: An array of `Atc.Network.Models.ArpEntity` representing the current ARP table entries. Returns an empty array if no connection is available or if the ARP lookup fails. +> +>Remarks: This method first checks if the results are cached and valid (less than 90 seconds old). If valid, cached results are returned. Otherwise, it performs a new ARP lookup using the system's 'arp' command. The results are parsed, cached, and then returned. If there's no network connection, an empty array is returned.
## DnsLookupHelper +Provides utilities for performing DNS lookups. >```csharp >public static class DnsLookupHelper @@ -34,10 +41,20 @@ >```csharp >Task GetHostname(IPAddress ipAddress, CancellationToken cancellationToken) >``` +>Summary: Resolves the hostname for a given IP address asynchronously. +> +>Parameters:
+>     `ipAddress`  -  The IP address to resolve the hostname for.
+>     `cancellationToken`  -  A token to monitor for cancellation requests.
+> +>Returns: The hostname associated with the specified IP address or null if the lookup fails or the address is a private IP address for which the local hostname cannot be resolved. +> +>Remarks: This method uses a SemaphoreSlim to ensure thread-safe access to the hostname and hostAddresses static fields. It first checks if the IP address is a private address. If so, and if the hostname and hostAddresses have not been previously set, it attempts to set them by resolving the local machine's hostname and IP addresses. For public IP addresses, it performs a DNS lookup to resolve the hostname. This method suppresses all exceptions, returning null in case of any errors or if the operation is canceled.
## IPv4AddressHelper +Provides utilities for validating and working with IPv4 addresses. >```csharp >public static class IPv4AddressHelper @@ -49,26 +66,100 @@ >```csharp >IReadOnlyCollection GetAddressesInRange(IPAddress startIpAddress, IPAddress endIpAddress) >``` +>Summary: Generates a collection of IPv4 addresses within a specified range. +> +>Parameters:
+>     `startIpAddress`  -  The starting IP address of the range.
+>     `endIpAddress`  -  The ending IP address of the range.
+> +>Returns: A read-only collection of IP addresses within the specified range. #### GetAddressesInRange >```csharp >IReadOnlyCollection GetAddressesInRange(IPAddress ipAddress, int cidrLength) >``` +>Summary: Generates a collection of IPv4 addresses within a specified range. +> +>Parameters:
+>     `startIpAddress`  -  The starting IP address of the range.
+>     `endIpAddress`  -  The ending IP address of the range.
+> +>Returns: A read-only collection of IP addresses within the specified range. #### GetFirstAndLastAddressInRange >```csharp >ValueTuple GetFirstAndLastAddressInRange(IPAddress ipAddress, int cidrLength) >``` +>Summary: Calculates the first and last IP addresses in a subnet given an IP address and CIDR length. +> +>Parameters:
+>     `ipAddress`  -  The IP address within the subnet.
+>     `cidrLength`  -  The CIDR notation length of the subnet mask.
+> +>Returns: A tuple containing the first and last IP addresses in the subnet range. #### GetLocalAddress >```csharp >IPAddress GetLocalAddress() >``` +>Summary: Retrieves the local machine's IPv4 address. +> +>Returns: The local IPv4 address, or null if not found. #### IsValid >```csharp >bool IsValid(string ipAddress) >``` +>Summary: Validates if a string is a valid IPv4 address. +> +>Parameters:
+>     `ipAddress`  -  The IP address in string format to validate.
+> +>Returns: True if the IP address is valid; otherwise, false. +> +>Remarks: This method checks if the string can be parsed into an IPAddress object and belongs to the IPv4 address family. It also ensures that the IP address string has exactly four octets. #### ValidateAddresses >```csharp >ValueTuple ValidateAddresses(IPAddress startIpAddress, IPAddress endIpAddress) >``` +>Summary: Validates that two IP addresses are valid IPv4 addresses and that the start IP is less than or equal to the end IP. +> +>Parameters:
+>     `startIpAddress`  -  The starting IP address of the range.
+>     `endIpAddress`  -  The ending IP address of the range.
+> +>Returns: A tuple containing a boolean indicating if the addresses are valid and an error message if they are not. + +
+ +## InternetWorldTimeHelper +Provides utilities for fetching the current time from the WorldTimeAPI. + +>```csharp +>public static class InternetWorldTimeHelper +>``` + +### Static Methods + +#### GetTimeForEuropeBerlin +>```csharp +>Task GetTimeForEuropeBerlin(CancellationToken cancellationToken) +>``` +>Summary: Retrieves the current time for the Europe/Berlin timezone. +> +>Parameters:
+>     `cancellationToken`  -  A token to monitor for cancellation requests.
+> +>Returns: A `System.DateTime` representing the current time in Europe/Berlin timezone, or null if the operation fails or is canceled. +#### GetTimeForWorldTimezone +>```csharp +>Task GetTimeForWorldTimezone(string worldTimezone, CancellationToken cancellationToken) +>``` +>Summary: Retrieves the current time for a specified WorldTimeAPI timezone. +> +>Parameters:
+>     `worldTimezone`  -  The timezone string as defined by WorldTimeAPI.
+>     `cancellationToken`  -  A token to monitor for cancellation requests.
+> +>Returns: A `System.DateTime` representing the current time in the specified timezone, or null if the operation fails or is canceled. +> +>Remarks: This method ensures thread safety by using a SemaphoreSlim to limit concurrent access. It checks for network connectivity before making the HTTP request. If the network is unavailable or the request fails, the method returns null.
@@ -88,6 +179,7 @@
## OpcUaAddressHelper +Provides utilities for validating OPC UA (Open Platform Communications Unified Architecture) addresses. >```csharp >public static class OpcUaAddressHelper @@ -99,14 +191,33 @@ >```csharp >bool IsValid(string url, bool restrictToIp4Address = False) >``` +>Summary: Validates the format of a given OPC UA address specified as a URL string. +> +>Parameters:
+>     `url`  -  The OPC UA address to validate.
+>     `restrictToIp4Address`  -  Indicates whether to restrict validation to IPv4 addresses only.
+> +>Returns: True if the address is a valid OPC UA address; otherwise, false. +> +>Remarks: This method checks if the URL is an absolute URI with the scheme "opc.tcp". If `restrictToIp4Address` is true, it further validates that the host part of the URI is a valid IPv4 address. #### IsValid >```csharp >bool IsValid(Uri uri, bool restrictToIp4Address = False) >``` +>Summary: Validates the format of a given OPC UA address specified as a URL string. +> +>Parameters:
+>     `url`  -  The OPC UA address to validate.
+>     `restrictToIp4Address`  -  Indicates whether to restrict validation to IPv4 addresses only.
+> +>Returns: True if the address is a valid OPC UA address; otherwise, false. +> +>Remarks: This method checks if the URL is an absolute URI with the scheme "opc.tcp". If `restrictToIp4Address` is true, it further validates that the host part of the URI is a valid IPv4 address.
## PingHelper +Provides utilities for performing ping operations to assess network connectivity and response time. >```csharp >public static class PingHelper @@ -118,14 +229,33 @@ >```csharp >Task GetStatus(IPAddress ipAddress, TimeSpan timeout) >``` +>Summary: Initiates a ping request to a specified IP address with a timeout. +> +>Parameters:
+>     `ipAddress`  -  The IP address to ping.
+>     `timeout`  -  The maximum amount of time to wait for a ping response.
+> +>Returns: A task that represents the asynchronous operation, resulting in a `Atc.Network.Models.PingStatusResult`. +> +>Remarks: This overload accepts a `System.TimeSpan` for the timeout and converts it to milliseconds before calling the main asynchronous ping method. #### GetStatus >```csharp >Task GetStatus(IPAddress ipAddress, int timeoutInMs = 1000) >``` +>Summary: Initiates a ping request to a specified IP address with a timeout. +> +>Parameters:
+>     `ipAddress`  -  The IP address to ping.
+>     `timeout`  -  The maximum amount of time to wait for a ping response.
+> +>Returns: A task that represents the asynchronous operation, resulting in a `Atc.Network.Models.PingStatusResult`. +> +>Remarks: This overload accepts a `System.TimeSpan` for the timeout and converts it to milliseconds before calling the main asynchronous ping method.
## TerminationHelper +Provides utilities for appending termination sequences to data arrays. >```csharp >public static class TerminationHelper @@ -137,10 +267,18 @@ >```csharp >void AppendTerminationBytesIfNeeded(ref byte data, TerminationType terminationType) >``` +>Summary: Appends termination bytes to a data array if the specified termination type is not already present at the end of the array. +> +>Parameters:
+>     `data`  -  The data array to append the termination bytes to, if necessary.
+>     `terminationType`  -  The type of termination sequence to append.
+> +>Remarks: This method first checks if the termination type is None, in which case it does nothing. If the termination type is specified, it converts the termination type to its byte array representation and checks if the data array already ends with this sequence. If not, it appends the termination bytes to the end of the data array.
## TerminationTypeHelper +Provides utilities for handling different types of message termination characters and sequences. >```csharp >public static class TerminationTypeHelper @@ -170,12 +308,31 @@ >```csharp >byte[] ConvertToBytes(TerminationType terminationType) >``` +>Summary: Converts a termination type to its byte array representation. +> +>Parameters:
+>     `terminationType`  -  The termination type to convert.
+> +>Returns: A byte array representation of the specified termination type. #### ConvertToString >```csharp >string ConvertToString(TerminationType terminationType) >``` +>Summary: Converts a termination type to its string representation. +> +>Parameters:
+>     `terminationType`  -  The termination type to convert.
+> +>Returns: A string representation of the specified termination type. #### HasTerminationType >```csharp >bool HasTerminationType(TerminationType terminationType, byte[] data) >``` +>Summary: Checks if the specified data contains the termination sequence for the given termination type. +> +>Parameters:
+>     `terminationType`  -  The termination type to check for.
+>     `data`  -  The data to search within.
+> +>Returns: True if the data contains the termination sequence; otherwise, false.
Generated by MarkdownCodeDoc version 1.2
diff --git a/docs/CodeDoc/Atc.Network/Atc.Network.Internet.md b/docs/CodeDoc/Atc.Network/Atc.Network.Internet.md index faa90af..54366ed 100644 --- a/docs/CodeDoc/Atc.Network/Atc.Network.Internet.md +++ b/docs/CodeDoc/Atc.Network/Atc.Network.Internet.md @@ -8,6 +8,7 @@
## IIPPortScan +Defines a contract for scanning IP ports to check for connectivity using TCP, HTTP, and HTTPS. >```csharp >public interface IIPPortScan @@ -19,30 +20,68 @@ >```csharp >Task CanConnectWithHttp(int portNumber = 80, CancellationToken cancellationToken = null) >``` +>Summary: Checks if an HTTP connection can be established on the specified port. +> +>Parameters:
+>     `portNumber`  -  The port number to check, defaulting to 80.
+>     `cancellationToken`  -  A token to cancel the operation.
+> +>Returns: A task that represents the asynchronous operation, resulting in true if the connection was successful; otherwise, false. #### CanConnectWithHttpOrHttps >```csharp >Task CanConnectWithHttpOrHttps(int portNumber = 80, bool useHttps = False, CancellationToken cancellationToken = null) >``` +>Summary: Checks if a connection using either HTTP or HTTPS can be established on the specified port. +> +>Parameters:
+>     `portNumber`  -  The port number to check, defaulting to 80.
+>     `useHttps`  -  Indicates whether to use HTTPS (true) or HTTP (false).
+>     `cancellationToken`  -  A token to cancel the operation.
+> +>Returns: A task that represents the asynchronous operation, resulting in true if the connection was successful; otherwise, false. #### CanConnectWithHttps >```csharp >Task CanConnectWithHttps(int portNumber = 443, CancellationToken cancellationToken = null) >``` +>Summary: Checks if an HTTPS connection can be established on the specified port. +> +>Parameters:
+>     `portNumber`  -  The port number to check, defaulting to 443.
+>     `cancellationToken`  -  A token to cancel the operation.
+> +>Returns: A task that represents the asynchronous operation, resulting in true if the connection was successful; otherwise, false. #### CanConnectWithTcp >```csharp >Task CanConnectWithTcp(int portNumber, CancellationToken cancellationToken = null) >``` +>Summary: Checks if a TCP connection can be established on the specified port. +> +>Parameters:
+>     `portNumber`  -  The port number to check.
+>     `cancellationToken`  -  A token to cancel the operation.
+> +>Returns: A task that represents the asynchronous operation, resulting in true if the connection was successful; otherwise, false. #### SetIPAddress >```csharp >void SetIPAddress(IPAddress value) >``` +>Summary: Sets the IP address to be used for scanning operations. +> +>Parameters:
+>     `value`  -  The IP address to scan.
#### SetTimeout >```csharp >void SetTimeout(TimeSpan value) >``` +>Summary: Sets the timeout period for connection attempts. +> +>Parameters:
+>     `value`  -  The maximum amount of time to wait for a connection attempt before timing out.

## IIPScanner +Defines a contract for scanning IP addresses or ranges to assess network accessibility and gather information like open ports, hostnames, and more. >```csharp >public interface IIPScanner @@ -54,33 +93,59 @@ >```csharp >Configuration >``` +>Summary: Gets or sets the configuration settings for the IP scanner. ### Events #### ProgressReporting >```csharp >ProgressReporting >``` +>Summary: Occurs when there is progress to report during the scanning process. ### Methods #### Scan >```csharp >Task Scan(IPAddress ipAddress, CancellationToken cancellationToken = null) >``` +>Summary: Initiates an asynchronous scan for the specified IP address. +> +>Parameters:
+>     `ipAddress`  -  The IP address to scan.
+>     `cancellationToken`  -  A token that can be used to request cancellation of the operation.
+> +>Returns: A task that represents the asynchronous operation, resulting in the scan results. #### ScanCidrRange >```csharp >Task ScanCidrRange(IPAddress ipAddress, byte cidrLength, CancellationToken cancellationToken = null) >``` +>Summary: Initiates an asynchronous scan for a range of IP addresses specified by a CIDR notation. +> +>Parameters:
+>     `ipAddress`  -  The starting IP address of the CIDR range.
+>     `cidrLength`  -  The CIDR length that specifies the range of IP addresses to scan.
+>     `cancellationToken`  -  A token that can be used to request cancellation of the operation.
+> +>Returns: A task that represents the asynchronous operation, resulting in the scan results. #### ScanRange >```csharp >Task ScanRange(IPAddress startIpAddress, IPAddress endIpAddress, CancellationToken cancellationToken = null) >``` +>Summary: Initiates an asynchronous scan over a specified range of IP addresses. +> +>Parameters:
+>     `startIpAddress`  -  The starting IP address of the range to scan.
+>     `endIpAddress`  -  The ending IP address of the range to scan.
+>     `cancellationToken`  -  A token that can be used to request cancellation of the operation.
+> +>Returns: A task that represents the asynchronous operation, resulting in the scan results.
## IPPortScan +Provides functionality for scanning IP ports to check for TCP, HTTP, and HTTPS connectivity. >```csharp ->public class IPPortScan : IIPPortScan +>public class IPPortScan : IIPPortScan, IDisposable >``` ### Methods @@ -89,31 +154,72 @@ >```csharp >Task CanConnectWithHttp(int portNumber = 80, CancellationToken cancellationToken = null) >``` +>Summary: Attempts to connect to a specified port using HTTP. +> +>Parameters:
+>     `portNumber`  -  The port number to attempt connection, default is 80.
+>     `cancellationToken`  -  A token to cancel the operation.
+> +>Returns: A task that represents the asynchronous operation, resulting in a boolean indicating connection success. #### CanConnectWithHttpOrHttps >```csharp >Task CanConnectWithHttpOrHttps(int portNumber = 80, bool useHttps = False, CancellationToken cancellationToken = null) >``` +>Summary: Attempts to connect to a specified port using HTTP or HTTPS. +> +>Parameters:
+>     `portNumber`  -  The port number to attempt connection, default is 80 for HTTP and 443 for HTTPS.
+>     `useHttps`  -  Specifies whether to use HTTPS (true) or HTTP (false).
+>     `cancellationToken`  -  A token to cancel the operation.
+> +>Returns: A task that represents the asynchronous operation, resulting in a boolean indicating connection success. #### CanConnectWithHttps >```csharp >Task CanConnectWithHttps(int portNumber = 443, CancellationToken cancellationToken = null) >``` +>Summary: Attempts to connect to a specified port using HTTPS. +> +>Parameters:
+>     `portNumber`  -  The port number to attempt connection, default is 443.
+>     `cancellationToken`  -  A token to cancel the operation.
+> +>Returns: A task that represents the asynchronous operation, resulting in a boolean indicating connection success. #### CanConnectWithTcp >```csharp >Task CanConnectWithTcp(int portNumber, CancellationToken cancellationToken = null) >``` +>Summary: Attempts to connect to a specified port using TCP. +> +>Parameters:
+>     `portNumber`  -  The port number to attempt connection.
+>     `cancellationToken`  -  A token to cancel the operation.
+> +>Returns: A task that represents the asynchronous operation, resulting in a boolean indicating connection success. +#### Dispose +>```csharp +>void Dispose() +>``` #### SetIPAddress >```csharp >void SetIPAddress(IPAddress value) >``` +>Summary: Sets the IP address to scan. +> +>Parameters:
+>     `value`  -  The IP address.
#### SetTimeout >```csharp >void SetTimeout(TimeSpan value) >``` +>Summary: Sets the timeout for connection attempts. +> +>Parameters:
+>     `value`  -  The timeout as a .

## IPScanner -IPScanner LoggerMessages. +Provides functionality for scanning IP addresses and ranges to determine open ports, resolve hostnames, MAC addresses, and vendor information. >```csharp >public class IPScanner : IIPScanner, IDisposable @@ -125,12 +231,16 @@ IPScanner LoggerMessages. >```csharp >Configuration >``` +>Summary: Gets or sets the configuration settings for the IP scanner. +> +>Remarks: This property allows for the dynamic adjustment of the scanner's settings after initialization, providing flexibility to change scanning behavior at runtime. ### Events #### ProgressReporting >```csharp >ProgressReporting >``` +>Summary: Occurs when there is progress to report during a scan operation. ### Methods #### Dispose @@ -141,14 +251,37 @@ IPScanner LoggerMessages. >```csharp >Task Scan(IPAddress ipAddress, CancellationToken cancellationToken = null) >``` +>Summary: Initiates an asynchronous scan for the specified IP address. +> +>Parameters:
+>     `ipAddress`  -  The IP address to scan.
+>     `cancellationToken`  -  A token that can be used to request cancellation of the operation.
+> +>Returns: A task that represents the asynchronous operation, resulting in the scan results. #### ScanCidrRange >```csharp >Task ScanCidrRange(IPAddress ipAddress, byte cidrLength, CancellationToken cancellationToken = null) >``` +>Summary: Initiates an asynchronous scan for a range of IP addresses specified by a CIDR notation. +> +>Parameters:
+>     `ipAddress`  -  The starting IP address of the CIDR range.
+>     `cidrLength`  -  The CIDR length that specifies the range of IP addresses to scan.
+>     `cancellationToken`  -  A token that can be used to request cancellation of the operation.
+> +>Returns: A task that represents the asynchronous operation, resulting in the scan results. #### ScanRange >```csharp >Task ScanRange(IPAddress startIpAddress, IPAddress endIpAddress, CancellationToken cancellationToken = null) >``` +>Summary: Scans a specified range of IP addresses for open ports and services. +> +>Parameters:
+>     `startIpAddress`  -  The starting IP address of the range to scan.
+>     `endIpAddress`  -  The ending IP address of the range to scan.
+>     `cancellationToken`  -  A token to cancel the operation.
+> +>Returns: A task that represents the asynchronous operation, resulting in a collection of scan results.
@@ -255,6 +388,7 @@ IPScanner LoggerMessages.
## IPScannerProgressReport +Represents a progress report for an ongoing IP scanning operation. >```csharp >public class IPScannerProgressReport @@ -266,26 +400,34 @@ IPScanner LoggerMessages. >```csharp >LatestUpdate >``` +>Summary: Gets or sets the latest update or result from the scanning operation. #### PercentageCompleted >```csharp >PercentageCompleted >``` +>Summary: Calculates and returns the percentage of tasks completed. #### TasksProcessedCount >```csharp >TasksProcessedCount >``` +>Summary: Gets or sets the number of tasks that have been processed so far. #### TasksToProcessCount >```csharp >TasksToProcessCount >``` +>Summary: Gets or sets the total number of tasks to process during the scan. #### Type >```csharp >Type >``` +>Summary: Gets or sets the type of the progress reporting event. ### Methods #### ToString >```csharp >string ToString() >``` +>Summary: Provides a string representation of the current progress report. +> +>Returns: A string that represents the current state of the progress report, including details about the latest update, the type of event, and the current progress.
Generated by MarkdownCodeDoc version 1.2
diff --git a/docs/CodeDoc/Atc.Network/Index.md b/docs/CodeDoc/Atc.Network/Index.md index 8bab38e..4119006 100644 --- a/docs/CodeDoc/Atc.Network/Index.md +++ b/docs/CodeDoc/Atc.Network/Index.md @@ -32,6 +32,7 @@ - [ArpHelper](Atc.Network.Helpers.md#arphelper) - [DnsLookupHelper](Atc.Network.Helpers.md#dnslookuphelper) - [IPv4AddressHelper](Atc.Network.Helpers.md#ipv4addresshelper) +- [InternetWorldTimeHelper](Atc.Network.Helpers.md#internetworldtimehelper) - [MacAddressVendorLookupHelper](Atc.Network.Helpers.md#macaddressvendorlookuphelper) - [OpcUaAddressHelper](Atc.Network.Helpers.md#opcuaaddresshelper) - [PingHelper](Atc.Network.Helpers.md#pinghelper) diff --git a/docs/CodeDoc/Atc.Network/IndexExtended.md b/docs/CodeDoc/Atc.Network/IndexExtended.md index be5a22a..dc812d8 100644 --- a/docs/CodeDoc/Atc.Network/IndexExtended.md +++ b/docs/CodeDoc/Atc.Network/IndexExtended.md @@ -88,6 +88,10 @@ - GetLocalAddress() - IsValid(string ipAddress) - ValidateAddresses(IPAddress startIpAddress, IPAddress endIpAddress) +- [InternetWorldTimeHelper](Atc.Network.Helpers.md#internetworldtimehelper) + - Static Methods + - GetTimeForEuropeBerlin(CancellationToken cancellationToken) + - GetTimeForWorldTimezone(string worldTimezone, CancellationToken cancellationToken) - [MacAddressVendorLookupHelper](Atc.Network.Helpers.md#macaddressvendorlookuphelper) - Static Methods - LookupVendorNameFromMacAddress(string macAddress, CancellationToken cancellationToken = null) @@ -138,6 +142,7 @@ - CanConnectWithHttpOrHttps(int portNumber = 80, bool useHttps = False, CancellationToken cancellationToken = null) - CanConnectWithHttps(int portNumber = 443, CancellationToken cancellationToken = null) - CanConnectWithTcp(int portNumber, CancellationToken cancellationToken = null) + - Dispose() - SetIPAddress(IPAddress value) - SetTimeout(TimeSpan value) - [IPScanner](Atc.Network.Internet.md#ipscanner) diff --git a/src/Atc.Network/Internet/IIPPortScan.cs b/src/Atc.Network/Internet/IIPPortScan.cs index fc8b534..f8a8f7c 100644 --- a/src/Atc.Network/Internet/IIPPortScan.cs +++ b/src/Atc.Network/Internet/IIPPortScan.cs @@ -1,25 +1,69 @@ namespace Atc.Network.Internet; +/// +/// Defines a contract for scanning IP ports to check for connectivity using TCP, HTTP, and HTTPS. +/// public interface IIPPortScan { + /// + /// Sets the IP address to be used for scanning operations. + /// + /// The IP address to scan. void SetIPAddress( IPAddress value); + /// + /// Sets the timeout period for connection attempts. + /// + /// The maximum amount of time to wait for a connection attempt before timing out. void SetTimeout( TimeSpan value); + /// + /// Checks if a TCP connection can be established on the specified port. + /// + /// The port number to check. + /// A token to cancel the operation. + /// + /// A task that represents the asynchronous operation, resulting in true if the connection was successful; otherwise, false. + /// Task CanConnectWithTcp( int portNumber, CancellationToken cancellationToken = default); + /// + /// Checks if an HTTP connection can be established on the specified port. + /// + /// The port number to check, defaulting to 80. + /// A token to cancel the operation. + /// + /// A task that represents the asynchronous operation, resulting in true if the connection was successful; otherwise, false. + /// Task CanConnectWithHttp( int portNumber = 80, CancellationToken cancellationToken = default); + /// + /// Checks if an HTTPS connection can be established on the specified port. + /// + /// The port number to check, defaulting to 443. + /// A token to cancel the operation. + /// + /// A task that represents the asynchronous operation, resulting in true if the connection was successful; otherwise, false. + /// Task CanConnectWithHttps( int portNumber = 443, CancellationToken cancellationToken = default); + /// + /// Checks if a connection using either HTTP or HTTPS can be established on the specified port. + /// + /// The port number to check, defaulting to 80. + /// Indicates whether to use HTTPS (true) or HTTP (false). + /// A token to cancel the operation. + /// + /// A task that represents the asynchronous operation, resulting in true if the connection was successful; otherwise, false. + /// Task CanConnectWithHttpOrHttps( int portNumber = 80, bool useHttps = false, diff --git a/src/Atc.Network/Internet/IIPScanner.cs b/src/Atc.Network/Internet/IIPScanner.cs index 926c28b..8ae5547 100644 --- a/src/Atc.Network/Internet/IIPScanner.cs +++ b/src/Atc.Network/Internet/IIPScanner.cs @@ -1,20 +1,57 @@ namespace Atc.Network.Internet; +/// +/// Defines a contract for scanning IP addresses or ranges to assess network +/// accessibility and gather information like open ports, hostnames, and more. +/// public interface IIPScanner { + /// + /// Occurs when there is progress to report during the scanning process. + /// event EventHandler? ProgressReporting; + /// + /// Gets or sets the configuration settings for the IP scanner. + /// + /// The configuration settings used by the scanner. IPScannerConfig Configuration { get; set; } + /// + /// Initiates an asynchronous scan for the specified IP address. + /// + /// The IP address to scan. + /// A token that can be used to request cancellation of the operation. + /// + /// A task that represents the asynchronous operation, resulting in the scan results. + /// Task Scan( IPAddress ipAddress, CancellationToken cancellationToken = default); + /// + /// Initiates an asynchronous scan for a range of IP addresses specified by a CIDR notation. + /// + /// The starting IP address of the CIDR range. + /// The CIDR length that specifies the range of IP addresses to scan. + /// A token that can be used to request cancellation of the operation. + /// + /// A task that represents the asynchronous operation, resulting in the scan results. + /// Task ScanCidrRange( IPAddress ipAddress, byte cidrLength, CancellationToken cancellationToken = default); + /// + /// Initiates an asynchronous scan over a specified range of IP addresses. + /// + /// The starting IP address of the range to scan. + /// The ending IP address of the range to scan. + /// A token that can be used to request cancellation of the operation. + /// + /// A task that represents the asynchronous operation, resulting in the scan results. + /// Task ScanRange( IPAddress startIpAddress, IPAddress endIpAddress, diff --git a/src/Atc.Network/Internet/IPScanner.cs b/src/Atc.Network/Internet/IPScanner.cs index 3e0324f..50257c9 100644 --- a/src/Atc.Network/Internet/IPScanner.cs +++ b/src/Atc.Network/Internet/IPScanner.cs @@ -2,6 +2,10 @@ // ReSharper disable LocalizableElement namespace Atc.Network.Internet; +/// +/// Provides functionality for scanning IP addresses and ranges to determine open ports, +/// resolve hostnames, MAC addresses, and vendor information. +/// [SuppressMessage("Design", "CA1031:Do not catch general exception types", Justification = "OK.")] [SuppressMessage("StyleCop.CSharp.DocumentationRules", "SA1601:Partial elements should be documented", Justification = "OK.")] [SuppressMessage("Major Code Smell", "S108:Nested blocks of code should not be left empty", Justification = "OK.")] @@ -17,8 +21,15 @@ public partial class IPScanner : IIPScanner, IDisposable private int tasksToProcessCount; private int tasksProcessedCount; + /// + /// Occurs when there is progress to report during a scan operation. + /// public event EventHandler? ProgressReporting; + /// + /// Initializes a new instance of the class with various configuration options. + /// + /// The logger to use for logging information and errors during scan operations. public IPScanner( ILogger logger) { @@ -26,6 +37,11 @@ public IPScanner( this.Configuration = new IPScannerConfig(); } + /// + /// Initializes a new instance of the class with a specified logger and optional configuration settings. + /// + /// The logger to use for logging information and errors during scan operations. + /// Optional configuration settings for the scanner. If not provided, default settings are used. public IPScanner( ILogger logger, IPScannerConfig? ipScannerConfig) @@ -34,24 +50,56 @@ public IPScanner( this.Configuration = ipScannerConfig ?? new IPScannerConfig(); } + /// + /// Initializes a new instance of the class using a default logger instance. + /// public IPScanner() : this(NullLogger.Instance) { } + /// + /// Initializes a new instance of the class with optional configuration settings using a default logger instance. + /// + /// Optional configuration settings for the scanner. If not provided, default settings are used. public IPScanner( IPScannerConfig? ipScannerConfig) : this(NullLogger.Instance, ipScannerConfig) { } + /// + /// Gets or sets the configuration settings for the IP scanner. + /// + /// The configuration settings used by the scanner. + /// + /// This property allows for the dynamic adjustment of the scanner's settings after initialization, + /// providing flexibility to change scanning behavior at runtime. + /// public IPScannerConfig Configuration { get; set; } + /// + /// Initiates an asynchronous scan for the specified IP address. + /// + /// The IP address to scan. + /// A token that can be used to request cancellation of the operation. + /// + /// A task that represents the asynchronous operation, resulting in the scan results. + /// public Task Scan( IPAddress ipAddress, CancellationToken cancellationToken = default) => ScanRange(ipAddress, ipAddress, cancellationToken); + /// + /// Initiates an asynchronous scan for a range of IP addresses specified by a CIDR notation. + /// + /// The starting IP address of the CIDR range. + /// The CIDR length that specifies the range of IP addresses to scan. + /// A token that can be used to request cancellation of the operation. + /// + /// A task that represents the asynchronous operation, resulting in the scan results. + /// public Task ScanCidrRange( IPAddress ipAddress, byte cidrLength, @@ -71,6 +119,15 @@ public Task ScanCidrRange( return ScanRange(startIpAddress, endIpAddress, cancellationToken); } + /// + /// Scans a specified range of IP addresses for open ports and services. + /// + /// The starting IP address of the range to scan. + /// The ending IP address of the range to scan. + /// A token to cancel the operation. + /// + /// A task that represents the asynchronous operation, resulting in a collection of scan results. + /// public async Task ScanRange( IPAddress startIpAddress, IPAddress endIpAddress, @@ -159,6 +216,9 @@ protected virtual void Dispose( syncLock.Dispose(); } + /// + /// Raises the event with current progress information. + /// private void RaiseProgressReporting( IPScannerProgressReportingType reportingType, IPScanResult? ipScanResult) diff --git a/src/Atc.Network/Internet/IPScannerProgressReport.cs b/src/Atc.Network/Internet/IPScannerProgressReport.cs index 8887d9c..8a4d0c1 100644 --- a/src/Atc.Network/Internet/IPScannerProgressReport.cs +++ b/src/Atc.Network/Internet/IPScannerProgressReport.cs @@ -1,18 +1,48 @@ namespace Atc.Network.Internet; +/// +/// Represents a progress report for an ongoing IP scanning operation. +/// public class IPScannerProgressReport { + /// + /// Gets or sets the total number of tasks to process during the scan. + /// + /// The total number of scanning tasks. public int TasksToProcessCount { get; set; } + /// + /// Gets or sets the number of tasks that have been processed so far. + /// + /// The number of completed scanning tasks. public int TasksProcessedCount { get; set; } + /// + /// Gets or sets the type of the progress reporting event. + /// + /// The type of event being reported. public IPScannerProgressReportingType Type { get; set; } + /// + /// Gets or sets the latest update or result from the scanning operation. + /// + /// The latest individual scan result. public IPScanResult? LatestUpdate { get; set; } + /// + /// Calculates and returns the percentage of tasks completed. + /// + /// The percentage of scanning tasks that have been completed. public double PercentageCompleted => MathHelper.Percentage(TasksToProcessCount, TasksProcessedCount); + /// + /// Provides a string representation of the current progress report. + /// + /// + /// A string that represents the current state of the progress report, + /// including details about the latest update, the type of event, and the current progress. + /// public override string ToString() { var sb = new StringBuilder(); diff --git a/test/Atc.Network.Test/CodeComplianceTests.cs b/test/Atc.Network.Test/CodeComplianceTests.cs index f0ddbc7..1fd3925 100644 --- a/test/Atc.Network.Test/CodeComplianceTests.cs +++ b/test/Atc.Network.Test/CodeComplianceTests.cs @@ -19,6 +19,7 @@ public class CodeComplianceTests typeof(IPPortScan), typeof(IPScanner), typeof(DnsLookupHelper), + typeof(InternetWorldTimeHelper), typeof(IPAddressExtensions), typeof(UshortExtensions), typeof(UdpClient),