A handle to an object. More...

#include <e32cmn.h>

Inheritance diagram for RHandleBase:

Public Types
enum	TAttributes { EReadAccess =0x1 , EWriteAccess =0x2 , EDirectReadAccess =0x4 , EDirectWriteAccess =0x8 }
	Read/Write attributes for the handle. More...

Public Member Functions
	RHandleBase ()
	Default constructor.

TInt	Handle () const
	Retrieves the handle-number of the object associated with this handle.

void	SetHandle (TInt aHandle)
	Sets the handle-number of this handle to the specified value.

TInt	SetReturnedHandle (TInt aHandleOrError)
	Sets the handle-number of this handle to the specified value.

IMPORT_C void	Close ()
	Closes the handle.

IMPORT_C TName	Name () const
	Gets the name of the handle.

IMPORT_C TFullName	FullName () const
	Gets the full name of the handle.

IMPORT_C void	FullName (TDes &aName) const
	Gets the full name of the handle.

IMPORT_C void	SetHandleNC (TInt aHandle)
	Sets the handle-number of this handle to the specified value, and marks it as not closable.

IMPORT_C TInt	Duplicate (const RThread &aSrc, TOwnerType aType=EOwnerProcess)
	Creates a valid handle to the kernel object for which the specified thread already has a handle.

IMPORT_C void	HandleInfo (THandleInfo *anInfo)
	Gets information about the handle.

IMPORT_C TUint	Attributes () const

IMPORT_C TInt	BTraceId () const
	Returns a unique object identifier for use with BTrace.

IMPORT_C void	NotifyDestruction (TRequestStatus &aStatus)
	Internal technology API.

Static Public Member Functions
static void	DoExtendedClose ()

Protected Member Functions
	RHandleBase (TInt aHandle)
	Copy constructor.

IMPORT_C TInt	Open (const TFindHandleBase &aHandle, TOwnerType aType)
	Opens a handle to a kernel side object found using a find-handle object.

TInt	OpenByName (const TDesC &aName, TOwnerType aOwnerType, TInt aObjectType)
	Implementation for RXxxxx::Open/OpenGlocbal(const TDesC &aName,,TOwnerType aType) functions.

Static Protected Member Functions
static TInt	SetReturnedHandle (TInt aHandleOrError, RHandleBase &aHandle)

Protected Attributes
TInt	iHandle

Detailed Description

A handle to an object.

The class encapsulates the basic behaviour of a handle, hiding the handle-number which identifies the object which the handle represents.

The class is abstract in the sense that a RHandleBase object is never explicitly instantiated. It is always a base class to a concrete handle class; for example, RSemaphore, RThread, RProcess, RCriticalSection etc.

API status: Published to all clients. Released API.

Definition at line 2568 of file e32cmn.h.

Member Enumeration Documentation

◆ TAttributes

enum RHandleBase::TAttributes

Read/Write attributes for the handle.

API status: Published to all clients. Released API.

Enumerator
EReadAccess
EWriteAccess
EDirectReadAccess
EDirectWriteAccess

Definition at line 2579 of file e32cmn.h.

Constructor & Destructor Documentation

◆ RHandleBase() [1/2]

RHandleBase::RHandleBase ( )

inline

Default constructor.

(generated from Symbian Developer Library)

◆ RHandleBase() [2/2]

RHandleBase::RHandleBase ( TInt aHandle )

inlineprotected

Copy constructor.

It constructs this handle from an existing one. Specifically, the handle-number encapsulated by the specified handle is copied to this handle.

Parameters

aHandle The existing handle to be copied.

(generated from Symbian Developer Library)

Member Function Documentation

◆ Attributes()

IMPORT_C TUint RHandleBase::Attributes ( ) const

◆ BTraceId()

IMPORT_C TInt RHandleBase::BTraceId ( ) const

Returns a unique object identifier for use with BTrace.

(generated from Symbian Developer Library)

◆ Close()

IMPORT_C void RHandleBase::Close ( )

Closes the handle.

This has the effect of closing the associated kernel side object.

As the associated object is a reference counting object, it is destroyed if there are no other open references to it.

CObject

(generated from Symbian Developer Library)

◆ DoExtendedClose()

static void RHandleBase::DoExtendedClose ( )

static

◆ Duplicate()

IMPORT_C TInt RHandleBase::Duplicate	(	const RThread &	aSrc,
		TOwnerType	aType = `EOwnerProcess`
	)

Creates a valid handle to the kernel object for which the specified thread already has a handle.

The function assumes that this handle has been copy constructed from an existing handle (or the handle-number has been explicitly copied through calls to Handle() and SetHandle()).

By default, any thread in the process can use this handle to access the kernel side object that the handle represents. However, specifying EOwnerThread as the second parameter to this function, means that only the creating thread can use this handle to access the kernel side object; any other thread in this process that wants to access the kernel side object must, again, duplicate this handle.

