Collapse all Symbian^3 Product Developer Library

RHandleBase Class Reference

class RHandleBase

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.

Public Member Functions
	RHandleBase()
IMPORT_C TUint	Attributes()
IMPORT_C TInt	BTraceId()
IMPORT_C void	Close()
void	DoExtendedClose()
IMPORT_C TInt	Duplicate(const RThread &, TOwnerType)
IMPORT_C TFullName	FullName()
IMPORT_C void	FullName(TDes &)
TInt	Handle()
IMPORT_C void	HandleInfo(THandleInfo *)
IMPORT_C TName	Name()
IMPORT_C void	NotifyDestruction(TRequestStatus &)
void	SetHandle(TInt)
IMPORT_C void	SetHandleNC(TInt)
TInt	SetReturnedHandle(TInt)

Protected Member Functions
	RHandleBase(TInt)
IMPORT_C TInt	Open(const TFindHandleBase &, TOwnerType)
TInt	OpenByName(const TDesC &, TOwnerType, TInt)
TInt	SetReturnedHandle(TInt, RHandleBase &)

Private Member Functions
void	DoExtendedCloseL()

Public Member Enumerations
enum	TAttributes { EReadAccess = 0x1, EWriteAccess = 0x2, EDirectReadAccess = 0x4, EDirectWriteAccess = 0x8 }

Protected Attributes
TInt	iHandle

Constructor & Destructor Documentation

RHandleBase()

RHandleBase

(

)

[inline]

Default constructor.

RHandleBase(TInt)

RHandleBase

(

TInt

aHandle

)

[protected, inline]

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

TInt aHandle

The existing handle to be copied.

Member Functions Documentation

Attributes()

IMPORT_C TUint

Attributes

(

)

const

BTraceId()

IMPORT_C TInt

BTraceId

(

)

const

Returns a unique object identifier for use with BTrace

Close()

IMPORT_C void

(

)

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

DoExtendedClose()

void

DoExtendedClose

(

)

[static]

DoExtendedCloseL()

void

DoExtendedCloseL

(

)

[private, static]

Duplicate(const RThread &, TOwnerType)

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.

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

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

FullName()

IMPORT_C TFullName

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

FullName(TDes &)

IMPORT_C void

FullName

(

TDes &

aName

)

const

Gets the full name of the handle.

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

KMaxFullName

Parameters

TDes & aName

On return, contains the full name of the handle.

Handle()

TInt

Handle

(

)

const [inline]

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

HandleInfo(THandleInfo *)

IMPORT_C void

HandleInfo

(

THandleInfo *

anInfo

)

Gets information about the handle.

Parameters

THandleInfo * anInfo

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

Name()

IMPORT_C TName

Name

(

)

const

Gets the name of the handle.

NotifyDestruction(TRequestStatus &)

IMPORT_C void

NotifyDestruction

(

TRequestStatus &

aStatus

)

Queue a notifier to detect destruction of this object

To cancel the notifier, use User::CancelMiscNotifier().

Parameters

TRequestStatus & aStatus

Open(const TFindHandleBase &, TOwnerType)

IMPORT_C TInt	Open	(	const TFindHandleBase &	aHandle,
			TOwnerType	aType
		)	[protected]

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

Parameters

const TFindHandleBase & aHandle	A find-handle object; an object that is used in searching for kernel side objects.
TOwnerType 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.

OpenByName(const TDesC &, TOwnerType, TInt)

TInt	OpenByName	(	const TDesC &	aName,
			TOwnerType	aOwnerType,
			TInt	aObjectType
		)	[protected]

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

Parameters

const TDesC & aName
TOwnerType aOwnerType
TInt aObjectType

SetHandle(TInt)

void

SetHandle

(

TInt

aHandle

)

[inline]

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

Parameters

TInt aHandle

The handle-number to be set.

SetHandleNC(TInt)

IMPORT_C void

SetHandleNC

(

TInt

aHandle

)

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

Parameters

TInt aHandle

The handle-number to be set.

SetReturnedHandle(TInt)

TInt

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

TInt aHandleOrError

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

SetReturnedHandle(TInt, RHandleBase &)

TInt	SetReturnedHandle	(	TInt	aHandleOrError,
			RHandleBase &	aHandle
		)	[protected, static]

Parameters

TInt aHandleOrError
RHandleBase & aHandle

Member Enumerations Documentation

Enum TAttributes

Read/Write attributes for the handle.

Enumerators

EReadAccess = 0x1
EWriteAccess = 0x2
EDirectReadAccess = 0x4
EDirectWriteAccess = 0x8

Member Data Documentation

TInt iHandle

TInt

iHandle

[protected]