[freetype2] logging 2a46d1f 01/16: [base] Add public API to change log handling function.

[Werner LEMBERG]

branch: logging
commit 2a46d1f04eb11688932d4e2da2b9b7de3dff6391
Author: Priyesh Kumar <priyeshkkumar@gmail.com>
Commit: Werner Lemberg <wl@gnu.org>

    [base] Add public API to change log handling function.
    
    * include/freetype/ftlogging.h (FT_Custom_Log_Handler): New function
    typedef to store the custom callback logging function.
    (FT_Set_Log_Handler, FT_Set_Default_Log_Handler): New functions to
    set and reset custom log handler.
    
    * include/freetype/internal/ftdebug.h (custom_output_handler): New
    variable to support a custom callback logging function.
    (FT_Logging_Callback): A new function typedef to print log using
    custom callback logging function, which is set using
    `FT_Set_Log_Handler`.
    (FT_Log): Use it.
    
    * src/base/ftdebug.c (FT_Set_Log_Handler,
    FT_Set_Default_Log_Handler, FT_Logging_Callback): Add function
    definitions.
---
 ChangeLog                           | 20 ++++++++++++
 include/freetype/ftlogging.h        | 63 +++++++++++++++++++++++++++++++++++++
 include/freetype/internal/ftdebug.h | 31 +++++++++++++++---
 src/base/ftdebug.c                  | 45 ++++++++++++++++++++++++--
 4 files changed, 152 insertions(+), 7 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index f3f113e..e6222f3 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,23 @@
+2020-11-30  Priyesh Kumar  <priyeshkkumar@gmail.com>
+
+       [base] Add public API to change log handling function.
+
+       * include/freetype/ftlogging.h (FT_Custom_Log_Handler): New function
+       typedef to store the custom callback logging function.
+       (FT_Set_Log_Handler, FT_Set_Default_Log_Handler): New functions to
+       set and reset custom log handler.
+
+       * include/freetype/internal/ftdebug.h (custom_output_handler): New
+       variable to support a custom callback logging function.
+       (FT_Logging_Callback): A new function typedef to print log using
+       custom callback logging function, which is set using
+       `FT_Set_Log_Handler`.
+       (FT_Log): Use it.
+
+       * src/base/ftdebug.c (FT_Set_Log_Handler,
+       FT_Set_Default_Log_Handler, FT_Logging_Callback): Add function
+       definitions.
+
 2020-11-28  Priyesh Kumar  <priyeshkkumar@gmail.com>
 
        [base] Add public API to change the levels of tracing components.
diff --git a/include/freetype/ftlogging.h b/include/freetype/ftlogging.h
index 6f5c4f0..6f65ec7 100644
--- a/include/freetype/ftlogging.h
+++ b/include/freetype/ftlogging.h
@@ -91,6 +91,69 @@ FT_BEGIN_HEADER
   FT_EXPORT( void )
   FT_Trace_Set_Default_Level( void );
 
+
+  /**************************************************************************
+   *
+   * @functype:
+   *   FT_Custom_Log_Handler
+   *
+   * @description:
+   *   A function typedef that is used to handle the logging of tracing and
+   *   debug messages on a file system.
+   *
+   * @input:
+   *   ft_component ::
+   *     The name of `FT_COMPONENT` from which the current debug or error
+   *     message is produced.
+   *
+   *   fmt ::
+   *     Actual debug or tracing message.
+   *
+   *   args::
+   *     Arguments of debug or tracing messages.
+   */
+  typedef void
+  (*FT_Custom_Log_Handler)( const char*  ft_component,
+                            const char*  fmt,
+                            va_list      args );
+
+
+  /**************************************************************************
+   *
+   * @function:
+   *   FT_Set_Log_Handler
+   *
+   * @description:
+   *   A function to set a custom log handler.
+   *
+   * @input:
+   *   handler ::
+   *     New logging function.
+   *
+   * @note:
+   *   This function is only available if compilation option `@FT_LOGGING`
+   *   is set.
+   */
+  FT_EXPORT( void )
+  FT_Set_Log_Handler( FT_Custom_Log_Handler  handler );
+
+
+  /**************************************************************************
+   *
+   * @function:
+   *   FT_Set_Default_Log_Handler
+   *
+   * @description:
+   *   A function to undo the effect of @FT_Set_Log_Handler, resetting the
+   *   log handler to FreeType's built-in version.
+   *
+   * @note:
+   *   This function is only available if compilation option `@FT_LOGGING`
+   *   is set.
+   */
+  FT_EXPORT( void )
+  FT_Set_Default_Log_Handler( void );
+
   /* */
 
 
