include/ptlib/svcproc.h

   1 /*
   2  * svcproc.h
   3  *
   4  * Service Process (daemon) class.
   5  *
   6  * Portable Windows Library
   7  *
   8  * Copyright (c) 1993-1998 Equivalence Pty. Ltd.
   9  *
  10  * The contents of this file are subject to the Mozilla Public License
  11  * Version 1.0 (the "License"); you may not use this file except in
  12  * compliance with the License. You may obtain a copy of the License at
  13  * http://www.mozilla.org/MPL/
  14  *
  15  * Software distributed under the License is distributed on an "AS IS"
  16  * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
  17  * the License for the specific language governing rights and limitations
  18  * under the License.
  19  *
  20  * The Original Code is Portable Windows Library.
  21  *
  22  * The Initial Developer of the Original Code is Equivalence Pty. Ltd.
  23  *
  24  * Portions are Copyright (C) 1993 Free Software Foundation, Inc.
  25  * All Rights Reserved.
  26  *
  27  * Contributor(s): ______________________________________.
  28  *
  29  * $Log$
  30  * Revision 1.24  2003/09/17 05:41:59  csoutheren
  31  * Removed recursive includes
  32  *
  33  * Revision 1.23  2003/09/17 01:18:02  csoutheren
  34  * Removed recursive include file system and removed all references
  35  * to deprecated coooperative threading support
  36  *
  37  * Revision 1.22  2002/10/22 07:42:52  robertj
  38  * Added extra debugging for file handle and thread leak detection.
  39  *
  40  * Revision 1.21  2002/09/16 01:08:59  robertj
  41  * Added #define so can select if #pragma interface/implementation is used on
  42  *   platform basis (eg MacOS) rather than compiler, thanks Robert Monaghan.
  43  *
  44  * Revision 1.20  2002/01/26 23:55:55  craigs
  45  * Changed for GCC 3.0 compatibility, thanks to manty@manty.net
  46  *
  47  * Revision 1.19  2001/05/22 12:49:32  robertj
  48  * Did some seriously wierd rewrite of platform headers to eliminate the
  49  *   stupid GNU compiler warning about braces not matching.
  50  *
  51  * Revision 1.18  1999/09/21 08:20:16  robertj
  52  * Fixed name space problem with PSYSTEMLOG() macro.
  53  *
  54  * Revision 1.17  1999/09/13 13:15:06  robertj
  55  * Changed PTRACE so will output to system log in PServiceProcess applications.
  56  *
  57  * Revision 1.16  1999/03/09 02:59:51  robertj
  58  * Changed comments to doc++ compatible documentation.
  59  *
  60  * Revision 1.15  1999/02/16 08:11:17  robertj
  61  * MSVC 6.0 compatibility changes.
  62  *
  63  * Revision 1.14  1998/10/13 14:06:15  robertj
  64  * Complete rewrite of memory leak detection code.
  65  *
  66  * Revision 1.13  1998/09/23 06:21:31  robertj
  67  * Added open source copyright license.
  68  *
  69  * Revision 1.12  1998/04/07 13:33:21  robertj
  70  * Changed startup code to support PApplication class.
  71  *
  72  * Revision 1.11  1998/03/29 06:16:50  robertj
  73  * Rearranged initialisation sequence so PProcess descendent constructors can do "things".
  74  *
  75  * Revision 1.10  1998/02/16 00:13:16  robertj
  76  * Added tray icon support.
  77  *
  78  * Revision 1.9  1998/02/03 06:19:14  robertj
  79  * Added extra log levels.
  80  *
  81  * Revision 1.8  1997/07/08 13:02:32  robertj
  82  * DLL support.
  83  *
  84  * Revision 1.7  1997/02/05 11:51:15  robertj
  85  * Changed current process function to return reference and validate objects descendancy.
  86  *
  87  * Revision 1.6  1996/08/19 13:39:20  robertj
  88  * Added "Debug" level to system log.
  89  * Moved PSYSTEMLOG macro to common code.
  90  * Changed PSYSTEMLOG macro so does not execute << expression if below debug level.
  91  * Fixed memory leak in PSystemLog stream buffer.
  92  *
  93  * Revision 1.5  1996/08/17 10:00:27  robertj
  94  * Changes for Windows DLL support.
  95  *
  96  * Revision 1.4  1996/08/09 11:16:53  robertj
  97  * Moved log macro to platform dependent header.
  98  *
  99  * Revision 1.3  1996/07/30 12:24:13  robertj
 100  * Added SYSTEMLOG macro for GNU compiler compatibility.
 101  *
 102  * Revision 1.2  1996/07/27 04:10:06  robertj
 103  * Changed SystemLog to be stream based rather than printf based.
 104  *
 105  * Revision 1.1  1995/12/23 03:47:25  robertj
 106  * Initial revision
 107  *
 108  * Revision 1.3  1995/12/10 11:50:05  robertj
 109  * Numerous fixes for WIN32 service processes.
 110  *
 111  * Revision 1.2  1995/07/02 01:23:27  robertj
 112  * Set up service process to be in subthread not main thread.
 113  *
 114  * Revision 1.1  1995/06/17 00:50:54  robertj
 115  * Initial revision
 116  *
 117  */
 118
 119 #ifndef _PSERVICEPROCESS
 120 #define _PSERVICEPROCESS
 121
 122 #ifdef P_USE_PRAGMA
 123 #pragma interface
 124 #endif
 125
 126 /** This class abstracts the operating system dependent error logging facility.
 127 To send messages to the system error log, the PSYSTEMLOG macro should be used.
 128   */
 129
 130 class PSystemLog : public PObject, public iostream {
 131   PCLASSINFO(PSystemLog, PObject);
 132
 133   public:
 134   /**@name Construction */
 135   //@{
 136     /// define the different error log levels
 137     enum Level {
 138       /// Log from standard error stream
 139       StdError = -1,
 140       /// Log a fatal error
 141       Fatal,
 142       /// Log a non-fatal error
 143       Error,
 144       /// Log a warning
 145       Warning,
 146       /// Log general information
 147       Info,
 148       /// Log debugging information
 149       Debug,
 150       /// Log more debugging information
 151       Debug2,
 152       /// Log even more debugging information
 153       Debug3,
 154       /// Log a lot of debugging information
 155       Debug4,
 156       /// Log a real lot of debugging information
 157       Debug5,
 158       /// Log a bucket load of debugging information
 159       Debug6,
 160
 161       NumLogLevels
 162     };
 163
 164     /// Create a system log stream
 165     PSystemLog(
 166      Level level   /// only messages at this level or higher will be logged
 167     ) : iostream(cout.rdbuf()) { logLevel = level; buffer.log = this; init(&buffer); }
 168
 169     /// Destroy the string stream, deleting the stream buffer
 170     ~PSystemLog() { flush(); }
 171   //@}
 172
 173   /**@name Output functions */
 174   //@{
 175     /** Log an error into the system log.
 176      */
 177     static void Output(
 178       Level level,      /// Log level for this log message.
 179       const char * msg  /// Message to be logged
 180     );
 181   //@}
 182
 183   /**@name Miscellaneous functions */
 184   //@{
 185     /** Set the level at which errors are logged. Only messages higher than or
 186        equal to the specified level will be logged.
 187       */
 188     void SetLevel(
 189       Level level  /// New log level
 190     ) { logLevel = level; }
 191
 192     /** Get the current level for logging.
 193
 194        @return
 195        Log level.
 196      */
 197     Level GetLevel() const { return logLevel; }
 198   //@}
 199
 200   private:
 201     PSystemLog(const PSystemLog &) : iostream(cout.rdbuf()) { }
 202     PSystemLog & operator=(const PSystemLog &) { return *this; }
 203
 204     class Buffer : public streambuf {
 205       public:
 206         virtual int overflow(int=EOF);
 207         virtual int underflow();
 208         virtual int sync();
 209         PSystemLog * log;
 210         PString string;
 211     } buffer;
 212     friend class Buffer;
 213
 214     Level logLevel;
 215 };
 216
 217
 218 /** Log a message to the system log.
 219 The current log level is checked and if allowed, the second argument is evaluated
 220 as a stream output sequence which is them output to the system log.
 221 */
 222 #define PSYSTEMLOG(level, variables) \
 223   if (PServiceProcess::Current().GetLogLevel() >= PSystemLog::level) { \
 224     PSystemLog P_systemlog(PSystemLog::level); \
 225     P_systemlog << variables; \
 226   } else (void)0
 227
 228
 229
 230 /** A process type that runs as a "background" service.
 231     This may be a service under the Windows NT operating system, or a "daemon" under Unix, or a hidden application under Windows.
 232  */
 233 class PServiceProcess : public PProcess
 234 {
 235   PCLASSINFO(PServiceProcess, PProcess);
 236
 237   public:
 238   /**@name Construction */
 239   //@{
 240     /** Create a new service process.
 241      */
 242     PServiceProcess(
 243       const char * manuf,   /// Name of manufacturer
 244       const char * name,    /// Name of product
 245       WORD majorVersion,    /// Major version number of the product
 246       WORD minorVersion,    /// Minor version number of the product
 247       CodeStatus status,    /// Development status of the product
 248       WORD buildNumber      /// Build number of the product
 249     );
 250   //@}
 251
 252   /**@name Callback functions */
 253   //@{
 254     /** Called when the service is started. This typically initialises the
 255        service and returns TRUE if the service is ready to run. The
 256        #Main()# function is then executed.
 257
 258        @return
 259        TRUE if service may start, FALSE if an initialisation failure occurred.
 260      */
 261     virtual BOOL OnStart() = 0;
 262
 263     /** Called by the system when the service is stopped. One return from this
 264        function there is no guarentee that any more user code will be executed.
 265        Any cleaning up or closing of resource must be done in here.
 266      */
 267     virtual void OnStop();
 268
 269     /** Called by the system when the service is to be paused. This will
 270        suspend any actions that the service may be executing. Usually this is
 271        less expensive in resource allocation etc than stopping and starting
 272        the service.
 273
 274        @return
 275        TRUE if the service was successfully paused.
 276      */
 277     virtual BOOL OnPause();
 278
 279     /** Resume after the service was paused.
 280      */
 281     virtual void OnContinue();
 282
 283     /** The Control menu option was used in the SysTray menu.
 284      */
 285     virtual void OnControl() = 0;
 286   //@}
 287
 288   /**@name Miscellaneous functions */
 289   //@{
 290     /** Get the current service process object.
 291
 292        @return
 293        Pointer to service process.
 294      */
 295     static PServiceProcess & Current();
 296
 297
 298     /** Set the level at which errors are logged. Only messages higher than or
 299        equal to the specified level will be logged.
 300
 301        The default is #LogError# allowing fatal errors and ordinary\
 302        errors to be logged and warning and information to be ignored.
 303
 304        If in debug mode then the default is #LogInfo# allowing all
 305        messages to be displayed.
 306      */
 307     void SetLogLevel(
 308       PSystemLog::Level level  /// New log level
 309     ) { currentLogLevel = level; }
 310
 311     /** Get the current level for logging.
 312
 313        @return
 314        Log level.
 315      */
 316     PSystemLog::Level GetLogLevel() const { return currentLogLevel; }
 317   //@}
 318
 319
 320     /* Internal initialisation function called directly from
 321        #main()#. The user should never call this function.
 322      */
 323     virtual int _main(void * arg = NULL);
 324
 325
 326   protected:
 327   // Member variables
 328     /// Flag to indicate service is run in simulation mode.
 329     BOOL debugMode;
 330
 331     /// Current log level for #PSYSTEMLOG# calls.
 332     PSystemLog::Level currentLogLevel;
 333
 334     friend void PSystemLog::Output(PSystemLog::Level, const char *);
 335
 336
 337 // Include platform dependent part of class
 338 #ifdef _WIN32
 339 #include "msos/ptlib/svcproc.h"
 340 #else
 341 #include "unix/ptlib/svcproc.h"
 342 #endif
 343 };
 344
 345 #endif
 346
 347
 348 // End Of File ///////////////////////////////////////////////////////////////