include/pnd_logger.h

   1
   2 #ifndef h_pnd_logger_h
   3 #define h_pnd_logger_h
   4
   5 #ifdef __cplusplus
   6 extern "C" {
   7 #endif
   8
   9 #include <stdio.h>
  10
  11 /* rudimentary logger; note that this is meant to be a no-brainer to use, so no setup is needed.
  12  */
  13 #define PND_LOG_FORCE (0xFF) /* use this log level to require it be emitted, no skipping */
  14
  15 // defaults will have no filtering, so any message will be emitted to all targets
  16 // default target is nothing, however, so logger is silent unless activated
  17 unsigned char pnd_log ( unsigned char level, char *format, ... );           // returns true if emitted; \n is implied!
  18 unsigned char pnd_log_to_stdout ( void );                                   // same as pnd_log_to_stream ( stdout );
  19 unsigned char pnd_log_to_stderr ( void );                                   // same as pnd_log_to_stream ( stderr );
  20
  21 /* the below is all optional, for when you need more control
  22  */
  23
  24 // logging is additive; you can log to multiple targets at once. Returns 'true' if accepted, false if could not set up.
  25 void pnd_log_to_nil ( void );                                               // stop logging to anywhere; does not close streams/etc
  26 unsigned char pnd_log_to_stream ( FILE * );                                 // 'stdout', 'stderr', or your own FILE* are good values
  27 unsigned char pnd_log_to_syslog ( char *facility );                         // NYI
  28 typedef void (*pnd_log_callback_f)( char *text, void *userdata );
  29 unsigned char pnd_log_to_callback ( pnd_log_callback_f f, void *userdata ); // NYI
  30
  31 // pass NULL to free any pre-text, otherwise it'll be kept. Passed in string is duplicated, so you may free yours if you like.
  32 void pnd_log_set_pretext ( char * );                                        // example: your app-name, or app+function-names, say.
  33 // after a write, do a flush; may only apply to streams, but will attempt to apply to all
  34 void pnd_log_set_flush ( unsigned char x );
  35
  36 // set a 'filter level'; any log message of higher-or-equal level than current filter-level will be emitted. Thus, to remove filters
  37 // just set to level 0. Returns existing setting.
  38 unsigned char pnd_log_set_filter ( unsigned char newlevel );                // ex: app-specific enum/#defines for your levels
  39 unsigned char pnd_log_get_filter ( void );
  40
  41 // how many targets can be opened, entirely? this is a compile time limit, for sanity.
  42 unsigned char pnd_log_max_targets ( void );
  43
  44 // tell buried lib functions to do some logging here; ie: since not all API's have a 'options' type flag where we could
  45 // add a hint to begin logging, they can just ask the logger if they need to do it
  46 #define PND_LOG_DEFAULT 0 // level 0 is by default the 'debug' level, with anything higher non-debug; only used for buried logging
  47 void pnd_log_set_buried_logging ( unsigned char yesno ); // set 1 for 'yes', 0 for 'no'
  48 unsigned char pnd_log_do_buried_logging ( void ); // return 1 for 'yes'
  49
  50 #ifdef __cplusplus
  51 } /* "C" */
  52 #endif
  53
  54 #endif