PServiceProcess Class Referenceabstract

A process type that runs as a "background" service. More...

`#include <svcproc.h>`

Inheritance diagram for PServiceProcess:

## Public Member Functions

virtual int | InternalMain (void *arg=NULL)
| Main function for process, called from real main after initialisation. More...
| ~PServiceProcess ()
virtual void | Terminate ()
| Terminate the process. More...
Construction
| PServiceProcess (const char *manuf, const char *name, WORD majorVersion, WORD minorVersion, CodeStatus status, WORD buildNumber)
| Create a new service process. More...
Callback functions
virtual PBoolean | OnStart ()=0
| Called when the service is started. More...
virtual void | OnStop ()
| Called by the system when the service is stopped. More...
virtual PBoolean | OnPause ()
| Called by the system when the service is to be paused. More...
virtual void | OnContinue ()
| Resume after the service was paused. More...
virtual void | OnControl ()=0
| The Control menu option was used in the SysTray menu. More...
Public Member Functions inherited from PProcess
PTimerList * | GetTimerList ()
| Get the list of timers handled by the application. More...
void | PreInitialise (int argc, char **argv, char **envp)
| Internal initialisation function called directly from `InternalMain()`. More...
| ~PProcess ()
PDirectory | PXGetHomeDir ()
void | PXCheckSignals ()
void | PXAbortIOBlock (int fd)
Comparison | Compare (const PObject &obj) const
| Compare two process instances. More...
virtual PString | GetThreadName () const
| Get the name of the thread. More...
virtual void | SetThreadName (const PString &name)
| Change the name of the thread. More...
| PProcess (const char *manuf="", const char *name="", WORD majorVersion=1, WORD minorVersion=0, CodeStatus status=ReleaseCode, WORD buildNumber=1, bool library=false)
| Create a new process instance. More...
virtual void | OnThreadStart (PThread &thread)
| Callback for when a thread is started by the PTLib system. More...
virtual void | OnThreadEnded (PThread &thread)
| Callback for when a thread is ended if wqas started in the PTLib system. More...
virtual bool | OnInterrupt (bool terminating)
| Callback for when a ^C (SIGINT) or termination request (SIGTERM) is received by process. More...
void | SetTerminationValue (int value)
| Set the termination value for the process. More...
int | GetTerminationValue () const
| Get the termination value for the process. More...
PArgList & | GetArguments ()
| Get the programme arguments. More...
virtual const PString & | GetManufacturer () const
| Get the name of the manufacturer of the software. More...
virtual const PString & | GetName () const
| Get the name of the process. More...
virtual PString | GetVersion (PBoolean full=true) const
| Get the version of the software. More...
const PFilePath & | GetFile () const
| Get the processes executable image file path. More...
PProcessIdentifier | GetProcessID () const
| Get the platform dependent process identifier for the process. More...
PTime | GetStartTime () const
| Return the time at which the program was started. More...
PString | GetUserName () const
| Get the effective user name of the owner of the process, eg "root" etc. More...
PBoolean | SetUserName (const PString &username, PBoolean permanent=false)
| Set the effective owner of the process. More...
PString | GetGroupName () const
| Get the effective group name of the owner of the process, eg "root" etc. More...
PBoolean | SetGroupName (const PString &groupname, PBoolean permanent=false)
| Set the effective group of the process. More...
int | GetMaxHandles () const
| Get the maximum file handle value for the process. More...
PBoolean | SetMaxHandles (int newLimit)
| Set the maximum number of file handles for the process. More...
virtual PString | GetConfigurationFile ()
| Get the default file to use in PConfig instances. More...
void | SetConfigurationPath (const PString &path)
| Set the default file or set of directories to search for use in PConfig. More...
Public Member Functions inherited from PThread
bool | IsAutoDelete () const
int | PXBlockOnChildTerminate (int pid, const PTimeInterval &timeout)
int | PXBlockOnIO (int handle, int type, const PTimeInterval &timeout)
void | PXAbortBlock () const
void | PrintOn (ostream &strm) const
| Standard stream print function. More...
| PThread (PINDEX, AutoDeleteFlag deletion=AutoDeleteThread, Priority priorityLevel=NormalPriority, const PString &threadName=PString::Empty())
| Create a new thread instance. More...
| ~PThread ()
| Destroy the thread, this simply calls the `Terminate()` function with all its restrictions and penalties. More...
virtual void | Restart ()
| Restart a terminated thread using the same stack priority etc that was current when the thread terminated. More...
virtual PBoolean | IsTerminated () const
| Determine if the thread has been terminated or ran to completion. More...
void | WaitForTermination () const
| Block and wait for the thread to terminate. More...
PBoolean | WaitForTermination (const PTimeInterval &maxWait) const
| Block and wait for the thread to terminate. More...
virtual void | Suspend (PBoolean susp=true)
| Suspend or resume the thread. More...
virtual void | Resume ()
| Resume thread execution, this is identical to `Suspend(false)`. More...
virtual PBoolean | IsSuspended () const
| Determine if the thread is currently suspended. More...
virtual void | SetPriority (Priority priorityLevel)
| Set the priority of the thread relative to other threads in the current process. More...
virtual Priority | GetPriority () const
| Get the current priority of the thread in the current process. More...
virtual void | SetAutoDelete (AutoDeleteFlag deletion=AutoDeleteThread)
| Set the flag indicating thread object is to be automatically deleted when the thread ends. More...
void | SetNoAutoDelete ()
| Reet the flag indicating thread object is to be automatically deleted when the thread ends. More...
virtual PThreadIdentifier | GetThreadId () const
| Get operating system specific thread identifier for this thread. More...
bool | GetTimes (Times &times)
| Get the thread execution times. More...
virtual void | Main ()=0
| User override function for the main execution routine of the thread. More...
Public Member Functions inherited from PObject
virtual | ~PObject ()
virtual PObject * | Clone () const
| Create a copy of the class on the heap. More...
virtual PINDEX | HashFunction () const
| This function yields a hash value required by the `PDictionary` class. More...
virtual const char * | GetClass (unsigned ancestor=0) const
| Get the current dynamic type of the object instance. More...
PBoolean | IsClass (const char *cls) const
virtual PBoolean | InternalIsDescendant (const char *clsName) const
| Determine if the dynamic type of the current instance is a descendent of the specified class. More...
virtual Comparison | CompareObjectMemoryDirect (const PObject &obj) const
| Determine the byte wise comparison of two objects. More...
bool | operator== (const PObject &obj) const
| Compare the two objects. More...
bool | operator!= (const PObject &obj) const
| Compare the two objects. More...
bool | operator< (const PObject &obj) const
| Compare the two objects. More...
bool | operator> (const PObject &obj) const
| Compare the two objects. More...
bool | operator<= (const PObject &obj) const
| Compare the two objects. More...
bool | operator>= (const PObject &obj) const
| Compare the two objects. More...
virtual void | ReadFrom (istream &strm)
| Input the contents of the object from the stream. More...

