Links one element to another.

    GSErrCode  ACAPI_Element_Link (
        const API_Guid&  guid_linkFrom,
        const API_Guid&  guid_linkTo,
        GSFlags          linkFlags
    );

 

Parameters

guid_linkFrom 

[in] Identifies the element to which the other element will be linked.

guid_linkTo 

[in] Identifies the element to link to the first element.

linkFlags

[in] Custom flags to store with the link.

 

Return Values

NoError

The function has completed with success.

APIERR_NEEDSUNDOSCOPE

The function must be undoable, it wasn’t called from an undoable command scope.

APIERR_BADDATABASE, APIERR_NOTMINE

The function cannot operate on the current database.

APIERR_BADID

One or both of the passed unique IDs are invalid, or the two IDs are equal.

APIERR_LINKEXIST

The elements has already been linked together.

For other common API errors see the API Errors document.

 

Remarks

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.

 

Requirements

Version: API 4.1 or later

Header: ACAPinc.h

 

See Also

ACAPI_Element_Unlink, ACAPI_Element_GetLinks, ACAPI_Element_GetLinkFlags,
API Functions