Parameters

aSrc	A reference to the thread containing the handle which is to be duplicated for this thread.
aType	An enumeration whose enumerators define the ownership of this handle. If not explicitly specified, EOwnerProcess is taken as default.

(generated from Symbian Developer Library)

◆ FullName() [1/2]

IMPORT_C TFullName RHandleBase::FullName ( ) const

Gets the full name of the handle.

Note: This method is stack consuming (it takes 512 bytes on stack to execute). For an alternative way to obtain the full name of the object, see RHandleBase::FullName(TDes& aName) const.

RHandleBase::FullName(TDes& aName) const

(generated from Symbian Developer Library)

◆ FullName() [2/2]

IMPORT_C void RHandleBase::FullName ( TDes & aName ) const

Gets the full name of the handle.

Parameters

aName On return, contains the full name of the handle.

Panic condition: KERN-EXEC 35, If full name of the handler is longer that the maximum length of aName descriptor. To avoid this, the maximum length of aName should be at least KMaxFullName.

(generated from Symbian Developer Library)

◆ Handle()

TInt RHandleBase::Handle ( ) const

inline

Retrieves the handle-number of the object associated with this handle.

(generated from Symbian Developer Library)

◆ HandleInfo()

IMPORT_C void RHandleBase::HandleInfo ( THandleInfo * anInfo )

Gets information about the handle.

Parameters

anInfo A pointer to a THandleInfo object supplied by the caller; on return, contains the handle information.

(generated from Symbian Developer Library)

◆ Name()

IMPORT_C TName RHandleBase::Name ( ) const

Gets the name of the handle.

(generated from Symbian Developer Library)

◆ NotifyDestruction()

IMPORT_C void RHandleBase::NotifyDestruction ( TRequestStatus & aStatus )

Internal technology API.

◆ Open()

IMPORT_C TInt RHandleBase::Open	(	const TFindHandleBase &	aHandle,
		TOwnerType	aType
	)

protected

Opens a handle to a kernel side object found using a find-handle object.

Parameters

aHandle	A find-handle object; an object that is used in searching for kernel side objects.
aType	An enumeration whose enumerators define the ownership of this handle. If not explicitly specified, EOwnerProcess is taken as default, and ownership is vested in the current process. Ownership can be vested in the current thread by passing the EOwnerThread enumerator.

(generated from Symbian Developer Library)

◆ OpenByName()

TInt RHandleBase::OpenByName	(	const TDesC &	aName,
		TOwnerType	aOwnerType,
		TInt	aObjectType
	)

protected

Implementation for RXxxxx::Open/OpenGlocbal(const TDesC &aName,,TOwnerType aType) functions.

(generated from Symbian Developer Library)

◆ SetHandle()

void RHandleBase::SetHandle ( TInt aHandle )

inline

Sets the handle-number of this handle to the specified value.

Parameters

aHandle The handle-number to be set.

(generated from Symbian Developer Library)

◆ SetHandleNC()

IMPORT_C void RHandleBase::SetHandleNC ( TInt aHandle )

Sets the handle-number of this handle to the specified value, and marks it as not closable.

Parameters

aHandle The handle-number to be set.

(generated from Symbian Developer Library)

◆ SetReturnedHandle() [1/2]

TInt RHandleBase::SetReturnedHandle ( TInt aHandleOrError )

inline

Sets the handle-number of this handle to the specified value.

The function can take a (zero or positive) handle-number, or a (negative) error number.

If aHandleOrError represents a handle-number, then the handle-number of this handle is set to that value. If aHandleOrError represents an error number, then the handle-number of this handle is set to zero and the negative value is returned.

Parameters

aHandleOrError A handle-number, if zero or positive; an error value, if negative.

(generated from Symbian Developer Library)

◆ SetReturnedHandle() [2/2]

static TInt RHandleBase::SetReturnedHandle	(	TInt	aHandleOrError,
		RHandleBase &	aHandle
	)

staticprotected

Member Data Documentation

◆ iHandle

TInt RHandleBase::iHandle

protected

Definition at line 2612 of file e32cmn.h.

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

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Detailed Description

Member Enumeration Documentation

◆ TAttributes

Constructor & Destructor Documentation

◆ RHandleBase() [1/2]

◆ RHandleBase() [2/2]

Member Function Documentation

◆ Attributes()

◆ BTraceId()

◆ Close()

◆ DoExtendedClose()

◆ Duplicate()

◆ FullName() [1/2]

◆ FullName() [2/2]

◆ Handle()

◆ HandleInfo()

◆ Name()

◆ NotifyDestruction()

◆ Open()

◆ OpenByName()

◆ SetHandle()

◆ SetHandleNC()

◆ SetReturnedHandle() [1/2]

◆ SetReturnedHandle() [2/2]

Member Data Documentation

◆ iHandle