## Protected Member Functions

int | InitialiseService ()
void | _PXShowSystemWarning (PINDEX num, const PString &str)
void | PXOnSignal (int)
void | PXOnAsyncSignal (int)
Protected Member Functions inherited from PProcess
void | Construct ()
| PDICTIONARY (PXFdDict, POrdinalKey, PThread)
void | CommonConstruct ()
void | CommonDestruct ()
void | CreateConfigFilesDictionary ()
Protected Member Functions inherited from PObject
| PObject ()
| Constructor for PObject, made protected so cannot ever create one on its own. More...

## Protected Attributes

PBoolean | debugMode
| Flag to indicate service is run in simulation mode. More...
PString | pidFileToRemove
PBoolean | isTerminating
Protected Attributes inherited from PProcess
bool | m_library
int | terminationValue
PString | manufacturer
PString | productName
WORD | majorVersion
WORD | minorVersion
CodeStatus | status
WORD | buildNumber
PFilePath | executableFile
PStringArray | configurationPaths
PArgList | arguments
int | maxHandles
PTime | programStartTime
bool | m_shuttingDown
ThreadMap | m_activeThreads
PMutex | m_activeThreadMutex
PTimerList | timers
PProcessIdentifier | m_processID
int | pxSignals
PAbstractDictionary * | configFiles
PXFdDict | ioBlocks [3]
Protected Attributes inherited from PThread
bool | m_isProcess
bool | m_autoDelete
PINDEX | m_originalStackSize
PString | m_threadName
PMutex | m_threadNameMutex
PThreadIdentifier | m_threadId

