Merge pull request #163 from end2endzone/feature-issue109

Merge branch feature-issue109.

Author: end2endzone

CHANGES

@@ -1,6 +1,7 @@
 Changes for 0.10.0
 
 * Deprecated support for icons with negative resource id.
+* Fixed issue #109: Implement default and verbose logging.
 * Fixed issue #150: ico icon (that do not specifically force index=0) are not working.
 * Fixed issue #155: Drop support for loading icons from a resource id (icons with a negative index smaller than -1).
 * Fixed issue #157: Compilation fails on Github Action: `fatal error C1083: Cannot open include file: 'atlbase.h': No such file or directory`.

UserManual.md

@@ -40,12 +40,13 @@ This manual includes a description of the system functionalities and capabilitie
   * [Setting properties](#setting-properties)
   * [Property expansion](#property-expansion)
   * [Using properties](#using-properties)
-  * [Environment variables](#environment-variables)
+  * [Environment variables properties](#environment-variables-properties)
   * [Live properties](#live-properties)
   * [Selection-based properties](#selection-based-properties)
   * [Multi-selection-based properties](#multi-selection-based-properties)
   * [Fixed properties](#fixed-properties)
   * [Default properties](#default-properties)
+* [Environment variables](#environment-variables)
 * [Plugins](#plugins)
   * [Plugin overview](#plugin-overview)
   * [C API](#c-api)
@@ -1530,7 +1531,7 @@ For instance, if one wants to implement 2 menus (called 'A' and 'B') and only sh
 
 
 
-## Environment variables ##
+## Environment variables properties ##
 
 The list of environment variables is available through the property system.
 
@@ -1776,6 +1777,25 @@ For example, the following would define `services.wce.command.start` and `servic
 
 
 
+# Environment variables #
+
+ShellAnything default startup behavior can be modified by setting specific pre-defined environment variables. Some features or configuration options can also be enabled or disabled through environment variables. For example, one can define an environment variables to enable verbose logging.
+
+Most of the time, if a feature can be enabled/disabled from an environment variable and/or a property, the environment variable have priority over internal properties.
+
+Most environment variables are detected when the application starts. After application startup, if you modify an environment variable you have to log off from windows and log in again for the changes to take effect.
+
+All ShellAnything environment variables names are prefixed with `SA_`.
+
+The following table defines the list of pre-defined environment variables for ShellAnything:
+
+| Name                           | Description                                                                                                        |
+|--------------------------------|--------------------------------------------------------------------------------------------------------------------|
+| SA_OPTION_LOGGING_VERBOSE      | Enables [verbose logging](#verbose-logging) when set to a value that evaluates to [true](#istrue-attribute).       |
+
+
+
+
 # Plugins #
 
 
@@ -2553,6 +2573,22 @@ There are no plan for keeping the log files for more than 5 days.
 
 
 
+### Verbose logging ###
+
+The application has a verbose logging mode. When enabled, the application will log additional details. This mode should be disabled by default. It should be temporary enabled because log files will likely contain sensitive information.
+
+Verbose mode is highly beneficial for debugging because it provides detailed information about the execution of the program. It allows you to see each step and print out intermediate values, helping you identify where things might be going wrong. For example, it is useful for diagnosing the reason for [Visibility / Validity](#visibility--validity) check failures.
+
+The verbose mode can be enabled (or disabled) with the following option :
+* Setting property `system.logging.verbose` to a value that evaluates to [true](#istrue-attribute) or [false](#isfalse-attribute).
+* Setting environment variable `SA_OPTION_LOGGING_VERBOSE` to a value that evaluates to [true](#istrue-attribute) or [false](#isfalse-attribute).
+
+If both options are specified, the environment variable has priority. 
+
+If no option is specified, verbose mode is disabled.
+
+
+
 ## Missing ampersand character (`&`) in menus ##
 
 One might be puzzled as to why his menus do not display ampersand character (`&`) properly.

include/shellanything/sa_logging.h

@@ -25,6 +25,7 @@
 #ifndef SA_API_LOGGING_H
 #define SA_API_LOGGING_H
 
+#include "shellanything/sa_types.h"
 #include "shellanything/sa_enums.h"
 
 #ifdef __cplusplus
@@ -34,6 +35,12 @@ extern "C" {
 #endif
 #endif
 
+/// <summary>
+/// Check if verbose logging is enabled.
+/// </summary>
+/// <returns>Return 1 if the verbose logging feature is enabled. Returns 0 otherwise.</returns>
+sa_boolean sa_logging_is_verbose();
+
 /// <summary>
 /// Log a custom message in logs.
 /// </summary>

resources/configurations/shellanything.xml

@@ -103,9 +103,34 @@
             <open path="https://github.com/end2endzone/ShellAnything/releases/latest" />
           </actions>
         </menu>
+      </menu>
+
+      <menu name="Verbose logging">
+        <icon path="C:\Windows\system32\shell32.dll" index="70" />
 
+        <menu name="Verbose logging is ENABLED">
+          <visibility istrue="${system.logging.verbose}" />
+        </menu>
+        <menu name="Verbose logging is DISABLED">
+          <visibility istrue="${system.logging.verbose}" inverse="istrue" />
+        </menu>
+        <menu separator="true" />
+        <menu name="Enable">
+          <icon path="C:\Windows\system32\shell32.dll" index="302" />
+          <actions>
+            <property name="system.logging.verbose" value="${system.true}" />
+          </actions>
+        </menu>
+        <menu name="Disable">
+          <icon path="C:\Windows\system32\shell32.dll" index="109" />
+          <actions>
+            <property name="system.logging.verbose" value="${system.false}" />
+          </actions>
+        </menu>
       </menu>
 
+      <menu separator="true />
+      
       <menu name="More configurations files...">
         <icon path="C:\Windows\system32\shell32.dll" index="69" />
         <actions>

src/api/sa.api.def

@@ -36,6 +36,7 @@ EXPORTS
   sa_icon_set_index
   sa_icon_set_path
   sa_icon_to_immutable
+  sa_logging_is_verbose
   sa_logging_print
   sa_logging_print_format
   sa_memory_alloc

src/api/sa_logging.cpp

@@ -27,6 +27,14 @@
 #include <stdarg.h> //for ...
 #include <string>
 
+sa_boolean sa_logging_is_verbose()
+{
+  bool value = shellanything::LoggerHelper::IsVerboseLoggingEnabled();
+  if (value)
+    return 1;
+  return 0;
+}
+
 void sa_logging_print(sa_log_level_t level, const char* source_name, const char* message)
 {
   if (source_name)

src/core/ActionManager.cpp

@@ -26,20 +26,26 @@
 #include "PropertyManager.h"
 #include "LoggerHelper.h"
 
+#include "SaUtils.h"
+
 #include "rapidassist/errors.h"
 
 namespace shellanything
 {
 
   bool ActionManager::Execute(const Menu* menu, const SelectionContext& context)
   {
+    SA_DECLARE_SCOPE_LOGGER_ARGS(sli);
+    sli.verbose = true;
+    ScopeLogger logger(&sli);
+
     //compute the visual menu title
     shellanything::PropertyManager& pmgr = shellanything::PropertyManager::GetInstance();
     std::string title = pmgr.Expand(menu->GetName());
 
     bool success = true;
 
-    SA_LOG(INFO) << "Executing action(s) for menu '" << title.c_str() << "'...";
+    SA_LOG(INFO) << "Executing action(s) for menu '" << title.c_str() << "', id=" << menu->GetCommandId() << "...";
 
     //execute actions
     const shellanything::IAction::ActionPtrList& actions = menu->GetActions();
@@ -59,7 +65,7 @@ namespace shellanything
           if (dwError)
           {
             std::string error_message = ra::errors::GetErrorCodeDescription(dwError);
-            SA_LOG(ERROR) << "Action #" << (i + 1) << " has failed: " << error_message;
+            SA_LOG(ERROR) << "Action #" << (i + 1) << " has failed: " << ToHexString(dwError) << ", " << error_message;
           }
           else
           {

src/core/ActionOpen.cpp

@@ -139,14 +139,19 @@ namespace shellanything
     {
       SA_LOG(INFO) << "Open file '" << path << "'.";
       uint32_t pId = ra::process::OpenDocumentUtf8(path);
-      return pId != ra::process::INVALID_PROCESS_ID;
+      bool success = (pId != ra::process::INVALID_PROCESS_ID);
+      if (!success)
+        SA_LOG(ERROR) << "Failed opening file '" << path << "'.";
+      return success;
     }
 
     //is path a directory?
     if (ra::filesystem::DirectoryExistsUtf8(path.c_str()))
     {
       SA_LOG(INFO) << "Open directory '" << path << "'.";
       bool success = OpenPathGeneric(path);
+      if (!success)
+        SA_LOG(ERROR) << "Failed opening directory '" << path << "'.";
       return success;
     }
 
@@ -156,6 +161,8 @@ namespace shellanything
     {
       SA_LOG(INFO) << "Open url '" << path << "'.";
       bool success = OpenPathGeneric(path);
+      if (!success)
+        SA_LOG(ERROR) << "Failed opening URL '" << path << "'.";
       return success;
     }
 

src/core/ActionProperty.cpp

@@ -259,7 +259,7 @@ namespace shellanything
       }
     }
 
-    // If regisrykey is specified, it has priority over value. This is required to allow setting a property to an empty value (a.k.a. value="").
+    // If registrykey is specified, it has priority over value. This is required to allow setting a property to an empty value (a.k.a. value="").
     if (!registrykey.empty())
     {
       std::string tmp_value;

src/core/ActionStop.cpp

@@ -115,7 +115,7 @@ namespace shellanything
 
     bool validated = mValidator->Validate(context);
 
-    //update the property
+    //log the result
     if (validated)
       SA_LOG(INFO) << "ActionStop: Validation is successful.";
     else