PTLib  Version 2.10.4
PProcess Class Reference

This class represents an operating system process. More...

#include <pprocess.h>

Inheritance diagram for PProcess:
PThread PObject PLibraryProcess PServiceProcess PHTTPServiceProcess PSecureHTTPServiceProcess

List of all members.

Classes

class  HostSystemURLHandlerInfo
 This class can be used to register various URL types with the host operating system so that URLs will automatically launch the correct application. More...

Public Member Functions

PTimerListGetTimerList ()
 Get the list of timers handled by the application.
void PreInitialise (int argc, char **argv, char **envp)
 Internal initialisation function called directly from InternalMain().
virtual int InternalMain (void *arg=NULL)
 Main function for process, called from real main after initialisation.
 ~PProcess ()
PDirectory PXGetHomeDir ()
virtual void PXOnSignal (int)
virtual void PXOnAsyncSignal (int)
void PXCheckSignals ()
void PXAbortIOBlock (int fd)
Overrides from class PObject
Comparison Compare (const PObject &obj) const
 Compare two process instances.
Overrides from class PThread
virtual void Terminate ()
 Terminate the process.
virtual PString GetThreadName () const
 Get the name of the thread.
virtual void SetThreadName (const PString &name)
 Change the name of the thread.

Static Public Member Functions

static void PreShutdown ()
 Internal shutdown function called directly from the ~PProcess InternalMain().
static void PostShutdown ()
static void PXShowSystemWarning (PINDEX code)
static void PXShowSystemWarning (PINDEX code, const PString &str)
Operating System information functions
static PString GetOSClass ()
 Get the class of the operating system the process is running on, eg "unix".
static PString GetOSName ()
 Get the name of the operating system the process is running on, eg "Linux".
static PString GetOSHardware ()
 Get the hardware the process is running on, eg "sparc".
static PString GetOSVersion ()
 Get the version of the operating system the process is running on, eg "2.0.33".
static bool IsOSVersion (unsigned major, unsigned minor=0, unsigned build=0)
 See if operating system is later than the version specified.
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.
static PString GetLibVersion ()
 Get the version of the PTLib library the process is running on, eg "2.5beta3".

Protected Types

typedef std::map
< PThreadIdentifier, PThread * > 
ThreadMap

Protected Member Functions

void Construct ()
 PDICTIONARY (PXFdDict, POrdinalKey, PThread)
void CommonConstruct ()
void CommonDestruct ()
virtual void _PXShowSystemWarning (PINDEX code, const PString &str)
void CreateConfigFilesDictionary ()

Protected Attributes

int terminationValue
PString manufacturer
PString productName
WORD majorVersion
WORD minorVersion
CodeStatus status
WORD buildNumber
PFilePath executableFile
PStringArray configurationPaths
PArgList arguments
PTimerList timers
PTime programStartTime
int maxHandles
bool m_library
bool m_shuttingDown
ThreadMap m_activeThreads
PMutex m_activeThreadMutex
int pxSignals
PAbstractDictionaryconfigFiles
PXFdDict ioBlocks [3]

Friends

void PXSignalHandler (int)
PString PX_GetThreadName (pthread_t id)
void PXSigHandler (int)

Construction

enum  CodeStatus { AlphaCode, BetaCode, ReleaseCode, NumCodeStatuses }
 Release status for the program. 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.

Process information functions

virtual void OnThreadStart (PThread &thread)
 Callback for when a thread is started by the PTLib system.
virtual void OnThreadEnded (PThread &thread)
 Callback for when a thread is ended if wqas started in the PTLib system.
virtual bool OnInterrupt (bool terminating)
 Callback for when a ^C (SIGINT) or termination request (SIGTERM) is received by process.
void SetTerminationValue (int value)
 Set the termination value for the process.
int GetTerminationValue () const
 Get the termination value for the process.
PArgListGetArguments ()
 Get the programme arguments.
virtual const PStringGetManufacturer () const
 Get the name of the manufacturer of the software.
virtual const PStringGetName () const
 Get the name of the process.
virtual PString GetVersion (PBoolean full=true) const
 Get the version of the software.
const PFilePathGetFile () const
 Get the processes executable image file path.
DWORD GetProcessID () const
 Get the platform dependent process identifier for the process.
PTime GetStartTime () const
 Return the time at which the program was started.