diff --git a/include/freetype/internal/ftdebug.h 
b/include/freetype/internal/ftdebug.h
index 8fe8846..464717a 100644
--- a/include/freetype/internal/ftdebug.h
+++ b/include/freetype/internal/ftdebug.h
@@ -121,7 +121,12 @@ FT_BEGIN_HEADER
                                                                            \
             ft_add_tag( dlg_tag );                                         \
             if ( ft_trace_levels[FT_TRACE_COMP( FT_COMPONENT )] >= level ) \
-              dlg_trace varformat;                                         \
+            {                                                              \
+              if ( custom_output_handler != NULL )                         \
+                FT_Logging_Callback varformat;                             \
+              else                                                         \
+                dlg_trace varformat;                                       \
+            }                                                              \
             ft_remove_tag( dlg_tag );                                      \
           } while( 0 )
 
@@ -367,12 +372,16 @@ FT_BEGIN_HEADER
 
   /**************************************************************************
    *
-   * `ft_default_log_handler` stores the function pointer that is used
-   * internally by FreeType to print logs to a file.
+   * 1. `ft_default_log_handler` stores the function pointer that is used
+   *    internally by FreeType to print logs to a file.
+   *
+   * 2. `custom_output_handler` stores the function pointer to the callback
+   *    function provided by the user.
    *
    * It is defined in `ftdebug.c`.
    */
-  extern dlg_handler  ft_default_log_handler;
+  extern dlg_handler            ft_default_log_handler;
+  extern FT_Custom_Log_Handler  custom_output_handler;
 
 
   /**************************************************************************
@@ -381,7 +390,6 @@ FT_BEGIN_HEADER
    * un-initialize `FILE*`.
    *
    * These functions are defined in `ftdebug.c`.
-   *
    */
   FT_BASE( void )
   ft_logging_init( void );
@@ -395,6 +403,7 @@ FT_BEGIN_HEADER
    * For printing the name of `FT_COMPONENT` along with the actual log we
    * need to add a tag with the name of `FT_COMPONENT`.
    *
+   * These functions are defined in `ftdebug.c`.
    */
   FT_BASE( void )
   ft_add_tag( const char*  tag );
@@ -402,6 +411,18 @@ FT_BEGIN_HEADER
   FT_BASE( void )
   ft_remove_tag( const char*  tag );
 
+
+  /**************************************************************************
+   *
+   * A function to print log data using a custom callback logging function
+   * (which is set using `FT_Set_Log_Handler`).
+   *
+   * This function is defined in `ftdebug.c`.
+   */
+  FT_BASE( void )
+  FT_Logging_Callback( const char*  fmt,
+                       ... );
+
 #endif /* FT_LOGGING */
 
 
diff --git a/src/base/ftdebug.c b/src/base/ftdebug.c
index f8d5f03..42a5ae0 100644
--- a/src/base/ftdebug.c
+++ b/src/base/ftdebug.c
@@ -82,7 +82,10 @@
   static FT_Bool      ft_have_newline_char   = TRUE;
   static const char*  ft_custom_trace_level  = NULL;
 
-  dlg_handler  ft_default_log_handler = NULL;
+  /* declared in ftdebug.h */
+
+  dlg_handler            ft_default_log_handler = NULL;
+  FT_Custom_Log_Handler  custom_output_handler  = NULL;
 
 #endif /* FT_LOGGING*/
 
@@ -441,7 +444,7 @@
   }
 
 
-  /*************************************************************************
+  /**************************************************************************
    *
    * An output log handler for FreeType.
    *
@@ -518,6 +521,44 @@
     ft_debug_init();
   }
 
+
+  /**************************************************************************
+   *
+   * Functions to handle a custom log handler.
+   *
+   */
+
+  /* documentation is in ftlogging.h */
+
+  FT_EXPORT_DEF( void )
+  FT_Set_Log_Handler( FT_Custom_Log_Handler  handler )
+  {
+    custom_output_handler = handler;
+  }
+
+
+  /* documentation is in ftlogging.h */
+
+  FT_EXPORT_DEF( void )
+  FT_Set_Default_Log_Handler()
+  {
+    custom_output_handler = NULL;
+  }
+
+
+  /* documentation is in ftdebug.h */
+  FT_BASE_DEF( void )
+  FT_Logging_Callback( const char*  fmt,
+                       ... )
+  {
+    va_list  ap;
+
+
+    va_start( ap, fmt );
+    custom_output_handler( ft_component, fmt, ap );
+    va_end( ap );
+  }
+
 #endif /* FT_LOGGING */