RHandleBase Class Reference

#include <e32cmn.h>

class RHandleBase
Protected Attributes
TInt iHandle
Public Member Enumerations
enumTAttributes { EReadAccess, EWriteAccess, EDirectReadAccess, EDirectWriteAccess }
Public Member Functions
RHandleBase()
IMPORT_C TUintAttributes()
IMPORT_C TIntBTraceId()
IMPORT_C voidClose()
voidDoExtendedClose()
IMPORT_C TIntDuplicate(const RThread &, TOwnerType)
IMPORT_C TFullNameFullName()
IMPORT_C voidFullName(TDes &)
TInt Handle()
IMPORT_C voidHandleInfo(THandleInfo *)
IMPORT_C TNameName()
IMPORT_C voidNotifyDestruction(TRequestStatus &)
voidSetHandle(TInt)
IMPORT_C voidSetHandleNC(TInt)
TInt SetReturnedHandle(TInt)
Protected Member Functions
RHandleBase(TInt)
IMPORT_C TIntOpen(const TFindHandleBase &, TOwnerType)
TInt OpenByName(const TDesC &, TOwnerType, TInt)
TInt SetReturnedHandle(TInt, RHandleBase &)

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.

Member Attribute Documentation

iHandle

TInt iHandle[protected]

Member Enumeration Documentation

Enum TAttributes

Read/Write attributes for the handle.

EnumeratorValueDescription
EReadAccess0x1
EWriteAccess0x2
EDirectReadAccess0x4
EDirectWriteAccess0x8

Constructor & Destructor Documentation

RHandleBase ( )

RHandleBase()[inline]

Default constructor.

RHandleBase ( TInt )

RHandleBase(TIntaHandle)[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
aHandleThe existing handle to be copied.

Member Function Documentation

Attributes ( )

IMPORT_C TUintAttributes()const

BTraceId ( )

IMPORT_C TIntBTraceId()const

Returns a unique object identifier for use with BTrace

Close ( )

IMPORT_C voidClose()

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.

See also: CObject

DoExtendedClose ( )

voidDoExtendedClose()[static]

Duplicate ( const RThread &, TOwnerType )

IMPORT_C TIntDuplicate(const RThread &aSrc,
TOwnerTypeaType = 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
aSrcA reference to the thread containing the handle which is to be duplicated for this thread.
aTypeAn enumeration whose enumerators define the ownership of this handle. If not explicitly specified, EOwnerProcess is taken as default.
Return Value
KErrNone, if successful; otherwise, one of the other system wide error codes.

FullName ( )

IMPORT_C TFullNameFullName()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.

See also: RHandleBase::FullName(TDes& aName) const

Return Value
The full name of the handle.

FullName ( TDes & )

IMPORT_C voidFullName(TDes &aName)const

Gets the full name of the handle.

See also: KMaxFullName

Parameters
aNameOn return, contains the full name of the handle.
Panic Codes
KERN-EXEC35, 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.

Handle ( )

TInt Handle()const [inline]

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

Return Value
The handle number

HandleInfo ( THandleInfo * )

IMPORT_C voidHandleInfo(THandleInfo *anInfo)

Gets information about the handle.

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

Name ( )

IMPORT_C TNameName()const

Gets the name of the handle.

Return Value
The name of the handle.

NotifyDestruction ( TRequestStatus & )

IMPORT_C voidNotifyDestruction(TRequestStatus &aStatus)

Queue a notifier to detect destruction of this object

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

Open ( const TFindHandleBase &, TOwnerType )

IMPORT_C TIntOpen(const TFindHandleBase &aHandle,
TOwnerTypeaType
)[protected]

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

Parameters
aHandleA find-handle object; an object that is used in searching for kernel side objects.
aTypeAn 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.
Return Value
KErrNone, if successful; otherwise one of the other system wide error codes.

OpenByName ( const TDesC &, TOwnerType, TInt )

TInt OpenByName(const TDesC &aName,
TOwnerTypeaOwnerType,
TIntaObjectType
)[protected]

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

SetHandle ( TInt )

voidSetHandle(TIntaHandle)[inline]

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

Parameters
aHandleThe handle-number to be set.

SetHandleNC ( TInt )

IMPORT_C voidSetHandleNC(TIntaHandle)

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

Parameters
aHandleThe handle-number to be set.

SetReturnedHandle ( TInt )

TInt SetReturnedHandle(TIntaHandleOrError)[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
aHandleOrErrorA handle-number, if zero or positive; an error value, if negative.
Return Value
KErrNone, if aHandle is a handle-number; the value of aHandleOrError, otherwise.

SetReturnedHandle ( TInt, RHandleBase & )

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