PString GetUserName () const
 Get the effective user name of the owner of the process, eg "root" etc.
PBoolean SetUserName (const PString &username, PBoolean permanent=false)
 Set the effective owner of the process.
PString GetGroupName () const
 Get the effective group name of the owner of the process, eg "root" etc.
PBoolean SetGroupName (const PString &groupname, PBoolean permanent=false)
 Set the effective group of the process.
int GetMaxHandles () const
 Get the maximum file handle value for the process.
PBoolean SetMaxHandles (int newLimit)
 Set the maximum number of file handles for the process.
virtual PString GetConfigurationFile ()
 Get the default file to use in PConfig instances.
void SetConfigurationPath (const PString &path)
 Set the default file or set of directories to search for use in PConfig.
static PProcessCurrent ()
 Get the current processes object instance.
static PBoolean IsInitialised ()
 Determine if the current processes object instance has been initialised.

Detailed Description

This class represents an operating system process.

This is a running "programme" in the context of the operating system. Note that there can only be one instance of a PProcess class in a given programme.

The instance of a PProcess or its GUI descendent PApplication is usually a static variable created by the application writer. This is the initial "anchor" point for all data structures in an application. As the application writer never needs to access the standard system main() function, it is in the library, the programmes execution begins with the virtual function PThread::Main() on a process.


Member Typedef Documentation

typedef std::map<PThreadIdentifier, PThread *> PProcess::ThreadMap [protected]

Member Enumeration Documentation

Release status for the program.

Enumerator:
AlphaCode 

Code is still very much under construction.

BetaCode 

Code is largely complete and is under test.

ReleaseCode 

Code has all known bugs removed and is shipping.

NumCodeStatuses 

Constructor & Destructor Documentation

PProcess::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.

Parameters:
manufName of manufacturer
nameName of product
majorVersionMajor version number of the product
minorVersionMinor version number of the product
statusDevelopment status of the product
buildNumberBuild number of the product
libraryPProcess is a library rather than an application

Member Function Documentation

virtual void PProcess::_PXShowSystemWarning ( PINDEX  code,
const PString str 
) [protected, virtual]

Reimplemented in PServiceProcess.

void PProcess::CommonConstruct ( ) [protected]
void PProcess::CommonDestruct ( ) [protected]
Comparison PProcess::Compare ( const PObject obj) const [virtual]

Compare two process instances.

This should almost never be called as a programme only has access to a single process, its own.

Returns:
EqualTo if the two process object have the same name.
Parameters:
objOther process to compare against.

Reimplemented from PObject.

void PProcess::Construct ( ) [protected]
static PProcess& PProcess::Current ( ) [static]

Get the current processes object instance.

The current process is the one the application is running in.

Returns:
pointer to current process instance.

Reimplemented from PThread.

Reimplemented in PHTTPServiceProcess, and PServiceProcess.

Get the programme arguments.

Programme arguments are a set of strings provided to the programme in a platform dependent manner.

Returns:
argument handling class instance.
virtual PString PProcess::GetConfigurationFile ( ) [virtual]

Get the default file to use in PConfig instances.

const PFilePath& PProcess::GetFile ( ) const

Get the processes executable image file path.

Returns:
file path for program.

Get the effective group name of the owner of the process, eg "root" etc.

This is a platform dependent string only provided by platforms that are multi-user. Note that some value may be returned as a "simulated" user. For example, in MS-DOS an environment variable

Returns:
group name of processes owner.
static PString PProcess::GetLibVersion ( ) [static]

Get the version of the PTLib library the process is running on, eg "2.5beta3".

Returns:
String for library version.
virtual const PString& PProcess::GetManufacturer ( ) const [virtual]

Get the name of the manufacturer of the software.

This is used in the default "About" dialog box and for determining the location of the configuration information as used by the PConfig class.

The default for this information is the empty string.

Returns:
string for the manufacturer name eg "Equivalence".
int PProcess::GetMaxHandles ( ) const

Get the maximum file handle value for the process.

For some platforms this is meaningless.

Returns:
user name of processes owner.
virtual const PString& PProcess::GetName ( ) const [virtual]

Get the name of the process.

This is used in the default "About" dialog box and for determining the location of the configuration information as used by the PConfig class.

The default is the title part of the executable image file.

Returns:
string for the process name eg "MyApp".
static PString PProcess::GetOSClass ( ) [static]

Get the class of the operating system the process is running on, eg "unix".

Returns:
String for OS class.
static PDirectory PProcess::GetOSConfigDir ( ) [static]

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.

Returns:
Directory for OS configuration files.
static PString PProcess::GetOSHardware ( ) [static]

Get the hardware the process is running on, eg "sparc".

Returns:
String for OS name.
static PString PProcess::GetOSName ( ) [static]

Get the name of the operating system the process is running on, eg "Linux".

Returns:
String for OS name.
static PString PProcess::GetOSVersion ( ) [static]

Get the version of the operating system the process is running on, eg "2.0.33".

Returns:
String for OS version.
DWORD PProcess::GetProcessID ( ) const

Get the platform dependent process identifier for the process.

This is an arbitrary (and unique) integer attached to a process by the operating system.

Returns:
Process ID for process.

Return the time at which the program was started.

Get the termination value for the process.

The termination value is an operating system dependent integer which indicates the processes termiantion value. It can be considered a "return value" for an entire programme.

Returns:
integer termination value.
virtual PString PProcess::GetThreadName ( ) const [virtual]

Get the name of the thread.

Thread names are a optional debugging aid.

Returns:
current thread name.

Reimplemented from PThread.

Get the list of timers handled by the application.

This is an internal function and should not need to be called by the user.

Returns:
list of timers.

Get the effective user name of the owner of the process, eg "root" etc.

This is a platform dependent string only provided by platforms that are multi-user. Note that some value may be returned as a "simulated" user. For example, in MS-DOS an environment variable

Returns:
user name of processes owner.
virtual PString PProcess::GetVersion ( PBoolean  full = true) const [virtual]

Get the version of the software.

This is used in the default "About" dialog box and for determining the location of the configuration information as used by the PConfig class.

If the full parameter is true then a version string built from the major, minor, status and build veriosn codes is returned. If false then only the major and minor versions are returned.

The default for this information is "1.0".

Returns:
string for the version eg "1.0b3".
Parameters:
fulltrue for full version, false for short version.
virtual int PProcess::InternalMain ( void *  arg = NULL) [virtual]

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

Reimplemented in PServiceProcess.

static PBoolean PProcess::IsInitialised ( ) [static]

Determine if the current processes object instance has been initialised.

If this returns true it is safe to use the PProcess::Current() function.

Returns:
true if process class has been initialised.
static bool PProcess::IsOSVersion ( unsigned  major,
unsigned  minor = 0,
unsigned  build = 0 
) [static]

See if operating system is later than the version specified.

Returns:
true if OS version leter than or equal to parameters.
Parameters:
majorMajor version number
minorMinor version number
buildBuild number
virtual bool PProcess::OnInterrupt ( bool  terminating) [virtual]

Callback for when a ^C (SIGINT) or termination request (SIGTERM) is received by process.

Note this function is called asynchronously and there may be many limitations on what can and cannot be done depending on the underlying operating system. It is recommeneded that this does no more than set flags and return.

Default behaviour returns false and the process is killed.

Returns:
true if the process is to be allowed to continue, false otherwise.
Parameters:
terminatingtrue if process terminating.
virtual void PProcess::OnThreadEnded ( PThread thread) [virtual]

Callback for when a thread is ended if wqas started in the PTLib system.

Note this is called in the context of the old thread.

virtual void PProcess::OnThreadStart ( PThread thread) [virtual]

Callback for when a thread is started by the PTLib system.

Note this is called in the context of the new thread.

PProcess::PDICTIONARY ( PXFdDict  ,
POrdinalKey  ,
PThread   
) [protected]
static void PProcess::PostShutdown ( ) [static]
void PProcess::PreInitialise ( int  argc,
char **  argv,
char **  envp 
)

Internal initialisation function called directly from InternalMain().

The user should never call this function.

static void PProcess::PreShutdown ( ) [static]

Internal shutdown function called directly from the ~PProcess InternalMain().

The user should never call this function.

void PProcess::PXAbortIOBlock ( int  fd)
virtual void PProcess::PXOnAsyncSignal ( int  ) [virtual]

Reimplemented in PServiceProcess.

virtual void PProcess::PXOnSignal ( int  ) [virtual]

