home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / nspr30-e.zip / nspr30-e / include / prlog.h < prev    next >
C/C++ Source or Header  |  1998-11-02  |  8KB  |  238 lines
  1. /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
  2. /*
  3.  * The contents of this file are subject to the Netscape Public License
  4.  * Version 1.0 (the "NPL"); you may not use this file except in
  5.  * compliance with the NPL.  You may obtain a copy of the NPL at
  6.  * http://www.mozilla.org/NPL/
  7.  * 
  8.  * Software distributed under the NPL is distributed on an "AS IS" basis,
  9.  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the NPL
  10.  * for the specific language governing rights and limitations under the
  11.  * NPL.
  12.  * 
  13.  * The Initial Developer of this code under the NPL is Netscape
  14.  * Communications Corporation.  Portions created by Netscape are
  15.  * Copyright (C) 1998 Netscape Communications Corporation.  All Rights
  16.  * Reserved.
  17.  */
  18.  
  19. #ifndef prlog_h___
  20. #define prlog_h___
  21.  
  22. #include "prtypes.h"
  23.  
  24. PR_BEGIN_EXTERN_C
  25.  
  26. /*
  27. ** prlog.h -- Declare interfaces to NSPR's Logging service
  28. **
  29. ** NSPR provides a logging service that is used by NSPR itself and is
  30. ** available to client programs.
  31. **
  32. ** To use the service from a client program, you should create a
  33. ** PRLogModuleInfo structure by calling PR_NewLogModule(). After
  34. ** creating the LogModule, you can write to the log using the PR_LOG()
  35. ** macro.
  36. **
  37. ** Initialization of the log service is handled by NSPR initialization.
  38. **
  39. ** At execution time, you must enable the log service. To enable the
  40. ** log service, set the environment variable: NSPR_LOG_MODULES
  41. ** variable.
  42. **
  43. ** NSPR_LOG_MODULES variable has the form:
  44. **
  45. **     <moduleName>:<value>[, <moduleName>:<value>]*
  46. **
  47. ** Where:
  48. **  <moduleName> is the name passed to PR_NewLogModule().
  49. **  <value> is a numeric constant, e.g. 5. This value is the maximum
  50. ** value of a log event, enumerated by PRLogModuleLevel, that you want
  51. ** written to the log.
  52. ** 
  53. ** For example: to record all events of greater value than or equal to
  54. ** PR_LOG_ERROR for a LogModule names "gizmo", say:
  55. ** 
  56. ** set NSPR_LOG_MODULES=gizmo:2
  57. ** 
  58. ** Note that you must specify the numeric value of PR_LOG_ERROR.
  59. ** 
  60. ** Special LogModule names are provided for controlling NSPR's log
  61. ** service at execution time. These controls should be set in the
  62. ** NSPR_LOG_MODULES environment variable at execution time to affect
  63. ** NSPR's log service for your application.
  64. ** 
  65. ** The special LogModule "all" enables all LogModules. To enable all
  66. ** LogModule calls to PR_LOG(), say:
  67. ** 
  68. ** set NSPR_LOG_MODULES=all:5
  69. ** 
  70. ** The special LogModule name "sync" tells the NSPR log service to do
  71. ** unbuffered logging.
  72. ** 
  73. ** The special LogModule name "buffsize:<size>" tells NSPR to set the
  74. ** log buffer to <size>.
  75. **
  76. ** The environment variable NSPR_LOG_FILE specifies the log file to use
  77. ** unless the default of "stderr" is acceptable. For MS Windows
  78. ** systems, NSPR_LOG_FILE can be set to a special value: "WinDebug"
  79. ** (case sensitive). This value causes PR_LOG() output to be written
  80. ** using the Windows API OutputDebugString(). OutputDebugString()
  81. ** writes to the debugger window; some people find this helpful.
  82. ** 
  83. **
  84. ** To put log messages in your programs, use the PR_LOG macro:
  85. **
  86. **     PR_LOG(<module>, <level>, (<printfString>, <args>*));
  87. **
  88. ** Where <module> is the address of a PRLogModuleInfo structure, and
  89. ** <level> is one of the levels defined by the enumeration:
  90. ** PRLogModuleLevel. <args> is a printf() style of argument list. That
  91. ** is: (fmtstring, ...).
  92. **
  93. ** Example:
  94. ** 
  95. ** main() {
  96. **    PRIntn one = 1;
  97. **    PRLogModuleInfo * myLm = PR_NewLogModule("gizmo");
  98. **    PR_LOG( myLm, PR_LOG_ALWAYS, ("Log this! %d\n", one)); 
  99. **    return; 
  100. ** }
  101. ** 
  102. ** Note the use of printf() style arguments as the third agrument(s) to
  103. ** PR_LOG().
  104. ** 
  105. ** After compiling and linking you application, set the environment:
  106. ** 
  107. ** SET NSPR_LOGMODULES=gizmo:5
  108. ** SET NSPR_LOG_FILE=logfile.txt
  109. ** 
  110. ** When you execute your application, the string "Log this! 1" will be
  111. ** written to the file "logfile.txt".
  112. ** 
  113. ** Note to NSPR engineers: a number of PRLogModuleInfo structures are
  114. ** defined and initialized in prinit.c. See this module for ideas on
  115. ** what to log where.
  116. ** 
  117. */
  118.  
  119. typedef enum PRLogModuleLevel {
  120.     PR_LOG_NONE = 0,                /* nothing */
  121.     PR_LOG_ALWAYS = 1,              /* always printed */
  122.     PR_LOG_ERROR = 2,               /* error messages */
  123.     PR_LOG_WARNING = 3,             /* warning messages */
  124.     PR_LOG_DEBUG = 4,               /* debug messages */
  125.  
  126.     PR_LOG_NOTICE = PR_LOG_DEBUG,   /* notice messages */
  127.     PR_LOG_WARN = PR_LOG_WARNING,   /* warning messages */
  128.     PR_LOG_MIN = PR_LOG_DEBUG,      /* minimal debugging messages */
  129.     PR_LOG_MAX = PR_LOG_DEBUG       /* maximal debugging messages */
  130. } PRLogModuleLevel;
  131.  
  132. /*
  133. ** One of these structures is created for each module that uses logging.
  134. **    "name" is the name of the module
  135. **    "level" is the debugging level selected for that module
  136. */
  137. typedef struct PRLogModuleInfo {
  138.     const char *name;
  139.     PRLogModuleLevel level;
  140.     struct PRLogModuleInfo *next;
  141. } PRLogModuleInfo;
  142.  
  143. /*
  144. ** Create a new log module.
  145. */
  146. PR_EXTERN(PRLogModuleInfo*) PR_NewLogModule(const char *name);
  147.  
  148. /*
  149. ** Set the file to use for logging. Returns PR_FALSE if the file cannot
  150. ** be created
  151. */
  152. PR_EXTERN(PRBool) PR_SetLogFile(const char *name);
  153.  
  154. /*
  155. ** Set the size of the logging buffer. If "buffer_size" is zero then the
  156. ** logging becomes "synchronous" (or unbuffered).
  157. */
  158. PR_EXTERN(void) PR_SetLogBuffering(PRIntn buffer_size);
  159.  
  160. /*
  161. ** Print a string to the log. "fmt" is a PR_snprintf format type. All
  162. ** messages printed to the log are preceeded by the name of the thread
  163. ** and a time stamp. Also, the routine provides a missing newline if one
  164. ** is not provided.
  165. */
  166. PR_EXTERN(void) PR_LogPrint(const char *fmt, ...);
  167.  
  168. /*
  169. ** Flush the log to its file.
  170. */
  171. PR_EXTERN(void) PR_LogFlush(void);
  172.  
  173. /*
  174. ** Windoze 16 can't support a large static string space for all of the
  175. ** various debugging strings so logging is not enabled for it.
  176. */
  177. #if (defined(DEBUG) || defined(FORCE_PR_LOG)) && !defined(WIN16)
  178. #define PR_LOGGING 1
  179.  
  180. #define PR_LOG_TEST(_module,_level) \
  181.     ((_module)->level >= (_level))
  182.  
  183. /*
  184. ** Log something.
  185. **    "module" is the address of a PRLogModuleInfo structure
  186. **    "level" is the desired logging level
  187. **    "args" is a variable length list of arguments to print, in the following
  188. **       format:  ("printf style format string", ...)
  189. */
  190. #define PR_LOG(_module,_level,_args)     \
  191.     PR_BEGIN_MACRO             \
  192.       if (PR_LOG_TEST(_module,_level)) { \
  193.       PR_LogPrint _args;         \
  194.       }                     \
  195.     PR_END_MACRO
  196.  
  197. #else /* (defined(DEBUG) || defined(FORCE_PR_LOG)) && !defined(WIN16) */
  198.  
  199. #undef PR_LOGGING
  200. #define PR_LOG_TEST(module,level) 0
  201. #define PR_LOG(module,level,args)
  202.  
  203. #endif /* (defined(DEBUG) || defined(FORCE_PR_LOG)) && !defined(WIN16) */
  204.  
  205. #ifndef NO_NSPR_10_SUPPORT
  206.  
  207. #ifdef PR_LOGGING
  208. #define PR_LOG_BEGIN    PR_LOG
  209. #define PR_LOG_END      PR_LOG
  210. #define PR_LOG_DEFINE   PR_NewLogModule
  211. #else
  212. #define PR_LOG_BEGIN(module,level,args)
  213. #define PR_LOG_END(module,level,args)
  214. #define PR_LOG_DEFINE(_name)    NULL
  215. #endif /* PR_LOGGING */
  216.  
  217. #endif /* NO_NSPR_10_SUPPORT */
  218.  
  219. #if defined(DEBUG)
  220.  
  221. PR_EXTERN(void) PR_Assert(const char *s, const char *file, PRIntn ln);
  222. #define PR_ASSERT(_expr) \
  223.     ((_expr)?((void)0):PR_Assert(# _expr,__FILE__,__LINE__))
  224.  
  225. #define PR_NOT_REACHED(_reasonStr) \
  226.     PR_Assert(_reasonStr,__FILE__,__LINE__)
  227.  
  228. #else
  229.  
  230. #define PR_ASSERT(expr) ((void) 0)
  231. #define PR_NOT_REACHED(reasonStr)
  232.  
  233. #endif /* defined(DEBUG) */
  234.  
  235. PR_END_EXTERN_C
  236.  
  237. #endif /* prlog_h___ */
  238.