Class RProcess

class RProcess : public RHandleBase;

Description

A handle to a process.

The process itself is a kernel object.

Derivation

• RHandleBase - A handle to an object.

• RProcess - A handle to a process.

Members

Defined in RProcess:

• Create(const TDesC &,const TDesC &,TOwnerType)Starts a new process, loading the specified executable.
• Create(const TDesC &,const TDesC &,const TUidType &,TOwnerType)Starts a new process, loading the specified executable which matches the specifi...
• CreateWithStackOverride(const TDesC &,const TDesC &,const TUidType &,TInt,TOwnerType)CR0885
• ExitCategory()constGets the name of the category associated with the end of the process.
• ExitReason()constGets the specific reason associated with the end of this process.
• ExitType()constTests whether the process has ended and, if it has ended, return how it ended.
• FileName()constGets a copy of the full path name of the loaded executable on which this process...
• GetMemoryInfo(TModuleMemoryInfo &)constGets the size and base address of the code and various data sections of the proc...
• HasCapability(TCapability,TCapability,const char *)constCheck if the process has both of the given capabilities
• HasCapability(TCapability,const char *)constCheck if the process has a given capability
• Id()constGets the Id of this process.
• Identity()const
• JustInTime()constTests whether "Just In Time" debugging is enabled or not for this proc...
• Kill(TInt)Ends this process, and all of its threads, specifying a reason code.
• Logon(TRequestStatus &)constRequests notification when this process dies, normally or otherwise.
• LogonCancel(TRequestStatus &)constCancels an outstanding request for notification of the death of this process.
• Open(TProcessId,TOwnerType)Opens a handle to the process whose process Id matches the specified process ID.
• Open(const TDesC &,TOwnerType)Opens a handle to a specifically named process.
• Open(const TFindProcess &,TOwnerType)Opens a handle to the process found by pattern matching a name.
• Panic(const TDesC &,TInt)Panics the process and all of its owned threads, specifying the panic category n...
• Priority()constGets the priority of this process.
• RProcess()Default constructor.
• RProcess(TInt)Constructor taking a handle number.
• RenameMe(const TDesC &)
• Rendezvous(TInt)Completes all Rendezvous' with the current process.
• Rendezvous(TRequestStatus &)constCreates a Rendezvous request with the process.
• RendezvousCancel(TRequestStatus &)constCancels a previously requested Rendezvous with the process.
• Resume()Makes the first thread in the process eligible for execution.
• SecureId()constReturn the Secure ID of the process.
• SetJustInTime(TBool)constEnables or disables "Just In Time" debugging for this process. This wi...
• SetParameter(TInt,RHandleBase)Sets the specified handle into the specified environment data slot for this proc...
• SetParameter(TInt,TInt)Sets the specfied integer value into the specified environment data slot for thi...
• SetParameter(TInt,const RSubSessionBase &)Sets the specfied sub-session into the specified environment data slot for this ...
• SetParameter(TInt,const TDesC16 &)Sets the specified 16-bit descriptor data into the specified environment data sl...
• SetParameter(TInt,const TDesC8 &)Sets the specified 8-bit descriptor data into the specified environment data slo...
• SetPriority(TProcessPriority)constSets the priority of this process to one of the values defined by theTProcessPri...
• Terminate(TInt)Ends this process, and all of its threads, specifying a reason code.
• Type()constGets the Uid type associated with the process.
• VendorId()constReturn the Vendor ID of the process.

Inherited from RHandleBase:

• Attributes()const
• BTraceId()constReturns a unique object identifier for use with BTrace
• Close()Closes the handle.
• Duplicate(const RThread &,TOwnerType)Creates a valid handle to the kernel object for which the specified thread alrea...
• FullName()constGets the full name of the handle.
• FullName(TDes &)constGets the full name of the handle.
• Handle()constRetrieves the handle-number of the object associated with this handle.
• HandleInfo(THandleInfo *)Gets information about the handle.
• Name()constGets the name of the handle.
• Open(const TFindHandleBase &,TOwnerType)Opens a handle to a kernel side object found using a find-handle object.
• RHandleBase(TInt)Copy constructor.
• SetHandle(TInt)Sets the handle-number of this handle to the specified value.
• SetHandleNC(TInt)Sets the handle-number of this handle to the specified value, and marks it as no...
• SetReturnedHandle(TInt)Sets the handle-number of this handle to the specified value.
• iHandle

inline RProcess();

Description

Default constructor.

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. In effect, the constructor creates a default process handle.

inline RProcess(TInt aHandle);

Description

Constructor taking a handle number.

Parameters

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

Description

Starts a new process, loading the specified executable.

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 specifying EOwnerThread as the third parameter to this function.

Parameters

Return value

