DHandles
A further limitation of opaque handles is that they can be too specific in cases where the action you want to perform is more generic. For example, a function that provides the name of a geometrical item should, ideally, be able to act on any of the geometry objects (ProSurface, ProEdge, ProCsys, and so on). However, the opaque handles for those different geometry items are not mutually compatible, so the Creo TOOLKIT function would also need to know the type of the object before it could internally de-reference the opaque pointer.
To solve this problem, Creo TOOLKIT defines a new, generic object type in these cases and declares it using a data handle, or DHandle. A DHandle is an explicit data structure that carries just enough information to identify a database item uniquely: the type, integer identifier, and handle to the owning model. Because the DHandle must contain the integer identifier (not the too-specific opaque handle), it also has the advantage of being persistent.
The most important examples of DHandles are ProGeomitem, which is the generic type for the geometry items previously mentioned, and ProModelitem, which is an even more generic object that includes ProGeomitem.
The declaration is as follows:
typedef struct pro_model_item
{
ProType type;
int id;
ProMdl owner;
} ProModelitem, ProGeomitem;
|
Note:
|
Although the field owner is defined using the OHandle ProMdl, and is therefore strictly speaking volatile, this handle is guaranteed to remain valid while the Creo Parametric model it refers to remains in memory.
|
The generic object ProGeomitem can represent any of the geometrical objects in a solid model, such as ProSurface, ProEdge, ProCurve, and ProCsys. The specific object types are said to be “derived from” the most generic type, and also to be “instances” of that type. The object type ProGeomitem is in turn an instance of ProModelitem, which can represent database items other than geometrical ones.
The generic object types such as
ProModelitem and
ProGeomitem are used as inputs to
Creo TOOLKIT functions whose actions are applicable to all of the more specific types of object that are instances of the generic type. For example, the function
ProGeomitemFeatureGet() has that name because it can act on any type of object that is an instance of
ProGeomitem ProSurface,
ProEdge,
ProCsys, and so on. The function
ProModelitemNameGet() is applicable to a wider range of database objects, not just geometrical ones.
If you have the OHandle to an object, such as
ProSurface, and you want to call a generic function such as
ProGeomitemFeatureGet(), you need to convert the OHandle to the more generic DHandle. Functions such as
ProGeomitemInit() and
ProModelitemInit() provide this capability. Similarly, you can convert a
ProGeomitem to a
ProSurface using the function
ProSurfaceInit(). These techniques are illustrated in
Example 3: Listing Holes in a Model, in the
Visit Functions section.