PProcess Class Reference

#include <pprocess.h>

Inheritance diagram for PProcess:

PThread PObject PServiceProcess PHTTPServiceProcess PSecureHTTPServiceProcess

List of all members.

Public Member Functions

PTimerListGetTimerList ()
virtual int _main (void *arg=NULL)
PTime GetStartTime () const
 ~PProcess ()
PDirectory PXGetHomeDir ()
char ** PXGetArgv () const
int PXGetArgc () const
char ** PXGetEnvp () const
virtual void PXOnSignal (int)
virtual void PXOnAsyncSignal (int)
void PXCheckSignals ()
void PXAbortIOBlock (int fd)
Overrides from class PObject
Comparison Compare (const PObject &obj) const
Overrides from class PThread
virtual void Terminate ()
virtual PString GetThreadName () const
virtual void SetThreadName (const PString &name)

Static Public Member Functions

static void PreInitialise (int argc, char **argv, char **envp)
static void PreShutdown ()
static void PXShowSystemWarning (PINDEX code)
static void PXShowSystemWarning (PINDEX code, const PString &str)
Operating System information functions
static PString GetOSClass ()
static PString GetOSName ()
static PString GetOSHardware ()
static PString GetOSVersion ()
static PDirectory GetOSConfigDir ()

Protected Member Functions

void CommonConstruct ()
void CommonDestruct ()
virtual void _PXShowSystemWarning (PINDEX code, const PString &str)
void CreateConfigFilesDictionary ()

Protected Attributes

int pxSignals
PAbstractDictionaryconfigFiles
PXFdDict ioBlocks [3]

Friends

class PThread
class PApplication
class PServiceProcess
class PHouseKeepingThread
void PXSignalHandler (int)
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)

Process information functions

void SetTerminationValue (int value)
int GetTerminationValue () const
PArgListGetArguments ()
virtual const PStringGetManufacturer () const
virtual const PStringGetName () const
virtual PString GetVersion (BOOL full=TRUE) const
const PFilePathGetFile () const
DWORD GetProcessID () const
PString GetUserName () const
BOOL SetUserName (const PString &username, BOOL permanent=FALSE)
PString GetGroupName () const
BOOL SetGroupName (const PString &groupname, BOOL permanent=FALSE)
int GetMaxHandles () const
BOOL SetMaxHandles (int newLimit)
void SetConfigurationPath (const PString &path)
static PProcessCurrent ()
static BOOL IsInitialised ()


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

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

PProcess::~PProcess (  ) 


Member Function Documentation

virtual int PProcess::_main ( void *  arg = NULL  )  [virtual]

Reimplemented in PServiceProcess.

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

PINLINE 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.

PINLINE 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.

PINLINE 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".

PINLINE 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.

PINLINE 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

PINLINE 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.

PINLINE PTimerList * PProcess::GetTimerList (  ) 

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 ( BOOL  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.

static BOOL 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 void PProcess::PreInitialise ( int  argc,
char **  argv,
char **  envp 
) [static]

static void PProcess::PreShutdown (  )  [static]

void PProcess::PXAbortIOBlock ( int  fd  ) 

void PProcess::PXCheckSignals (  ) 

int PProcess::PXGetArgc (  )  const [inline]

char** PProcess::PXGetArgv (  )  const [inline]

char** PProcess::PXGetEnvp (  )  const [inline]

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

BOOL PProcess::SetGroupName ( const PString groupname,
BOOL  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

BOOL 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

PINLINE 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.

BOOL PProcess::SetUserName ( const PString username,
BOOL  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:
username New user name or uid
permanent Flag 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

friend class PApplication [friend]

friend class PHouseKeepingThread [friend]

friend class PServiceProcess [friend]

friend class PThread [friend]

void PXSigHandler ( int   )  [friend]

void PXSignalHandler ( int   )  [friend]


Member Data Documentation

PXFdDict PProcess::ioBlocks[3] [protected]

int PProcess::pxSignals [protected]


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

Generated on Thu Aug 20 12:07:39 2009 for PWLib by  doxygen 1.5.9