PProcess Class Reference

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

#include <pprocess.h>

Inheritance diagram for PProcess:


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.
PArgList &	GetArguments ()
	Get the programme arguments.
virtual const PString &	GetManufacturer () const
	Get the name of the manufacturer of the software.
virtual const PString &	GetName () const
	Get the name of the process.
virtual PString	GetVersion (PBoolean full=true) const
	Get the version of the software.
const PFilePath &	GetFile () 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 PProcess &	Current ()
	Get the current processes object instance.
static PBoolean	IsInitialised ()
	Determine if the current processes object instance has been initialised.
Public Member Functions
PTimerList *	GetTimerList ()
	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
PAbstractDictionary *	configFiles
PXFdDict	ioBlocks [3]
Friends
void	PXSignalHandler (int)
PString	PX_GetThreadName (pthread_t id)
void	PXSigHandler (int)
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...

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

enum PProcess::CodeStatus

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:

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
library	PProcess is a library rather than an application

PProcess::~PProcess ( )

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:

obj

Other process to compare against.

Reimplemented from PObject.

void PProcess::Construct ( ) [protected]

void PProcess::CreateConfigFilesDictionary ( ) [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 PServiceProcess, and PHTTPServiceProcess.

PArgList& PProcess::GetArguments ( )

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.

PString PProcess::GetGroupName ( ) const

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.

PTime PProcess::GetStartTime ( ) const

Return the time at which the program was started.

int PProcess::GetTerminationValue ( ) const

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.

PTimerList* PProcess::GetTimerList ( )

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.

PString PProcess::GetUserName ( ) const

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:

full

true 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:

major	Major version number
minor	Minor version number
build	Build 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:

terminating

true 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 )

void PProcess::PXCheckSignals ( )

PDirectory PProcess::PXGetHomeDir ( )

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

Reimplemented in PServiceProcess.

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

Reimplemented in PServiceProcess.

static void PProcess::PXShowSystemWarning	(	PINDEX	code,
		const PString &	str
	)			`[static]`

static void PProcess::PXShowSystemWarning ( PINDEX code ) [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:

path

Explicit 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:

groupname	New group name or gid
permanent	Flag 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:

newLimit

New 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:

value

Value 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:

name

New 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: