Class RProcess

RProcess

Support

Supported from 5.0

Description

A handle to a process. The process itself is a Kernel object.

Derivation

RHandleBase Handle to an object RProcess A handle to a process

Defined in RProcess:
CommandLine(), CommandLineLength(), Create(), ExitCategory(), ExitReason(), ExitType(), FileName(), GetRamSizes(), Id(), Kill(), LoadedFromRam(), Logon(), LogonCancel(), Open(), Owner(), Panic(), Priority(), Protected(), RProcess(), Rename(), Resume(), SetOwner(), SetPriority(), SetProtected(), SetType(), Type()

Inherited from RHandleBase:
Close(), Duplicate(), Handle(), SetHandle()

RProcess();

Description

Constructs this object.

The constructor exists to initialise private data within this handle; it does not create the process object.

Specifically, it sets the handle-number to the value KCurrentProcessHandle, defined in e32std.h. In effect, construction of a RProcess creates a default process handle.

TInt Create(const TDesC& aFileName,const TDesC& aCommand,const TUidType& aUidType, TOwnerType aType=EOwnerProcess);
TInt Create(const TDesC& aFileName,const TDesC& aCommand,TOwnerType aType=EOwnerProcess);

Description

Starts a new process, loading the specified executable which matches the specified UID type.

The executable can be in ROM or RAM.

By default, ownership of this process handle is vested in the current process, but can be vested in the current thread by passing EOwnerThread as the second parameter to this function.

Parameters

const TDesC& aFileName A descriptor containing the full path name of the executable to be loaded. If this name has no file extension, an extension of .EXE is appended. The length of the resulting full path name must not be greater than KMaxFileName, defined in e32std.h. The length of the file name itself must not be greater than KMaxOsName defined in e32std.h. If no path is specified, the system will look in \System\Programs on all drives, in the usual search order. const TDesC& aCommand A descriptor containing data passed as an argument to the thread function of the new process's main thread, when it is first scheduled. The length of this descriptor must not be greater than KMaxCommandLine. const TUidType& aUidType If specified, a UID type (a triplet of UIDs) which the executable must match. If not specified, defaults to a UID type containing KNullUid UIDs. TOwnerType aType=EOwnerProcess An enumeration whose enumerators define the ownership of this process handle. If not explicitly specified, EOwnerProcess is taken as default.

Return value

TInt KErrNone if successful otherwise another of the system-wide error codes.

TInt Open(const TDesC& aName,TOwnerType aType=EOwnerProcess);

Description

Opens a handle to a specifically named process.

By default, ownership of this process handle is vested in the current process, but can be vested in the current thread by passing EOwnerThread as the second parameter to this function.

Parameters

const TDesC& aName A reference to the descriptor containing the name of the process to be opened. TOwnerType aType=EOwnerProcess An enumeration whose enumerators define the ownership of this thread handle. If not explicitly specified, EOwnerProcess is taken as default.

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes:

TInt Open(const TFindProcess& aFind,TOwnerType aType=EOwnerProcess);

Description

Opens a handle to the process found by pattern matching a name.

A TFindProcess object is used to find all processes whose full names match a specified pattern.

By default, ownership of this process handle is vested in the current process, but can be vested in the current thread by passing EOwnerThread as the second parameter to this function.

Parameters

const TFindProcess& aFind A reference to the TFindProcess object used to find the process. TOwnerType aType An enumeration whose enumerators define the ownership of this process handle. If not explicitly specified, EOwnerProcess is taken as default.

Return value

TInt KErrNone if successful otherwise another of the system-wide error codes.

TInt Open(TProcessId aId,TOwnerType aType=EOwnerProcess);

Description

Opens a handle to the process whose process Id matches a specific process ID.

By default, ownership of this process handle is vested in the current process, but can be vested in the current thread by passing EOwnerThread as the second parameter to this function.

Parameters

TProcessId aId The process Id used to find the process. TOwnerType aType An enumeration whose enumerators define the ownership of this process handle. If not explicitly specified, EOwnerProcess is taken as default.

Return value

TInt KErrNone if successful otherwise another of the system-wide error codes.

TInt Rename(const TDesC& aName);

Description

Assigns a new name to this process, replacing any existing name.

When a process is created, its default name is the name portion of the filename from which the executable is loaded.

Any attempt to rename a process which is protected and is different from the process invoking this function, causes the rename operation to fail. A process can call Rename() on itself whether it is protected or not.

The new name must be a valid name and it must also be such that the process's new fullname remains unique amongst processes.

Parameters

const TDesC& aName A reference to the descriptor containing the new name of the process.

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes. Specifically: KErrBadName, if aName is an invalid. KErrAlreadyExists, if a process with the same fullname as that generated from aName already exists.

TProcessPriority Priority() const;

Description

Returns the priority of this process.

Return value

TProcessPriority One of the TProcessPriority enumerator values

void SetPriority(TProcessPriority aPriority) const;

Description

Sets the priority of this process to one of the values defined by theTProcessPriority enumeration. The priority can be set to one of the four values:

• EPriorityLow

• EPriorityBackground

• EPriorityForeground

• EPriorityHigh

The absolute priority of all threads owned by the process (and all threads owned by those threads etc.) are re-calculated.

Notes:

• The priority values EPriorityWindowServer, EPriorityFileServer, EPriorityRealTimeServer and EPrioritySupervisor are restricted to EPOC itself and any attempt to explicitly set any of these priority values causes a KERN-EXEC 14 panic to be raised.

• Any attempt to set the priority of a process which is protected and is different from the process owning the thread which invokes this function, causes a KERN-EXEC 1 panic to be raised.

• A process can set its own priority whether it is protected or not.

Parameters

TProcessPriority aPriority The priority value; the enumeration is defined ine32std.h.

void Resume();

Description

Makes the first thread (the main thread) in the process eligible for execution.

Notes:

• The process must be fully loaded before calling this function, otherwise a PLAT 12 panic is raised.

• See the Resume() member function of RThread for additional information on resuming threads.

void Kill(TInt aReason);

Description

Ends this process specifying a reason code.

Notes:

• Any attempt to end a process which is protected and is different from the process owning the thread which invokes this function, causes a KERN-EXEC 1 panic to be raised.

• A process can call Kill() on itself whether it is protected or not.

Parameters

TInt aReason The reason to be associated with the ending of this process.

void Panic(const TDesC& aCategory,TInt aReason);

Description

Panics the process and all of its owned threads, specifying the panic category name and reason code.

The length of the category name should be no greater than 16; any name with a length greater than 16 is truncated to 16.

Notes:

• Any attempt to panic a process which is protected and is different from the process owning the thread which invokes this function, causes a KERN-EXEC 1 panic to be raised.

• A process can call Panic() on itself whether it is protected or not.

Parameters

const TDesC& aCategory A reference to the descriptor containing the text which defines the category name for this panic. TInt aReason The panic number

TExitType ExitType() const;

Description

Has the process ended and, if it has ended, return how it ended.

This information allows the caller to distinguish between controlled termination and a panic.

Note that while the process is alive, the function returnsEExitPending.

Return value

TExitType An enumeration whose enumerators describe how the process has ended.

TInt ExitReason() const;

Description

Returns the specific reason associated with the end of this process. The reason number together with the category name is a way of distinguishing between different causes of process termination.

If the process has panicked, this value is the panic number. If the process has ended as a result of a call to Kill(), then the value is the one supplied by Kill().

If the process has not ended, then the returned value is zero.

Return value

TInt The reason associated with the end of the process.

TExitCategoryName ExitCategory() const;

Description

Returns the name of the category associated with the end of the process. The category name together with the reason number is a way of distinguishing between different causes of process termination.

If the process has panicked, the category name is the panic category name; for example, E32USER-CBase or KERN-EXEC. If the process has ended as a result of a call to Kill(), then the category name is Kill.

If the process has not ended, then the category name is empty, i.e. the length of the category name is zero.

Return value

TExitCategoryName A TBuf<TInt> descriptor with a defined maximum length containing the name of the category associated with the end of the process.

void Logon(TRequestStatus& aStatus) const;

Description

Requests notification when this process dies, normally or otherwise.

