A reference counting object can be identified by a name. A name consists of a string of characters whose length must not be greater than KMaxName, a symbol defined in e32std.h.
A name can contain any character except: *, ? and :, i.e. the characters asterisk, question mark and single colon. The system static function User::ValidateName() is available to do this.
A reference counting object can also be identified by its full name. This is descriptive of the reference counting object's ownership hierarchy, i.e. it is a name that identifies the reference counting object in the context of its owning reference counting object.
The full name is a concatenation of:
the name of the owning reference counting object,
a double colon :: ,
the name of the reference counting object.
For example, given the three CObject derived objects: x, y and z with names: one, two and three respectively, where x is owned by y and y, in turn, is owned by z:
_LIT(KTxtOne,"one"); _LIT(KTxtTwo,"two"); _LIT(KTxtThree,"three"); class CSomeClass : public CObject { ... }; ... CSomeClass* x; CSomeClass* y; CSomeClass* z; ... x = new(ELeave) CSomeClass; y = new(ELeave) CSomeClass; z = new(ELeave) CSomeClass; ... x->SetName(KTxtOne); y->SetName(KTxtTwo); z->SetName(KTxtThree); ... x->SetOwner(y); y->SetOwner(z); ...
the full name of x is, three::two::one.
the full name of y is, three::two.
the full name of z is three, the same as its name.
Names give reference counting objects an identity and are used when searching for a specific object or a group of related objects.
See also: