ACAPI_Attribute_Get |

Retrieves an attribute from the database.

    GSErrCode  ACAPI_Attribute_Get (
        API_Attribute*     attribute
    );

Parameters

attribute: [in/out] Parameters of the attribute. The type and the index or the name of the attribute must be passed in the typeID and index, or in the typeID and name fields in the attribute header. The data of the attribute is returned in the appropriate fields of the API_Attribute structure.

Return Values

NoError: The function has completed with success.
APIERR_BADPARS: The passed parameter (attribute) is nullptr
APIERR_BADID: The attribute type is invalid
APIERR_BADINDEX: The attribute index is invalid; if referenced by index
APIERR_BADNAME: The attribute with the given name doesn’t exist; if referenced by name
APIERR_DELETED: The attribute doesn’t exist in the database.

For other common API errors see the API Errors document.

Remarks

This function is used to retrieve one attribute’s data from the database. Beside the typeID, you should specify either the index or the name field of the header. In the latter case, the index field should be set to zero, and the attribute database is searched by name.

You may optionally call ACAPI_Attribute_GetDef to get extended information for certain attribute types.

The index range is not always continuous; deleted attributes are not purged immediately from the database.

Note: The received attributes can have dynamically allocated members depending on the typeID. They should be disposed when they are no more needed.

API_MaterialID: attribute.material.texture.fileLoc
API_ModelViewOptionsID: attribute.modelViewOpt.modelViewOpt.gdlOptions

Note: Special pen IDs can be used:

1000: returns the color of the grid line
1001: returns the color of the zone stamp
1002: returns the color of the ghost story

Example


/* Example I -- get an attribute */
API_Attribute     attrib;
GSErrCode         err;

BNZeroMemory (&attrib, sizeof (API_Attribute));

/* get the "Wave" line type */
attrib.header.typeID = API_LinetypeID;
CHCopyC ("Wave", attrib.header.name);

err = ACAPI_Attribute_Get (&attrib);



/* Example II -- loop through all attributes of a kind */
API_Attribute  attrib;
short          nLin, i;
GSErrCode      err;

BNZeroMemory (&attrib, sizeof (API_Attribute));
attrib.header.typeID = API_LinetypeID;
err = ACAPI_Attribute_GetNum (API_LinetypeID, &nLin);
for (i = 1; i <= nLin && err == NoError; i++) {
    attrib.header.index = i;
    err = ACAPI_Attribute_Get (&attrib);
    if (err == NoError) {
        /* do what you want */
    }
    if (err == APIERR_DELETED)
        err = NoError;
}

Requirements

Version: API 1.3 or later

Header: ACAPinc.h

Parameters

Return Values

Remarks

Example

Requirements

See Also