The handle-number and the object index

The handle-number is an integer which uniquely identifies a reference counting object within an object index.

Given a handle-number, a pointer to the corresponding reference counting object can be retrieved using CObjectIx::At() or CObjectIx::AtL().

Every new reference counting object that is added to the object index, is assigned an instance number; this value is incremented for every new object added to the index.

The handle-number is a TInt value which combines the instance number of the reference counting object with the index of its position within the object index's array. The combination of the two values is non-destructive, i.e. given a handle-number, both the instance part and the index part can be extracted.

Handle-numbers are guaranteed to be unique for all objects in the index. However, once an object has been removed from the index, there can be no guarantee that the same handle-number will never be re-used; the probability is low but not zero.