Class RHandleBase

class RHandleBase;

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.

Members

Defined in RHandleBase:
Attributes(), Close(), Duplicate(), FullName(), FullName(), Handle(), HandleInfo(), Name(), Open(), RHandleBase(), RHandleBase(), SetHandle(), SetHandleNC(), SetReturnedHandle(), iHandle

inline RHandleBase();

Description

Default constructor.

protected: inline RHandleBase(TInt aHandle);

Description

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.

inline TInt Handle() const;

Description

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

Return value

TInt The handle number

inline void SetHandle(TInt aHandle);

Description

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

Parameters

TInt aHandle The handle-number to be set.

inline TInt SetReturnedHandle(TInt aHandleOrError);

Description

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.

Return value

TInt KErrNone, if aHandle is a handle-number; the value of aHandleOrError, otherwise.

IMPORT_C void Close();

Description

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

IMPORT_C TName Name() const;

Description

Gets the name of the handle.

Return value

TName The name of the handle.

IMPORT_C TFullName FullName() const;

Description

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.

Return value

TFullName The full name of the handle.

IMPORT_C void FullName(TDes &aName) const;

Description

Gets the full name of the handle.

Parameters

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

Panic codes

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.

See also:

• KMaxFullName

IMPORT_C void SetHandleNC(TInt aHandle);

Description

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.

IMPORT_C TInt Duplicate(const RThread &aSrc, TOwnerType aType=EOwnerProcess);

Description

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 An enumeration whose enumerators define the ownership of this handle. If not explicitly specified, EOwnerProcess is taken as default.

Return value

TInt KErrNone, if successful; otherwise, one of the other system wide error codes.

IMPORT_C void HandleInfo(THandleInfo *anInfo);

Description

Gets information about the handle.

Parameters

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

IMPORT_C TUint Attributes() const;

Description

Return value

TUint

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

Description

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.

Return value

TInt KErrNone, if successful; otherwise one of the other system wide error codes.

protected: TInt iHandle;

Description