Reimplemented in PServiceProcess.

static void PProcess::PXShowSystemWarning ( PINDEX  code) [static]
static void PProcess::PXShowSystemWarning ( PINDEX  code,
const PString str 
) [static]
void PProcess::SetConfigurationPath ( const PString path)

Set the default file or set of directories to search for use in PConfig.

To find the .ini file for use in the default PConfig() instance, this explicit filename is used, or if it is a set of directories separated by either ':' or ';' characters, then the application base name postfixed with ".ini" is searched for through those directories.

The search is actually done when the GetConfigurationFile() is called, this function only sets the internal variable.

Note for Windows, a path beginning with "HKEY_LOCAL_MACHINE\\" or "HKEY_CURRENT_USER\\" will actually search teh system registry for the application base name only (no ".ini") in that folder of the registry.

Parameters:
pathExplicit file or set of directories
PBoolean PProcess::SetGroupName ( const PString groupname,
PBoolean  permanent = false 
)

Set the effective group of the process.

This is a platform dependent string only provided by platforms that are multi-user.

For unix systems if the groupname may consist exclusively of digits and there is no actual groupname consisting of that string then the numeric uid value is used. For example "0" is the superuser. For the rare occassions where the groups name is the same as their uid, if the groupname field starts with a '#' then the numeric form is forced.

If an empty string is provided then original group that executed the process in the first place (the real group) is set as the effective group.

The permanent flag indicates that the group will not be able to simply change back to the original group as indicated above, ie for unix systems setgid() is used instead of setegid(). This is not necessarily meaningful for all platforms.

Returns:
true if processes group changed. The most common reason for failure is that the process does not have the privilege to change the effective group.
Parameters:
groupnameNew group name or gid
permanentFlag for if effective or real group
PBoolean PProcess::SetMaxHandles ( int  newLimit)

Set the maximum number of file handles for the process.

For unix systems the user must be run with the approriate privileges before this function can set the value above the system limit.

For some platforms this is meaningless.

Returns:
true if successfully set the maximum file hadles.
Parameters:
newLimitNew limit on file handles
void PProcess::SetTerminationValue ( int  value)

Set the termination value for the process.

The termination value is an operating system dependent integer which indicates the processes termiantion value. It can be considered a "return value" for an entire programme.

Parameters:
valueValue to return a process termination status.
virtual void PProcess::SetThreadName ( const PString name) [virtual]

Change the name of the thread.

Thread names are a optional debugging aid.

Returns:
current thread name.
Parameters:
nameNew name for the thread.

Reimplemented from PThread.

PBoolean PProcess::SetUserName ( const PString username,
PBoolean  permanent = false 
)

Set the effective owner of the process.

This is a platform dependent string only provided by platforms that are multi-user.

For unix systems if the username may consist exclusively of digits and there is no actual username consisting of that string then the numeric uid value is used. For example "0" is the superuser. For the rare occassions where the users name is the same as their uid, if the username field starts with a '#' then the numeric form is forced.

If an empty string is provided then original user that executed the process in the first place (the real user) is set as the effective user.

The permanent flag indicates that the user will not be able to simple change back to the original user as indicated above, ie for unix systems setuid() is used instead of seteuid(). This is not necessarily meaningful for all platforms.

Returns:
true if processes owner changed. The most common reason for failure is that the process does not have the privilege to change the effective user.
Parameters:
usernameNew user name or uid
permanentFlag for if effective or real user
virtual void PProcess::Terminate ( ) [virtual]

Terminate the process.

Usually only used in abnormal abort situation.

Reimplemented from PThread.

Reimplemented in PServiceProcess.


Friends And Related Function Documentation

PString PX_GetThreadName ( pthread_t  id) [friend]
void PXSigHandler ( int  ) [friend]
void PXSignalHandler ( int  ) [friend]

Member Data Documentation

WORD PProcess::buildNumber [protected]
PXFdDict PProcess::ioBlocks[3] [protected]
bool PProcess::m_library [protected]
bool PProcess::m_shuttingDown [protected]
WORD PProcess::majorVersion [protected]
int PProcess::maxHandles [protected]
WORD PProcess::minorVersion [protected]
int PProcess::pxSignals [protected]
int PProcess::terminationValue [protected]

The documentation for this class was generated from the following files:
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines