PK_ERROR_code_t     PK_TOPOL_ask_entities_by_attdef
(
--- received arguments ---
PK_TOPOL_t          topol,              --- topological entity
PK_CLASS_t          class,              --- class of requested entities
PK_LOGICAL_t        have_attrib,        --- whether entities have an attribute
PK_ATTDEF_t         attdef,             --- attribute definition
                                        --- ( may be PK_ENTITY_null )

--- returned arguments ---
int                *const n_entities,   --- number of entities ( >= 0 )
PK_ENTITY_t       **const entities      --- entities ( optional )
)


This function returns the set of entities of the given class which belong
to topol and either do or do not have an attribute of the given attdef,
depending upon have_attrib.


Specific Errors:
    PK_ERROR_wrong_entity       Topological entity not supported
    PK_ERROR_bad_class          Given class is invalid


At present 'topol' is restricted to be of class PK_CLASS_body.

The output array entities is optional.  If it is set to NULL, the function
will only compute the number of entities.

The function selects from all the entities belonging to the given topol by
applying two filters:

 - class:  all returned entities will belong to the given class.
           class may be:

           PK_CLASS_face
           PK_CLASS_edge
           PK_CLASS_vertex
           PK_CLASS_region
           PK_CLASS_surf   and all subclasses
           PK_CLASS_curve  and all subclasses
           PK_CLASS_point

 - attdef: entities are also selected by whether or not they have particular
           attributes.  attdef may be set to an existing attribute
           definition, in which case selection is by whether or not an entity
           has an attribute of that attribute definition, or it may be set to
           PK_ENTITY_null, meaning an attribute of any attribute definition.
           If have_attrib is set to PK_LOGICAL_true then selected entities
           will have an attribute as specified by attdef.  If have_attrib
           is set to PK_LOGICAL_false then selected entities will not have
           an attribute as specified by attdef.