Revize 12899c8b

re #9570 - Commented IProcessDetection.cs, IProcessUtils.cs, ProcessDetection.cs, and ProcessUtils.cs

ld_client/LDClient/detection/IProcessDetection.cs

@@ -1 +1 @@
 namespace LDClient.detection {
     
+    /// <summary>
+    /// This interface defines the functionality of a process detector.
+    /// A process detector is used to determine whether a user is currently
+    /// using a debugger or not.
+    /// </summary>
     internal interface IProcessDetection {
         
+        /// <summary>
+        /// Periodically runs process detection. This method is instantiated
+        /// as a thread from the main class (Program.cs).
+        /// </summary>
         public void RunPeriodicDetection();
     }
 }

ld_client/LDClient/detection/IProcessUtils.cs

@@ -5 +5 @@
 using System.Threading.Tasks;
 
 namespace LDClient.detection {
+    
+    /// <summary>
+    /// This interface defines the functionality of all methods that
+    /// are used to work with processes (within this project).
+    /// </summary>
     public interface IProcessUtils {
+        
+        /// <summary>
+        /// Checks if a process is running or not.
+        /// </summary>
+        /// <param name="name">Name of the process</param>
+        /// <returns>True, if the process is running. False otherwise.</returns>
         public bool IsProcessRunning(string name);
 
+        /// <summary>
+        /// Executes a new process (t32rem.exe) with arguments which are passed in
+        /// as a parameter of the method.
+        /// </summary>
+        /// <param name="fileName">Path to the .exe file</param>
+        /// <param name="argument">Arguments passed into the .exe file</param>
+        /// <param name="timeout">Timeout used when waiting for the process to terminate</param>
+        /// <param name="desiredExitCode">Status code indicating a successful termination of the process.</param>
+        /// <returns>True, if the command was executed successfully. False otherwise.</returns>
         public bool ExecuteNewProcess(string fileName, string argument, int timeout, int desiredExitCode);
     }
 }

ld_client/LDClient/detection/ProcessDetection.cs

