API_​Attr_​Head

Contains common information related to all attribute types.

    typedef struct {
        API_AttrTypeID     typeID;
        API_AttributeIndex index;
        short              flags;
        short              filler_0[3];
        char               name[API_AttrNameLen];
        API_Guid           guid;
        UInt64             modiTime;
        GS::UniString      *uniStringNamePtr;
    } API_Attr_Head;

 

Members

typeID
Type of the attribute; this identifies the attribute along with the index field.
Refer to the API_AttrTypeID structure to see the possible attribute types.
index
The attribute index is the current database index of the given attribute. References to any attribute are done through these indices. It goes from 1 to the maximum available attribute index for each attribute type.
flags
The attribute flags. Attribute type specific values are described in the individual attribute sections (where applicable). The following values are common for all types of attributes:

Value

Description

APIAttr_IsClientCreated 6.1

In teamwork mode, indicates whether an attribute was created by the client and not sent with the changes yet. Such an attribute can still be modified or deleted in teamwork mode (output only)

name
The name of the attribute, which appears in the appropriate dialogs.
Modified in API 11  The attribute names can be at most 256 character long.
guid Modified in API 11
The globally unique identifier (GUID) of the attribute; can be used for identifying attributes with ACAPI_Attribute_Get and ACAPI_Attribute_Search.
modiTime
The modification time of the attribute in GSTime.
uniStringNamePtr API 11
Optional parameter for accessing the name of the attribute in UniString format.

 

Remarks

This structure contains general information about an attribute. Not all the fields are applicable to all attributes; see the description of the individual attributes.

As a general rule, before calling any of the Attribute Manager functions, clear the whole structure, fill the necessary fields, then call the function. Clearing all fields in the structure is important for future compatibility; in the next API releases the fillers may have meanings.

Pen attributes normally don’t have names and their index must be between 1 and 255. There are special pen index values described at API_PenType.

API 11  Note that the generalPtr pointer has been removed from the API_Attr_Head structure. You can access long attribute names in C string format (name) or in GS::UniString format (uniStringNamePtr). For deleting more attributes with one attribute function call use ACAPI_Attribute_DeleteMore.

From ARCHICAD 11 attribute names are stored in GS::UniString format. You can use UniString format for attribute operations to avoid loss of information due to character conversion. To achieve this set the pointer of a GS::UniString variable in the uniStringNamePtr field of the API_Attr_Head structure. Otherwise always set this field to nullptr.

You can identify attributes by their GUID or name. If you want to refer to an attribute by name, set the guid member to APINULLGuid. Note that Fonts, Pens and Model View Options do not have own GUID, in their case the guid field always contains APINULLGuid. If you set uniStringNamePtr to point to a valid GS::UniString object, the content of the name character buffer is ignored.

 

Requirements

Version: API 1.3 or later
Header: APIdefs_Attributes.h

 

See Also

API_AttrTypeID
API_AttributeIndex
API_Guid
Attribute Manager
API Types
ACAPI_Attribute_Get, ACAPI_Attribute_Search, ACAPI_Attribute_DeleteMore