## Miscellaneous functions

void | SetLogLevel (PSystemLog::Level level)
| Set the level at which errors are logged. More...
PSystemLog::Level | GetLogLevel () const
| Get the current level for logging. More...
static PServiceProcess & | Current ()
| Get the current service process object. More...

## Additional Inherited Members

Public Types inherited from PProcess
enum | CodeStatus { AlphaCode, BetaCode, ReleaseCode, NumCodeStatuses }
| Release status for the program. More...
Public Types inherited from PThread
enum | Priority { LowestPriority, LowPriority, NormalPriority, HighPriority, HighestPriority, NumPriorities }
| Codes for thread priorities. More...
enum | AutoDeleteFlag { AutoDeleteThread, NoAutoDeleteThread }
| Codes for thread autodelete flag. More...
Public Types inherited from PObject
enum | Comparison { LessThan = -1, EqualTo = 0, GreaterThan = 1 }
| Result of the comparison operation performed by the `Compare()` function. More...
Static Public Member Functions inherited from PProcess
static void | PreShutdown ()
| Internal shutdown function called directly from the ~PProcess `InternalMain()`. More...
static void | PostShutdown ()
static void | PXShowSystemWarning (PINDEX code)
static void | PXShowSystemWarning (PINDEX code, const PString &str)
static PString | GetOSClass ()
| Get the class of the operating system the process is running on, eg "unix". More...
static PString | GetOSName ()
| Get the name of the operating system the process is running on, eg "Linux". More...
static PString | GetOSHardware ()
| Get the hardware the process is running on, eg "sparc". More...
static PString | GetOSVersion ()
| Get the version of the operating system the process is running on, eg "2.0.33". More...
static bool | IsOSVersion (unsigned major, unsigned minor=0, unsigned build=0)
| See if operating system is later than the version specified. More...
static PDirectory | GetOSConfigDir ()
| Get the configuration directory of the operating system the process is running on, eg "/etc" for Unix, "c:\windows" for Win95 or "c:\winnt\system32\drivers\etc" for NT. More...
static PString | GetLibVersion ()
| Get the version of the PTLib library the process is running on, eg "2.5beta3". More...
static PProcess & | Current ()
| Get the current processes object instance. More...
static PBoolean | IsInitialised ()
| Determine if the current processes object instance has been initialised. More...
static PProcessIdentifier | GetCurrentProcessID ()
| Get the platform dependent process identifier for the currentprocess. More...
Static Public Member Functions inherited from PThread
static void | Sleep (const PTimeInterval &delay)
| Suspend the current thread for the specified amount of time. More...
static PThreadIdentifier | GetCurrentThreadId ()
static PThread * | Current ()
| Get the currently running thread object instance. More...
static void | Yield ()
| Yield to another thread without blocking. More...
static PThread * | Create (const PNotifier &notifier, INT parameter=0, AutoDeleteFlag deletion=AutoDeleteThread, Priority priorityLevel=NormalPriority, const PString &threadName=PString::Empty(), PINDEX stackSize=65536)
| Create a simple thread executing the specified notifier. More...
static PThread * | Create (const PNotifier &notifier, const PString &threadName)
Static Public Member Functions inherited from PObject
static const char * | Class ()
| Get the name of the class as a C string. More...
static Comparison | InternalCompareObjectMemoryDirect (const PObject *obj1, const PObject *obj2, PINDEX size)
| Internal function caled from CompareObjectMemoryDirect() More...
Protected Types inherited from PProcess
typedef std::map< PThreadIdentifier, PThread * > | ThreadMap

## Detailed Description

A process type that runs as a "background" service.

This may be a service under the Windows NT operating system, or a "daemon" under Unix, or a hidden application under Windows.

## Constructor & Destructor Documentation

## PServiceProcess()

