PK_ENTITY_ask_description

PK_ERROR_code_t   PK_ENTITY_ask_description
(
--- received arguments ---
int                                      tag, --- PK entity or internal tag
const PK_ENTITY_ask_description_o_t *options, --- options structure

--- returned arguments ---
char **const                     description  --- ptr to null terminated string
)


This function returns a textual description of Parasolid's internal
representation of a PK entity


Specific Errors:

    PK_ERROR_not_a_tag                  Not value of external or internal tag



The function is first called with 'tag' set to the value of a PK entity.

This returns a null terminated string which describes Parasolid's internal
representation of the entity. If the tag value is set to PK_ENTITY_null,
an empty string is returned, containing the single null character '\0'.

The application can traverse an entity's underlying structure by scanning the
descriptive text for integer tags (described later) and calling this function
with the derived tag values.

The tags will either be 'external' types belonging to one of the PK classes
              PK_ENTITY_t, PK_MARK_t, PK_PARTITION_t, PK_PMARK_t
or 'internal' Parasolid tags which do not belong to any of these PK classes.
The application can detect such cases using the classification functions
        PK_ENTITY_is, PK_MARK_is, PK_PARTITION_is, PK_PMARK_is

The returned text is divided into lines, each terminated by a '\n' character.

The first line of text contains a summary description of the tag. If the tag
belongs to the PK_ENTITY class, this will start with the name of its concrete
class. If it belongs to another PK class, the description will start with this
class name. In other cases the description will start with the word 'Internal'.

The remainder of the description contains the names and values of constituent
fields within the tag, followed by internal status data.

The field names and values are separated by a ':' character. Field values may
be continued on a following line. The relative ordering of the field / value
pairs within the descriptive string is subject to change.
If a field name refers to a tag, its value is written out in the form    #NNN
where the 'NNN' represents an integer containing one or more decimal digits.

The content and layout of internal status data at the end of the descriptive
string is subject to change. This is provided solely for debugging purposes.

The returned 'description' character pointer will refer to memory which has
been allocated by the registered PK memory allocator function. This must be
freed by the application after each call to this function.