@@ -3 +3 @@
 using LDClient.network.data;
 
 namespace LDClient.detection {
-   
-	 public sealed class ProcessDetection : IProcessDetection {
-        
+
+    /// <summary>
+    /// This class takes care of process detection. When t32mtc (process)
+    /// is detected, it means that the debugger is currently being used.
+    /// The class keeps track of the current state of a debugger.
+    /// </summary>
+    public sealed class ProcessDetection : IProcessDetection {
+
+        /// <summary>
+        /// Datetime format used when sending payloads to the server.
+        /// </summary>
         private const string DatetimeFormat = "yyyy-MM-dd hh:mm:ss";
 
+        /// <summary>
+        /// Name of the process the application detects.
+        /// </summary>
         private readonly string _processName;
+        
+        /// <summary>
+        /// How often the application check the current status of the process (cunning / not running).
+        /// </summary>
         private readonly uint _detectionPeriodMs;
+        
+        /// <summary>
+        /// Instance of InfoFetcher used to fetch information from the debugger
+        /// (when the process is detected).
+        /// </summary>
         private readonly IInfoFetcher _infoFetcher;
+        
+        /// <summary>
+        /// Instance of API clients used for sending data off to the server.
+        /// </summary>
         private readonly IApiClient _apiClient;
+        
+        /// <summary>
+        /// Instance of ProcessUtils which encapsulates common functionality
+        /// when it comes to dealing with processes (limited by the needs of this application).
+        /// </summary>
         private readonly IProcessUtils _processUtils;
 
+        /// <summary>
+        /// Flag indicating whether the process is currently running or not.
+        /// </summary>
         private bool _processIsActive;
+        
+        /// <summary>
+        /// Flag if the application failed to retrieve data when the process was detected.
+        /// </summary>
         private bool _failedToRetrieveData;
+        
+        /// <summary>
+        /// Last payload that was sent to the server.
+        /// </summary>
         private Payload? _lastConnectedPayload;
 
+        /// <summary>
+        /// Flag used to stop the thread (process detection).
+        /// </summary>
         public bool DetectionRunning = false;
-
-        public ProcessDetection(string processName, uint detectionPeriodMs, IInfoFetcher infoFetcher, IApiClient apiClient, IProcessUtils processUtils) {
+        
+        /// <summary>
+        /// Creates an instance of this class.
+        /// </summary>
+        /// <param name="processName">Name of the process the application detects</param>
+        /// <param name="detectionPeriodMs">How often the application check the current status of the process (cunning / not running)</param>
+        /// <param name="infoFetcher">Instance of InfoFetcher used to fetch information from the debugger</param>
+        /// <param name="apiClient">Instance of API clients used for sending data off to the server</param>
+        /// <param name="processUtils">Instance of ProcessUtils which encapsulates common functionality when it comes to dealing with processes (limited by the needs of this application)</param>
+        public ProcessDetection(string processName, uint detectionPeriodMs, IInfoFetcher infoFetcher,
+            IApiClient apiClient, IProcessUtils processUtils) {
             _processName = processName;
             _detectionPeriodMs = detectionPeriodMs;
             _infoFetcher = infoFetcher;
@@ -29 +81 @@
             _processUtils = processUtils;
         }
 
+        /// <summary>
+        /// Retrieves data from the debugger.
+        /// </summary>
+        /// <returns>True, if the data was fetched successfully. False, otherwise.</returns>
         private async Task<bool> RetrieveDataFromDebugger() {
+            // Try to fetch data from the debugger.
             var success = await _infoFetcher.FetchDataAsync();
+            
+            // If the data was fetched successfully, send a payload off to the server.
             if (success) {
-                _lastConnectedPayload = await SendDataToServerAsync(_infoFetcher.HeadSerialNumber, _infoFetcher.BodySerialNumber, DatetimeFormat);
+                _lastConnectedPayload = await SendDataToServerAsync(_infoFetcher.HeadSerialNumber,
+                    _infoFetcher.BodySerialNumber, DatetimeFormat);
             }
             return success;
         }
 
+        /// <summary>
+        /// Sends a payload to the server when a debugger gets disconnected.
+        /// </summary>
         private async Task DebuggerDisconnected() {
+            // Make sure the debugger was connected in the first place.
             if (_lastConnectedPayload is not null) {
+                // Update the status and timestamp of the last payload
+                // (the serial numbers remain the same).
                 _lastConnectedPayload.Status = ConnectionStatus.Disconnected;
                 _lastConnectedPayload.TimeStamp = DateTime.Now.ToString(DatetimeFormat);
+                
+                // Send the data to the server.
                 await _apiClient.SendPayloadAsync(_lastConnectedPayload);
+                
+                // Clear the last payload.
                 _lastConnectedPayload = null;
             }
         }
 
+        /// <summary>
+        /// Checks if the t32mtc process is running or not. 
+        /// </summary>
         private async Task DetectProcessAsync() {
+            // Check if the process is running.
             var processExists = _processUtils.IsProcessRunning(_processName);
 
+            // Check if the process was not running but now it is (flip flop ON). 
             if (processExists && !_processIsActive) {
                 Program.DefaultLogger.Info($"Process started: {_processName}");
                 if (!_failedToRetrieveData) {
                     _failedToRetrieveData = !await RetrieveDataFromDebugger();
                 }
-            } else if (!processExists && _processIsActive) {
+            }
+            // Check if the process was running but now it is not (fli flop OFF).
+            else if (!processExists && _processIsActive) {
                 Program.DefaultLogger.Info($"Process stopped: {_processName}");
                 _failedToRetrieveData = false;
                 await DebuggerDisconnected();
             }
+
+            // Keep track of the current state of the debugger.
             _processIsActive = processExists;
         }
-        
+
+        /// <summary>
+        /// Creates a payload and sends it to the server.
+        /// </summary>
+        /// <param name="headSerialNumber">serial number of the head of the debugger</param>
+        /// <param name="bodySerialNumber">serial number of the body of the debugger</param>
+        /// <param name="datetimeFormat">datetime format (timestamp)</param>
+        /// <returns>the newly-created payload</returns>
         private async Task<Payload> SendDataToServerAsync(string headSerialNumber, string bodySerialNumber, string datetimeFormat) {
+            // Create a new payload. 
             Payload payload = new() {
                 UserName = Environment.UserName,
                 HostName = Environment.MachineName,
@@ -75 +162 @@
                 },
                 Status = ConnectionStatus.Connected
             };
+            
+            // Send it to the server and return it.
             await _apiClient.SendPayloadAsync(payload);
             return payload;
         }
-        
+
+        /// <summary>
+        /// Periodically runs process detection. This method is instantiated
+        /// as a thread from the main class (Program.cs).
+        /// </summary>
         public async void RunPeriodicDetection() {
             Program.DefaultLogger.Info("Process periodic detector has started");
             DetectionRunning = true;
+            
             while (DetectionRunning) {
                 await DetectProcessAsync();
-                Thread.Sleep((int)_detectionPeriodMs);
+                Thread.Sleep((int) _detectionPeriodMs);
             }
         }
     }

ld_client/LDClient/detection/ProcessUtils.cs

@@ -6 +6 @@
 using System.Threading.Tasks;
 
 namespace LDClient.detection {
-    public class ProcessUtils : IProcessUtils{
+    
+    /// <summary>
+    /// This class implements the IProcessUtils interface.
+    /// It implements methods that are used when dealing with processes.
+    /// </summary>
+    public class ProcessUtils : IProcessUtils {
 
+        /// <summary>
+        /// Checks if a process is running or not.
+        /// </summary>
+        /// <param name="name">Name of the process</param>
+        /// <returns>True, if the process is running. False otherwise.</returns>
         public bool IsProcessRunning(string name) {
             return Process.GetProcessesByName(name).Length > 0;
         }
-
-
+        
+        /// <summary>
+        /// Executes a new process (t32rem.exe) with arguments which are passed in
+        /// as a parameter of the method.
+        /// </summary>
+        /// <param name="fileName">Path to the .exe file</param>
+        /// <param name="argument">Arguments passed into the .exe file</param>
+        /// <param name="timeout">Timeout used when waiting for the process to terminate</param>
+        /// <param name="desiredExitCode">Status code indicating a successful termination of the process.</param>
+        /// <returns>True, if the command was executed successfully. False otherwise.</returns>
         public bool ExecuteNewProcess(string fileName, string argument, int timeout, int desiredExitCode) {
-
+            // Create a new process.
             var t32RemProcess = new Process();
             t32RemProcess.StartInfo.FileName = fileName;
             t32RemProcess.StartInfo.Arguments = argument;
+            
             try {
+                // Execute the process and wait until it terminates or until the timeout is up.
                 t32RemProcess.Start();
                 if (!t32RemProcess.WaitForExit(timeout)) {
                     Program.DefaultLogger.Error($"Execution has not terminated within a predefined timeout of {timeout} ms");
                     return false;
                 }
+                
+                // Check if the process terminated successfully.
                 if (t32RemProcess.ExitCode != desiredExitCode) {
                     Program.DefaultLogger.Error($"Execution terminated with an error code of {t32RemProcess.ExitCode}");
                     return false;
@@ -32 +54 @@
                 Program.DefaultLogger.Error($"Failed to run {fileName} {argument}. {exception.Message}");
                 return false;
             }
-
             return true;
         }
-
     }
 }