Searches for a registered Library Part in the loaded libraries.
GSErrCode ACAPI_LibPart_Search ( API_LibPart* ancestor, bool createIfMissing, bool onlyPlaceable = false );
- [in/out] The library part to search for
- [in] Set to true to create a reference if it is missing.
- [in] The search is limited to placeable library parts only. Optional parameter, can be omitted.
- The function has completed with success, the Library Part has been found (or reference created successfully if
- The originating library part file is missing. The document name is still filled.
- no library part is found according to the given
- no library part is found with the given document or file name
- the reference cannot be created; only when
For other common API errors see the API Errors.
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
ownUnIDfield 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
file_Namefields to empty string
- if you leave the
docu_Namefields blank, but
file_Nameis given, the function will search by the name of the library part file
file_Nameare not specified, or
docu_Nameis not an empty string
ACAPI_LibPart_Searchtries 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
parentUnIDis given, but
docu_UNameis empty, the function retrieves the first library part in the enumerated libraries which is a descendant of the specified parent subtype
typeIDbased distinction of library parts obsolete, though you may use this field for searching by subtype instead of
parentUnIDfor internal ancestor nodes (note that in this case
APILib_ObjectIDcorresponds to Model Elements, and
API_ZombieLibIDmarks 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.
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.
See the example of the ACAPI_LibPart_Create function.
- Version: API 1.3 or later
- Header: ACAPinc.h