ACAPI_LibPart_Search |

Searches for a registered Library Part in the loaded libraries.

    GSErrCode  ACAPI_LibPart_Search (
        API_LibPart*     ancestor,
        bool             createIfMissing,
        bool             onlyPlaceable = false
    );

Parameters

ancestor: [in/out] The library part to search for
createIfMissing: [in] Set to true to create a reference if it is missing.
onlyPlaceable: [in] The search is limited to placeable library parts only. Optional parameter, can be omitted.

Return Values

NoError: The function has completed with success, the Library Part has been found (or reference created successfully if createIfMissing is true)
APIERR_MISSINGDEF: The originating library part file is missing. The document name is still filled.
APIERR_BADPARS: ancestor is nullptr
APIERR_BADID: no library part is found according to the given ownUnID, parentUnID or typeID parameters
APIERR_BADNAME: no library part is found with the given document or file name
APIERR_MEMFULL: the reference cannot be created; only when createIfMissing is true

For other common API errors see the API Errors.

Remarks

This function is used to search a Library Part in the loaded libraries.

The Library Part can be referenced by the following criteria:

the most exact identification of a library part is the global unique ID. You can copy the unique ID string of the requested library part into the ownUnID field of the API_LibPart structure. Since the revision part of the unique ID can be changed by minor modifications (see Library Part Subtypes for more details), only main GUID match can meet the condition. If you search by ownUnID, set the docu_Name and file_Name fields to empty string
if you leave the ownUnID and docu_Name fields blank, but file_Name is given, the function will search by the name of the library part file
if ownUnID and file_Name are not specified, or docu_Name is not an empty string
- if docu_Name is given, ACAPI_LibPart_Search tries to find a library part with that document name. Note that document names are not unique. You may reduce the chance of mismatch if you also specify the subtype parentUnID
- if parentUnID is given, but docu_UName is empty, the function retrieves the first library part in the enumerated libraries which is a descendant of the specified parent subtype

Please remember that library parts are classified according to the subtype hierarchy as it is explained in the Library Part Subtypes chapter of this documentation. The expandable subtype system made the typeID based distinction of library parts obsolete, though you may use this field for searching by subtype instead of parentUnID for internal ancestor nodes (note that in this case APILib_ObjectID corresponds to Model Elements, and API_ZombieLibID marks the General Object subtype).

ACAPI_LibPart_Search can also create a virtual reference to a none existing library part (i.e. an index which can be referred to) if the library part has not found in the active libraries and createIfMissing was set true). Same effect appears when an opened plan refers to a library part which is not in the active libraries. In this case Archicad places a filled circle on the plan where a missing library part is referenced.

On success ACAPI_LibPart_Search fills out all the fields of the API_LibPart structure, therefore remember to free the location pointer allocated by the function if you do not not need it any more.

Example

See the example of the ACAPI_LibPart_Create function.

Requirements

Version: API 1.3 or later

Header: ACAPinc.h

Parameters

Return Values

Remarks

Example

Requirements

See Also