PServiceProcess::PServiceProcess | ( | const char * | manuf,
|  | const char * | name,
|  | WORD | majorVersion,
|  | WORD | minorVersion,
|  | CodeStatus | status,
|  | WORD | buildNumber
| ) |  |

Create a new service process.

Parameters

  manuf | Name of manufacturer
  name | Name of product
  majorVersion | Major version number of the product
  minorVersion | Minor version number of the product
  status | Development status of the product
  buildNumber | Build number of the product

## ~PServiceProcess()

PServiceProcess::~PServiceProcess | ( |  | ) |

## Member Function Documentation

## _PXShowSystemWarning()

void PServiceProcess::_PXShowSystemWarning | ( | PINDEX | num,
|  | const PString & | str
| ) |  |

protected virtual

Reimplemented from PProcess.

## Current()

static PServiceProcess& PServiceProcess::Current | ( |  | ) |

static

Get the current service process object.

Returns
  Pointer to service process.

## GetLogLevel()

PSystemLog::Level PServiceProcess::GetLogLevel | ( |  | ) | const

inline

Get the current level for logging.

Returns
  Log level.

References PSystemLog::GetTarget(), PSystemLogTarget::GetThresholdLevel(), and InternalMain().

## InitialiseService()

int PServiceProcess::InitialiseService | ( |  | ) |

protected

## InternalMain()

virtual int PServiceProcess::InternalMain | ( | void * | arg = `NULL` | ) |

virtual

Main function for process, called from real main after initialisation.

Reimplemented from PProcess.

Referenced by GetLogLevel().

## OnContinue()

virtual void PServiceProcess::OnContinue | ( |  | ) |

virtual

Resume after the service was paused.

Reimplemented in PHTTPServiceProcess.

## OnControl()

virtual void PServiceProcess::OnControl | ( |  | ) |

pure virtual

The Control menu option was used in the SysTray menu.

## OnPause()

virtual PBoolean PServiceProcess::OnPause | ( |  | ) |

virtual

Called by the system when the service is to be paused.

This will suspend any actions that the service may be executing. Usually this is less expensive in resource allocation etc than stopping and starting the service.

Returns
  true if the service was successfully paused.

Reimplemented in PHTTPServiceProcess.

## OnStart()

virtual PBoolean PServiceProcess::OnStart | ( |  | ) |

pure virtual

Called when the service is started.

This typically initialises the service and returns true if the service is ready to run. The `Main()` function is then executed.

Returns
  true if service may start, false if an initialisation failure occurred.

Implemented in PHTTPServiceProcess.

## OnStop()

virtual void PServiceProcess::OnStop | ( |  | ) |

virtual

Called by the system when the service is stopped.

One return from this function there is no guarentee that any more user code will be executed. Any cleaning up or closing of resource must be done in here.

Reimplemented in PHTTPServiceProcess.

## PXOnAsyncSignal()

void PServiceProcess::PXOnAsyncSignal | ( | int |  | ) |

protected virtual

Reimplemented from PProcess.

## PXOnSignal()

void PServiceProcess::PXOnSignal | ( | int |  | ) |

protected virtual

Reimplemented from PProcess.

## SetLogLevel()

void PServiceProcess::SetLogLevel | ( | PSystemLog::Level | level | ) |

inline

Set the level at which errors are logged.

Only messages higher than or equal to the specified level will be logged.

The default is PSystemLog::Error allowing fatal errors and ordinary\ errors to be logged and warning and information to be ignored.

If in debug mode then the default is PSystemLog::Info allowing all messages to be displayed.

Parameters

  level | New log level

References PSystemLog::GetTarget(), and PSystemLogTarget::SetThresholdLevel().

## Terminate()

virtual void PServiceProcess::Terminate | ( |  | ) |

virtual

Terminate the process.

Usually only used in abnormal abort situation.

Reimplemented from PProcess.

## Member Data Documentation

## debugMode

PBoolean PServiceProcess::debugMode

protected

Flag to indicate service is run in simulation mode.

## isTerminating

PBoolean PServiceProcess::isTerminating

protected

## pidFileToRemove

PString PServiceProcess::pidFileToRemove

protected

The documentation for this class was generated from the following file:

- svcproc.h