CObject Class Reference

#include <e32base.h>

class CObject : public CBase

Inherits from

CObject
- CBase

Public Member Functions
	CObject()
	~CObject()
TInt	AccessCount()
virtual IMPORT_C void	Close()
virtual IMPORT_C TFullName	FullName()
virtual IMPORT_C TName	Name()
virtual IMPORT_C TInt	Open()
CObject *	Owner()
IMPORT_C TInt	SetName(const TDesC *)
IMPORT_C void	SetNameL(const TDesC *)
void	SetOwner(CObject *)

Protected Member Functions
void	Dec()
virtual IMPORT_C TInt	Extension_(TUint, TAny &, TAny )
void	Inc()
TInt	UniqueID()

Inherited Functions
	CBase::CBase()
	CBase::Delete(CBase *)
	CBase::operator new(TUint)
	CBase::operator new(TUint,TAny *)
	CBase::operator new(TUint,TLeave)
	CBase::operator new(TUint,TLeave,TUint)
	CBase::operator new(TUint,TUint)
	CBase::~CBase()

Detailed Description

Implements reference counting to track concurrent references to itself.

An object of this type arranges automatic destruction of itself when the final reference is removed.

A reference counting object is any object which has CObject as its base class. Constructing a CObject derived type or calling its Open() member function adds a reference to that object by adding one to the reference count; calling its Close() member function removes a reference by subtracting one from the reference count; when the last user of the object calls Close(), the reference count becomes zero and the object is automatically destroyed.

Constructor & Destructor Documentation

CObject ( )

IMPORT_C

CObject

(

)

Constructs the object and initializes the reference count to one.

Once constructed, a reference counting object cannot be deleted until its reference count is reduced to zero.

~CObject ( )

IMPORT_C

~CObject

(

)

Destructor.

It removes this reference counting object from its object container, a CObjectCon type.

Panic Codes
E32USER-CBase	33 if the reference count is not zero when the destructor is called.

Member Function Documentation

AccessCount ( )

TInt

AccessCount

(

)

const [inline]

Gets the number of open references to this reference counting object.

Return Value: The number of open references.

Close ( )

IMPORT_C void

(

)

[virtual]

Closes this reference counting object.

The default behaviour decrements the reference count by one. If this becomes zero, then the function deletes this reference counting object.

Where a derived class implements its own version of this function, it can use the protected member function Dec() to decrement the reference count or make a base call to this function.

Panic Codes
E32USER-CBase	34 if the reference count is negative when this function is called.

Dec ( )

void

Dec

(

)

[protected, inline]

Subtracts one from the reference count.

This function is called by the default implementation of the Close() member function of this class.

Extension_ ( TUint, TAny &, TAny )

IMPORT_C TInt	Extension_	(	TUint	aExtensionId,
			TAny *&	a0,
			TAny *	a1
		)	[protected, virtual]

Reimplemented from CBase::Extension_(TUint,TAny *&,TAny *)

Extension function

FullName ( )

IMPORT_C TFullName

FullName

(

)

const [virtual]

Gets the full name of this reference counting object.

By default, the full name is a concatenation of this reference counting object's name with the full name of its owning reference counting object.

Return Value: A modifiable buffer descriptor with a defined maximum length containing the full name of this reference counting object.

Inc ( )

void

Inc

(

)

[protected, inline]

Adds one to the reference count.

This function is called by the default implementation of the Open() member function of this class.

Name ( )

IMPORT_C TName

Name

(

)

const [virtual]

Gets the name of this reference counting object.

The default behaviour provided by this function depends on whether a name has been explicitly set into the object:

if a name has previously been set, then the function returns that name.

if a name has not been set, then the function builds a default name. This is fourteen characters and has the format: LOCAL-nnnnnnnn where nnnnnnnn is the hexadecimal character representation of this reference counting object's address. This default name is, therefore, guaranteed to be unique within the current process.

Return Value: A modifiable buffer descriptor with a defined maximum length containing the name of this reference counting object.

Open ( )

IMPORT_C TInt

Open

(

)

[virtual]

Opens this reference counting object.

The default behaviour increments the reference count by one and returns KErrNone. Where a derived class implements its own version of this function, it must either use the protected member function Inc() to increment the reference count or make a base call to this function.

Return Value: KErrNone.

Owner ( )

CObject *

Owner

(

)

const [inline]

Gets a pointer to the reference counting object which owns this reference counting object.

Return Value: A pointer to the owning reference counting object. This is NULL, if there is no owner.

SetName ( const TDesC * )

IMPORT_C TInt

SetName

(

const TDesC *

aName

)

Sets or clears this reference counting object's name.

To set the name, the specified descriptor must contain the name to be set. Once the name has been successfully set, then the specified source descriptor can be discarded.

To clear an existing name, specify a NULL argument.

Parameters
aName	A pointer to the descriptor containing the name to be set, or NULL if an existing name is to be cleared.

Return Value: KErrNone, if the function is successful; KerrNoMemory, if there is insufficient memory available.

Panic Codes
USER	11 if the length of aName is greater than KMaxName for a 16-bit descriptor.
USER	23 if the length of aName is greater than KMaxName for an 8-bit descriptor.

SetNameL ( const TDesC * )

IMPORT_C void

SetNameL

(

const TDesC *

aName

)

Sets or clears this reference counting object's name, and leaves on error.

To set the name, the specified descriptor must contain the name to be set. Once the name has been successfully set, then the specified source descriptor can be discarded.

To clear an existing name, specify a NULL argument.

The function leaves if there is insufficient memory.

Parameters
aName	A pointer to the descriptor containing the name to be set, or NULL if an existing name is to be cleared.

Panic Codes
USER	11 if the length of aName is greater than KMaxName for a 16-bit descriptor.
USER	23 if the length of aName is greater than KMaxName for an 8-bit descriptor.

SetOwner ( CObject * )

void

SetOwner

(

CObject *

anOwner

)

[inline]

Sets the owner of this reference counting object.

If this reference counting object already has an owner, then all knowledge of that owner is lost.

Parameters
anOwner	A pointer to the reference counting object which is to be the new owner of this reference counting object.

UniqueID ( )

TInt

UniqueID

(

)

const [protected, inline]

Gets this reference counting object's unique ID.

The unique ID is an integer which is a property of the object container. It forms part of the identity of all reference counting objects and is the same value for all reference counting objects held within the same object container.

CObject Class Reference

Inherits from

Detailed Description

Constructor & Destructor Documentation

CObject ( )

~CObject ( )

Member Function Documentation

AccessCount ( )

Close ( )

Dec ( )

Extension_ ( TUint, TAny *&, TAny * )

FullName ( )

Inc ( )

Name ( )

Open ( )

Owner ( )

SetName ( const TDesC * )

SetNameL ( const TDesC * )

SetOwner ( CObject * )

UniqueID ( )

Extension_ ( TUint, TAny &, TAny )