Class CObjectCon

CObjectCon

Support

Supported from 5.0

Description

An object container.

An object container acts as a home for a set of related reference counting objects.

A reference counting object, a CObject type, must be added to an object container. Only one instance of a given reference counting object can be held by an object container, i.e. each object within an object container must be distinct.

Object containers are constructed by an object container index, a CObjectConIx type.

Note that this class is not intended for user derivation.

Derivation

CBase Base class for all classes to be instantiated on the heap CObjectCon An object container

Defined in CObjectCon:
AddL(), At(), AtL(), CheckUniqueFullName(), Count(), FindByFullName(), FindByName(), NewL(), Remove(), UniqueID(), operator[](), ~CObjectCon()

Inherited from CBase:
operator new()

See also:

• CObject
• CObjectConIx

static CObjectCon* NewL();

Description

Creates an object container.

Open code rarely, if ever, explicitly calls this function. Instead, call the CreateL() member function of the container index, CObjectConIx, which uses this function in its implementation.

Return value

CObjectCon* A pointer to the new object container.

See also:

• CObjectConIx::CreateL()

~CObjectCon();

Description

Frees all resources owned by the object container, prior to its destruction.

In particular, it destroys all contained reference counting objects (CObject types).

void AddL(CObject* anObj);

Description

Adds a reference counting object to this object container.

If the specified reference counting object has a name, it must be valid, otherwise the function leaves with KErrBadName; in addition, the reference counting object's full name must be unique to this object container, otherwise the function leaves with KErrAlreadyExists.

If the specified reference counting object has no name, then the object itself must be unique to the object container, i.e. the object container should not already contain the same reference counting object, otherwise the function leaves with KErrAlreadyExists.

Parameters

CObject* anObj A pointer to the reference counting object to be added.

void Remove(CObject* anObj);

Description

Removes a reference counting object from this object container

The specified reference counting object is destroyed on removal.

If the reference counting object is not held by this object container, then the function raises an E32USER-CBase 35 panic.

Parameters

CObject* anObj A pointer to the reference counting object to be removed.

TInt CheckUniqueFullName(const CObject* anObject) const;

Description

Checks that the specified reference counting object does not already exist in this object container.

Uniqueness is decided by name, if the object has a name, otherwise by pointer.

If the reference counting object has a name, then it is unique only if there is no other reference counting object in the container with the same full name.

If the reference counting object has no name, then it is unique only if there is no other reference counting object in the container with the same pointer.

Parameters

const CObject* anObject A pointer to the reference counting object to be checked.

Return value

TInt KErrNone, if the reference counting object does not already exist in this object container; KErrBadName, if the name of the reference counting object is invalid; KErrAlreadyExists, if the reference counting object already exists.

TInt CheckUniqueFullName(const CObject* anOwner,const TDesC& aName) const;

Description

Checks that a name will be unique.

The function checks that no reference counting object exists in this object container with the same full name as that generated from the specified name and the specified owning reference counting object.

This is a useful test to ensure that the name for a potential new reference counting object will result in a unique full name.

Parameters

const CObject* anObject A pointer to a potential owning reference counting object. const TDesC& aName The name for a potential new reference counting object.

Return value

TInt KErrNone, if the full name does not already exist in this object container; KErrBadName, if the specified name is invalid; KErrAlreadyExists, if a reference counting object with the same fullname as the generated one already exists in this object container.

CObject* operator[](TInt anIndex);

Description

Gets a pointer to a reference counting object located at the specified offset within the object container.

Parameters

TInt anIndex The offset of the reference counting object within the object container. Offset is relative to zero. This value must be greater than or equal to zero and it must be less than the total number of objects held by the container, otherwise the operator raises an E32USER-CBase 21 panic.

Return value

CObject* A pointer to the owning reference counting object.

CObject* At(TInt aFindHandle) const;

Description

Gets a pointer to the reference counting object with the specified find-handle number.

A find-handle number is an integer which uniquely identifies a reference counting object with respect to its object container.

Parameters

TInt aFindHandle The find-handle number of the reference counting object. The unique Id part of this number must be the same as the unique Id of this container, otherwise the function raises an E32User-CBase 38 panic. The index part of the find-handle number must be a valid index, i.e. its value must be greater than or equal to zero and less than the total number of reference counting objects held by this object container, otherwise the function raises an E32User-CBase 39 panic.

Return value

CObject* anOwner A pointer to the reference counting object.

CObject* AtL(TInt aFindHandle) const;

Description

Gets a pointer to the reference counting object with the specified find-handle number.

A find-handle number is an integer which uniquely identifies a reference counting object with respect to its object container.

Parameters

TInt aFindHandle The find-handle number of the reference counting object. The unique Id part of this number must be the same as the unique Id of this container, otherwise the function leaves with KErrBadHandle. The index part of the find-handle number must be a valid index, i.e. its value must be greater than or equal to zero and less than the total number of reference counting objects held by this object container, otherwise the function leaves with KErrArgument.

Return value

CObject* anOwner A pointer to the reference counting object.

TInt FindByName(TInt& aFindHandle,const TDesC& aMatch,TName& aName) const;

Description

Searches for the reference counting object whose name matches the specified match pattern.

The search starts at the reference counting object following the one associated with the specified find-handle number. If the specified find-handle number is zero, then searching starts at the beginning of the object container.

Notes:

• names are folded for the purpose of pattern matching

• if the specified find-handle number is non-zero, then the unique Id part of the number must be the same as the unique Id of this container, otherwise the function raises an E32User-CBase 38 panic.

Parameters

TInt& aFindHandle On entry, contains the find-handle number of a reference counting object from where searching is to start or zero. On return, if an object is found, then this is set to the find-handle number of that object; if no object is found, then this is set to a generated number, the index part of which has the value 0x7fff. If the object container is empty, then this reference is not changed. const TDesC& aMatch The match pattern. TName& aName A modifiable buffer descriptor with a defined maximum length. On return, if an object is found, then this contains the name of that object; if no object is found, then the length of this descriptor is set to zero. If the object container is empty, then this reference is not changed.

Return value

TInt KErrNone, if a matching reference counting object is found; KErrNotFound, if no matching reference counting object can be found or the object container is empty.

TInt FindByFullName(TInt& aFindHandle,const TDesC& aMatch,TFullName& aFullName) const;

Description

Searches for the reference counting object whose full name matches the specified match pattern.

The search starts at the reference counting object following the one associated with the specified find-handle number. If the specified find-handle number is zero, then searching starts at the beginning of the object container.

Notes:

• names are folded for the purpose of pattern matching

• if the specified find-handle number is non-zero, then the unique Id part of the number must be the same as the unique Id of this container, otherwise the function raises an E32User-CBase 38 panic.

Parameters

TInt& aFindHandle On entry, contains the find-handle number of a reference counting object from where searching is to start or zero. On return, if an object is found, then this is set to the find-handle number of that object; if no object is found, then this is set to a generated number, the index part of which has the value 0x7fff. If the object container is empty, then this reference is not changed. const TDesC& aMatch The match pattern. TFullName& aFullName A modifiable buffer descriptor with a defined maximum length. On return, if an object is found, then this contains the full name of that object; if no object is found, then the length of this descriptor is set to zero. If the object container is empty, then this reference is not changed.

Return value

TInt KErrNone, if a matching reference counting object is found; KErrNotFound, if no matching reference counting object can be found or the object container is empty.

TInt UniqueID() const;

Description

Gets this object container's unique ID.

Parameters

TInt The unique ID value.

TInt Count() const;

Description

Gets the number of reference counting objects in this object container.

Parameters

TInt The number of objects.