The acdbHandEnt() function retrieves the name of an entity with a specific handle. Like entity names, handles are unique within a drawing. Unlike entity names, an entity's handle is constant throughout its life. ObjectARX applications that manipulate a specific database can use acdbHandEnt() to obtain the current name of an entity they must use.
The following sample code fragment uses acdbHandEnt() to obtain an entity name and to print it out.
char handle[17];
ads_name e1;
strcpy(handle, "5a2");
if (acdbHandEnt(handle, e1) != RTNORM)
acdbFail("No entity with that handle exists\n");
else
acutPrintf("%ld", e1[0]);
In one particular editing session, this code might print out 60004722. In another editing session with the same drawing, it might print an entirely different number. But in both cases, the code is accessing the same entity.
The acdbHandEnt() function has an additional use: entities deleted from the database (with acdbEntDel()) are not purged until you leave the current drawing (by exiting AutoCAD or switching to another drawing). This means that acdbHandEnt() can recover the names of deleted entities, which can then be restored to the drawing by a second call to acdbEntDel().
Entities in drawings cross-referenced with XREF Attach are not actually part of the current drawing; their handles are unchanged and cannot be accessed by acdbHandEnt(). However, when drawings are combined by means of INSERT, INSERT *, XREF Bind (XBIND), or partial DXFIN, the handles of entities in the incoming drawing are lost, and incoming entities are assigned new handle values to ensure that each handle in the original drawing remains unique.