A request for notification is an asynchronous request.

When this process dies, the request completes andTRequestStatus is set to one of theTExitTypeenumerators identifying how the process has died.

Alternatively, if an outstanding notification request is cancelled by a call to this process's LogonCancel() member function, then the request completes with the value KErrCancel.

A request for notification requires memory to be allocated; if this is unavailable, the call to Logon() returns but the asynchronous request completes immediately with the valueKErrNoMemory.

Parameters

TRequestStatus& aStatus A reference to the request status object. When the asynchronous request completes, this is set to: KErrCancel, if an outstanding request is cancelled.KErrNoMemory, if there is insufficient memory. One of the TExitType enumerators identifying how the process has died.

TInt LogonCancel(TRequestStatus& aStatus) const;

Description

Cancels an outstanding request for notification of the death of this process.

A request for notification must previously have been made, otherwise the function returns KErrGeneral.

The caller passes a reference to the same request status object as was passed in the original call to Logon().

Parameters

TRequestStatus& aStatus A reference to the same request status object used in the original call to Logon().

Return value

TInt KErrGeneral if there is no outstanding request,KErrNone otherwise.

TUidType Type() const;

Description

Returns the type associated with the process.

Return value

TUidType A reference to a TUidType object containing the process type.

TProcessId Id() const;

Description

Returns the Id of this process.

Return value

TProcessId The Id of this process.

TFileName FileName() const;

Description

Returns a copy of the full path name of the loaded executable on which this process is based.

This is the file name which is passed to the Create() member function of this RProcess.

Return value

TFileName A TBuf descriptor with a defined maximum length containing the full path name of the file.

See also:

• TBuf

TCommand CommandLine() const;

Support

Withdrawn in 6.0

Description

Gets a copy of the data which is passed as an argument to the thread function of the new process's main thread when it is first scheduled to run.

This is the command line which is passed to theCreate()member function of thisRProcess().

Return value

TCommand A TBuf descriptor with a defined maximum length containing the command line.

See also:

• TBuf

void CommandLine(TDes& aCommand) const;

Support

Supported from 6.0

Description

Gets a copy of the data which is passed as an argument to the thread function of the new process's main thread when it is first scheduled to run.

Parameters

TDes& aCommand A modifiable descriptor supplied by the caller into which the argument data is put. The descriptor must be big enough, otherwise the function raises a panic.

See also:

• TDes

TInt CommandLineLength() const;

Support

Supported from 6.0

Description

Gets the length of the data which is passed as an argument to the thread function of the new process's main thread when it is first scheduled to run.

Return value

TInt The length of the argument data.

See also:

• TDes

TInt GetRamSizes(TInt& aCodeSize, TInt& aConstDataSize, TInt& anInitialisedDataSize, TInt& anUninitialisedDataSize);

Description

Gets the size of an executable's sections.

This function is deprecated and should not be used.

TBool LoadedFromRam() const;

Description

Tests whether the executable for this process was loaded from RAM or was found in ROM.

Return value

TBool True, if the executable was loaded from RAM; false otherwise.

TBool Protected() const;

Description

Tests whether this process is protected.

The protected state prevents any other process from setting the priority, ending or panicking this process.

Return value

TBool True, if the process is protected; false, otherwise.

TInt Owner(RProcess &anOwner) const;

Description

Gets a handle to the process which owns this process.

Parameters

RProcess &anOwner A reference to a default process handle. On successful return from this function, this is a fully constructed handle. to the owning process.

Return value

TInt KErrNone if successful otherwise another of the system-wide error codes. Specifically: KErrNotFound, if this process has no owning process.

void SetType(const TUidType& aType);

Description

Sets the process type.

Parameters

const TUidType& aType A reference to a TUidType object containing the process type.

void SetProtected(TBool aState) const;

Description

Sets the process into a protected state.

The protected state prevents any other process from setting the priority, ending or panicking this process.

Parameters

TBool aState True, if the process is to be protected; false, otherwise.

void SetOwner(const RProcess& aProcess) const;

Description

Makes the process with the specified handle the owner of this process.

Parameters

const RProcess& aProcess A reference to the handle of the process which is to own this process.