Links one element to another.
GSErrCode ACAPI_Element_Link ( const API_Guid& guid_linkFrom, const API_Guid& guid_linkTo, GSFlags linkFlags );
- [in] Identifies the element to which the other element will be linked.
- [in] Identifies the element to link to the first element.
- [in] Custom flags to store with the link.
- The function has completed with success.
- The function must be undoable, it wasn’t called from an undoable command scope.
- The function cannot operate on the current database.
- One or both of the passed unique IDs are invalid, or the two IDs are equal.
- The elements has already been linked together.
For other common API errors see the API Errors document.
The add-on creating the link is also registered with the link; so the link “belongs” to the add-on.
The advantage of using element linking is that the server application automatically tracks changes in the GUIDs, and updates them accordingly.
After establishing a link, you can also install an element observer with a callback function, that will be called when any of the observed elements change. In this callback you can find out which other elements are linked to the observed element with ACAPI_Element_GetLinks, and retrieve the supplied
linkFlags with ACAPI_Element_GetLinkFlags. You can remove the link when you are done with ACAPI_Element_Unlink.
- Version: API 4.1 or later
- Header: ACAPinc.h