IMPORT_C TInt Create(const TDesC &aFileName, const TDesC &aCommand, const TUidType &aUidType, 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 specifying EOwnerThread as the fourth parameter.

Parameters

Return value

IMPORT_C 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

Return value

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

Description

Opens a handle to the process whose process Id matches the specified 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

Return value

IMPORT_C TUidType Type() const;

Description

Gets the Uid type associated with the process.

Return value

IMPORT_C TProcessId Id() const;

Description

Gets the Id of this process.

Return value

static inline TInt RenameMe(const TDesC &aName);

Description

Parameters

Return value

IMPORT_C void Kill(TInt aReason);

Description

Ends this process, and all of its threads, specifying a reason code.

This function is intended to be used if a process is exiting under normal conditions.

If the process is system permanent, the entire system is rebooted.

Parameters

See also:

• User::SetProcessCritical(TCritical)Sets up or changes the effect that termination of subsequently created threads w...
• User::ProcessCritical()Gets the critical state associated with the current process.

IMPORT_C void Terminate(TInt aReason);

Description

Ends this process, and all of its threads, specifying a reason code.

This function is intended to be used if a process is exiting under abnormal conditions, for example if an error condition has been detected.

If the process is system critical or system permanent, the entire system is rebooted.

Parameters

See also:

• User::SetProcessCritical(TCritical)Sets up or changes the effect that termination of subsequently created threads w...
• User::ProcessCritical()Gets the critical state associated with the current process.

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

If the process is system critical or system permanent, the entire system is rebooted.

Parameters

See also:

• User::SetProcessCritical(TCritical)Sets up or changes the effect that termination of subsequently created threads w...
• User::ProcessCritical()Gets the critical state associated with the current process.

IMPORT_C void Resume();

Description

Makes the first thread in the process eligible for execution.

Panic codes

See also:

• RThread::Resume()constMakes the thread eligible for execution.

IMPORT_C TFileName FileName() const;

Description

Gets 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 RProcess::Create(const TDesC &,const TDesC &,TOwnerType) member function of this RProcess.

Return value

See also:

• RProcess::Create(const TDesC &,const TDesC &,TOwnerType)Starts a new process, loading the specified executable.

IMPORT_C TExitType ExitType() const;

Description

Tests whether the process has ended and, if it has ended, return how it ended.

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

Return value

IMPORT_C TInt ExitReason() const;

Description

Gets 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 RProcess::Kill(TInt), then the value is the one supplied by RProcess::Kill(TInt).

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

Return value

See also:

• RProcess::Kill(TInt)Ends this process, and all of its threads, specifying a reason code.

IMPORT_C TExitCategoryName ExitCategory() const;

Description

Gets 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 RProcess::Kill(TInt), 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

See also:

• RProcess::Kill(TInt)Ends this process, and all of its threads, specifying a reason code.

IMPORT_C TProcessPriority Priority() const;

Description

Gets the priority of this process.

Return value

IMPORT_C 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 internal to Symbian OS 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

IMPORT_C TBool JustInTime() const;

Description

Tests whether "Just In Time" debugging is enabled or not for this process.

Return value

See also:

• RProcess::SetJustInTime(TBool)constEnables or disables "Just In Time" debugging for this process. This wi...

IMPORT_C void SetJustInTime(TBool aBoolean) const;

Description

Enables or disables "Just In Time" debugging for this process. This will only have an effect when running on the emulator.

"Just In Time" debugging catches a thread just before it executes a panic or exception routine. Capturing a thread early, before it is terminated, allows the developer to more closely inspect what went wrong, before the kernel removes the thread. In some cases, the developer can modify context, program counter, and variables to recover the thread. This is only possible on the emulator.

By default, "Just In Time" debugging is enabled.

Parameters

IMPORT_C void Logon(TRequestStatus &aStatus) const;

Description

Requests notification when this process dies, normally or otherwise.

A request for notification is an asynchronous request, and completes:

• when the process terminates

• if the outstanding request is cancelled by a call to RProcess::LogonCancel(TRequestStatus &)const.

A request for notification requires memory to be allocated; if this is unavailable, then the call to RProcess::Logon(TRequestStatus &)const returns, and the asynchronous request completes immediately.

Parameters

See also:

• RProcess::LogonCancel(TRequestStatus &)constCancels an outstanding request for notification of the death of this process.
• RProcess::ExitReason()constGets the specific reason associated with the end of this process.

IMPORT_C 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 RProcess::Logon(TRequestStatus &)const.

Parameters

Return value

See also:

• RProcess::Logon(TRequestStatus &)constRequests notification when this process dies, normally or otherwise.

IMPORT_C TInt GetMemoryInfo(TModuleMemoryInfo &aInfo) const;

Description

Gets the size and base address of the code and various data sections of the process.

The run addresses are also returned.

Parameters

Return value

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

Description

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

ATFindProcess 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

Return value

IMPORT_C void Rendezvous(TRequestStatus &aStatus) const;

Description

Creates a Rendezvous request with the process.

The request is an asynchronous request, and completes:

• when a call is made to RProcess::Rendezvous(TInt).

• if the outstanding request is cancelled by a call to RProcess::RendezvousCancel(TRequestStatus &)const

• if the process exits

• if the process panics.

Note that a request requires memory to be allocated; if this is unavailable, then this call to RProcess::Rendezvous(TRequestStatus &)const returns, and the asynchronous request completes immediately.

Parameters

See also:

• RProcess::Rendezvous(TInt)Completes all Rendezvous' with the current process.

IMPORT_C TInt RendezvousCancel(TRequestStatus &aStatus) const;

Description

Cancels a previously requested Rendezvous with the process.

The request completes with the value KErrCancel (if it was still outstanding).

Parameters

Return value

IMPORT_C static void Rendezvous(TInt aReason);

Description

Completes all Rendezvous' with the current process.

Parameters

IMPORT_C TSecureId SecureId() const;

Description

Return the Secure ID of the process.

If an intended use of this method is to check that the Secure ID is a given value, then the use of a TSecurityPolicy object should be considered. E.g. Instead of something like:

        RProcess& process;
        TInt error = process.SecureId()==KRequiredSecureId ? KErrNone : KErrPermissionDenied;

this could be used;

        RProcess& process;
        static _LIT_SECURITY_POLICY_S0(mySidPolicy, KRequiredSecureId);
        TInt error = mySidPolicy().CheckPolicy(process);

This has the benefit that the TSecurityPolicy::CheckPolicy(RProcess,const char *)const methods are configured by the system wide Platform Security configuration. I.e. are capable of emitting diagnostic messages when a check fails and/or the check can be forced to always pass.

Return value

See also:

• TSecurityPolicy::CheckPolicy(RProcess,const char *)constChecks this policy against the platform security attributes of aProcess.

IMPORT_C TVendorId VendorId() const;

Description

Return the Vendor ID of the process.

If an intended use of this method is to check that the Vendor ID is a given value, then the use of a TSecurityPolicy object should be considered. E.g. Instead of something like:

        RProcess& process;
        TInt error = process.VendorId()==KRequiredVendorId ? KErrNone : KErrPermissionDenied;

this could be used;

        RProcess& process;
        static _LIT_SECURITY_POLICY_V0(myVidPolicy, KRequiredVendorId);
        TInt error = myVidPolicy().CheckPolicy(process);

This has the benefit that the TSecurityPolicy::CheckPolicy(RProcess,const char *)const methods are configured by the system wide Platform Security configuration. I.e. are capable of emitting diagnostic messages when a check fails and/or the check can be forced to always pass.

Return value

See also:

• TSecurityPolicy::CheckPolicy(RProcess,const char *)constChecks this policy against the platform security attributes of aProcess.

inline TBool HasCapability(TCapability aCapability, const char *aDiagnostic=0) const;

Description

Check if the process has a given capability

When a check fails the action taken is determined by the system wide Platform Security configuration. If PlatSecDiagnostics is ON, then a diagnostic message is emitted. If PlatSecEnforcement is OFF, then this function will return ETrue even though the check failed.

Parameters

Return value

inline TBool HasCapability(TCapability aCapability1, TCapability aCapability2, const char *aDiagnostic=0) const;

Description

Check if the process has both of the given capabilities

When a check fails the action taken is determined by the system wide Platform Security configuration. If PlatSecDiagnostics is ON, then a diagnostic message is emitted. If PlatSecEnforcement is OFF, then this function will return ETrue even though the check failed.

Parameters

Return value

IMPORT_C TInt SetParameter(TInt aIndex, RHandleBase aHandle);

Description

Sets the specified handle into the specified environment data slot for this process.

Parameters

Return value

Panic codes

IMPORT_C TInt SetParameter(TInt aSlot, const RSubSessionBase &aSession);

Description

Sets the specfied sub-session into the specified environment data slot for this process.

Parameters

Return value

Panic codes

IMPORT_C TInt SetParameter(TInt aSlot, const TDesC16 &aDes);

Description

Sets the specified 16-bit descriptor data into the specified environment data slot for this process.

Parameters

Return value

Panic codes

IMPORT_C TInt SetParameter(TInt aSlot, const TDesC8 &aDes);

Description

Sets the specified 8-bit descriptor data into the specified environment data slot for this process.

Parameters

Return value

Panic codes

IMPORT_C TInt SetParameter(TInt aSlot, TInt aData);

Description

Sets the specfied integer value into the specified environment data slot for this process.

Parameters

Return value

Panic codes

inline TUid Identity() const;

Description

Return value

IMPORT_C TInt CreateWithStackOverride(const TDesC &aFileName, const TDesC &aCommand, const TUidType &aUidType, TInt aMinStackSize, TOwnerType aType);

Description

CR0885

Parameters

Return value