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
istrue
) APIERR_MISSINGDEF
- The originating library part file is missing. The document name is still filled.
APIERR_BADPARS
ancestor
isnullptr
APIERR_BADID
- no library part is found according to the given
ownUnID
,parentUnID
ortypeID
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
istrue
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 byownUnID
, set thedocu_Name
andfile_Name
fields to empty string - if you leave the
ownUnID
anddocu_Name
fields blank, butfile_Name
is given, the function will search by the name of the library part file - if
ownUnID
andfile_Name
are not specified, ordocu_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 subtypeparentUnID
- if
parentUnID
is given, butdocu_UName
is empty, the function retrieves the first library part in the enumerated libraries which is a descendant of the specified parent subtype
- if
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
See Also
API_LibPart
ACAPI_LibPart_Get, ACAPI_LibPart_Create
LibPart Manager, Library Part Subtypes
API Functions