Hotlink Manager

Functions related to the creation, manipulation and management of hotlink modules. More...

Classes
struct	API_HotlinkUserData
	Hotlink user data. More...
struct	API_HotlinkNode
	Describes a hotlink node. More...
class	API_HotlinkCacheGenerator
	Base class for generating the updated content of a hotlink cache. More...

Enumerations
enum	API_HotlinkTypeID { APIHotlink_Unknown = 0 , APIHotlink_Module = 1 , APIHotlink_XRef = 2 }
	Enumerates the available hotlink module types.
enum	API_HotlinkStoryRangeID { APIHotlink_SingleStory = 0 , APIHotlink_AllStories = 1 }
	Type of the hotlink by the number of linked stories. More...

Functions
GSErrCode	ACAPI_Hotlink_GetHotlinkNode (API_HotlinkNode *hotlinkNode, bool *enableUnplaced=nullptr)
	Returns a hotlink node identified by its guid.
GSErrCode	ACAPI_Hotlink_GetHotlinkStoryInfo (API_HotlinkNode *hotlinkNode)
	Creates a hotlink node without updating its cache content.
GSErrCode	ACAPI_Hotlink_CreateHotlinkNode (API_HotlinkNode *hotlinkNode)
	Gets the story info from a hotlink source file.
GSErrCode	ACAPI_Hotlink_ModifyHotlinkNode (API_HotlinkNode *hotlinkNode)
	Modifies the parameters of a hotlink node.
GSErrCode	ACAPI_Hotlink_DeleteHotlinkNode (const API_Guid *hotlinkNodeGuid)
	Deletes the given hotlink node.
GSErrCode	ACAPI_Hotlink_BreakHotlinkNode (const API_Guid *hotlinkNodeGuid)
	Breaks the link of the given hotlink node.
GSErrCode	ACAPI_Hotlink_UpdateHotlinkCache (const API_Guid *hotlinkNodeGuid, API_HotlinkCacheGenerator *hotlinkCacheGenerator=nullptr)
	Updates the cache of the given hotlink node.
GSErrCode	ACAPI_Hotlink_GetHotlinkNodes (const API_HotlinkTypeID *type, GS::Array< API_Guid > *nodeRefList, bool *enableUnplaced=nullptr)
	Returns the list of hotlink nodes.
GSErrCode	ACAPI_Hotlink_GetHotlinkRootNodeGuid (const API_HotlinkTypeID *type, API_Guid *rootNodeGuid)
	Retrieves the Guid of the Hotlink Module type or XRef type hotlink root node.
GSErrCode	ACAPI_Hotlink_GetHotlinkNodeTree (const API_Guid *hotlinkNodeGuid, GS::HashTable< API_Guid, GS::Array< API_Guid > > *hotlinkNodeTree)
	Retrieves the tree structure under a given hotlink node.
GSErrCode	ACAPI_Hotlink_GetHotlinkInstances (const API_Guid *hotlinkNodeGuid, GS::Array< API_Guid > *elementRefList)
	Returns a list of hotlink instance elements placed from the given hotlink node.
GSErrCode	ACAPI_Hotlink_GetHotLinkOwner (const API_Guid *elemGuid, API_Guid *hotlinkGuid)
	Returns the identifier of the hotlink instance the element belongs to (see API_HotlinkType).
GSErrCode	ACAPI_Hotlink_GetHotlinkProxyElementTable (const API_Guid *hotlinkGuid, GS::HashTable< API_Guid, API_Guid > *proxyElementTable)
	Returns the mapping table of the proxy elements and the source elements of the given hotlink instance.
GSErrCode	ACAPI_Hotlink_GetHotlinkSourceStatus (const IO::Location *hotlinkLocation, API_HotlinkSourceStatus *hotlinkSourceStatus)
	Returns the status of the given hotlink source file.
GSErrCode	ACAPI_Hotlink_GetContainingHotlinkGuid (const API_Guid *elemGuid, API_Guid *hotlinkElemGuid)
	Retrieves the guid of the hotlink element which contains the given element.

Detailed Description

Functions related to the creation, manipulation and management of hotlink modules.

Enumeration Type Documentation

API_HotlinkStoryRangeID

enum API_HotlinkStoryRangeID

Type of the hotlink by the number of linked stories.

Remarks

This type specifies in API_HotlinkNode whether the hotlinked

Function Documentation

ACAPI_Hotlink_BreakHotlinkNode()

GSErrCode ACAPI_Hotlink_BreakHotlinkNode

(

const API_Guid *

hotlinkNodeGuid

)

Breaks the link of the given hotlink node.

Parameters

hotlinkNodeGuid

[in] guid of the hotlink node to be broken

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - hotlinkNodeGuid parameter is nullptr.
• APIERR_BADID - hotlinkNodeGuid is invalid.
• APIERR_NEEDSUNDOSCOPE - The function must be undoable, it wasn't called from an undoable command scope.

Remarks

This function deletes the hotlink node identified by the hotlinkNodeGuid parameter. Unlike ACAPI_Hotlink_DeleteHotlinkNode the instance elements are not deleted from the project, but converted into normal elements grouped together.

ACAPI_Hotlink_CreateHotlinkNode()

GSErrCode ACAPI_Hotlink_CreateHotlinkNode

(

API_HotlinkNode *

hotlinkNode

)

Gets the story info from a hotlink source file.

Parameters

hotlinkNode

[in/out] the hotlink node which contains the location of the file

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - hotlinkNode parameter is nullptr, or sourceLocation is nullptr or invalid.

Remarks

This function is used to get the story info from a hotlink source file, usually called before creating a hotlink node with the right story settings (storyRangeType, refFloorInd). The hotlink can be APIHotlink_Module A valid sourceLocation must be specified. On success the ... of the new hotlink node returns in the guid field of the hotlinkNode parameter. Ths function does not create a hotlink node and does not changes the database.

ACAPI_Hotlink_DeleteHotlinkNode()

GSErrCode ACAPI_Hotlink_DeleteHotlinkNode

(

const API_Guid *

hotlinkNodeGuid

)

Deletes the given hotlink node.

Parameters

hotlinkNodeGuid

[in] guid of the hotlink node to be deleted

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - hotlinkNodeGuid parameter is nullptr.
• APIERR_BADID - hotlinkNodeGuid is invalid.
• APIERR_NEEDSUNDOSCOPE - The function must be undoable, it wasn't called from an undoable command scope.

Remarks

This function deletes the hotlink node identified by the hotlinkNodeGuid parameter. Unlike ACAPI_Hotlink_BreakHotlinkNode all the instance elements created from this node are removed from the project.

ACAPI_Hotlink_GetContainingHotlinkGuid()

GSErrCode ACAPI_Hotlink_GetContainingHotlinkGuid	(	const API_Guid *	elemGuid,
		API_Guid *	hotlinkElemGuid
	)

Retrieves the guid of the hotlink element which contains the given element.

Parameters

elemGuid	[in] The guid of the element.
hotlinkElemGuid	[out] The guid of the hotlink which contains the given element.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - The elemGuid or the hotlinkElemGuid parameter is nullptr
• APIERR_BADID - The passed elemGuid is invalid.

Remarks

This function is used to obtain the hotlink element which contains the given element. If the passed element is not hotlinked element, hotlinkElemGuid will be set to APINULLGuid.

ACAPI_Hotlink_GetHotlinkInstances()

GSErrCode ACAPI_Hotlink_GetHotlinkInstances	(	const API_Guid *	hotlinkNodeGuid,
		GS::Array< API_Guid > *	elementRefList
	)

Returns a list of hotlink instance elements placed from the given hotlink node.

Parameters

hotlinkNodeGuid	[in] the Guid of the hotlink node
elementRefList	[out] Guid list of the hotlink instances

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - any of the parameters is nullptr
• APIERR_BADID - no hotlink element found by the specified Guid

Remarks

This function retrieves the API_HotlinkType hotlink instance elements of the specified hotlink node.

Example

Int32 allInstancesCounter = 0;
Int32 nestedCounter = 0;
Int32 hotlinkmoduleCounter = 0;
Int32 xrefCounter = 0;
 
GS::Array<API_Guid> nodeRefList;
if (ACAPI_Database (APIDb_GetHotlinkNodesID, nullptr, &nodeRefList) == NoError) {
    for (UIndex iNode = 0; iNode < nodeRefList.GetSize (); iNode++) {
        GS::Array<API_Guid> elementRefList;
        if (ACAPI_Database (APIDb_GetHotlinkInstancesID, &nodeRefList[iNode], &elementRefList) == NoError) {
            for (UIndex iElem = 0; iElem < elementRefList.GetSize (); iElem++) {
                API_Element element;
                BNZeroMemory (&element, sizeof (API_Element));
                element.header.guid = elementRefList[iElem];
                if (ACAPI_Element_Get (&element) == NoError && element.header.type == API_HotlinkID) {
                    allInstancesCounter++;
                    if (element.header.hotlinkGuid != APINULLGuid)
                        nestedCounter++;
                    if (element.hotlink.type == APIHotlink_Module)
                        hotlinkmoduleCounter++;
                    if (element.hotlink.type == APIHotlink_XRef)
                        xrefCounter++;
                }
            }
        }
    }
}

ACAPI_Hotlink_GetHotlinkNode()

GSErrCode ACAPI_Hotlink_GetHotlinkNode	(	API_HotlinkNode *	hotlinkNode,
		bool *	enableUnplaced = nullptr
	)

Returns a hotlink node identified by its guid.

Since

Archicad 26

Parameters

hotlinkNode	[in/out] Hotlink node.
enableUnplaced	[in] True if the search is performed in all hotlink nodes (including cached ones) and false if only in placed ones.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - hotlinkNode parameter is nullptr

Remarks

This function is used to get the data of the specified hotlink node.

Example

Hotlink-related code samples can be found in the Element_Test
 
example add-on.

ACAPI_Hotlink_GetHotlinkNodes()

GSErrCode ACAPI_Hotlink_GetHotlinkNodes	(	const API_HotlinkTypeID *	type,
		GS::Array< API_Guid > *	nodeRefList,
		bool *	enableUnplaced = nullptr
	)

Returns the list of hotlink nodes.

Since

Archicad 26

Parameters

type	[in] optional type selector ( APIHotlink_Module or APIHotlink_XRef), if this variable is nullptr, all nodes are collected
nodeRefList	[out] the list of hotlink nodes found in the project
enableUnplaced	[in] True if the search is performed in all hotlink nodes (including cached ones) and false if only in placed ones.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - the nodeRefList parameter is nullptr

Remarks

This function returns the hotlink nodes as a list of Guids. The data of a hotlink node can be retrieved with the ACAPI_Hotlink_GetHotlinkNode function. To explore a nested node hierarchy, use ACAPI_Hotlink_GetHotlinkNodeTree. In order to get the hotlink instances placed in the project, use the ACAPI_Hotlink_GetHotlinkInstances function.

Example

See the examples section of APIDb_GetHotlinkInstancesID
. Further hotlink-related code samples can be found in the Element_Test
 
example add-on.

ACAPI_Hotlink_GetHotlinkNodeTree()

GSErrCode ACAPI_Hotlink_GetHotlinkNodeTree	(	const API_Guid *	hotlinkNodeGuid,
		GS::HashTable< API_Guid, GS::Array< API_Guid > > *	hotlinkNodeTree
	)

Retrieves the tree structure under a given hotlink node.

Parameters

hotlinkNodeGuid	[in] Guid of the parent node
hotlinkNodeTree	[out] the tree structure under the given parent node

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - any of the parameters is nullptr

Remarks

This function helps to explore the nested node hierarchy of hotlinks used in the project. The structure is presented in a hashtable of parent node and array of children nodes pairs. The top node of the tree is defined by the hotlinkNodeGuid parameter, which is usually either the Hotlink Module type or the XRef type hotlink root node (these can be retrieved with the ACAPI_Hotlink_GetHotlinkRootNodeGuid function), however it can be any of the nodes when only a sub-tree is requested.

Example

API_HotlinkTypeID type = APIHotlink_Module;
API_Guid hotlinkRootNodeGuid = APINULLGuid;
if (ACAPI_Database (APIDb_GetHotlinkRootNodeGuidID, &type, &hotlinkRootNodeGuid) == NoError) {
    GS::HashTable<API_Guid, GS::Array<API_Guid> > hotlinkNodeTree;
    if (ACAPI_Database (APIDb_GetHotlinkNodeTreeID, &hotlinkRootNodeGuid, &hotlinkNodeTree) == NoError) {
        if (hotlinkNodeTree.ContainsKey (hotlinkRootNodeGuid)) {
            ACAPI_WriteReport ("List of main level hotlink nodes:", false);
            const GS::Array<API_Guid>& nodeRefList = hotlinkNodeTree.Get (hotlinkRootNodeGuid);
            for (UInt32 i = 0; i < nodeRefList.GetSize (); i++) {
                char guidStr[64];
                APIGuid2GSGuid (nodeRefList[i]).ConvertToString (guidStr);
                ACAPI_WriteReport (guidStr, false);
            }
        } else {
            ACAPI_WriteReport ("No hotlink node was found", false);
        }
    }
}

ACAPI_Hotlink_GetHotLinkOwner()

GSErrCode ACAPI_Hotlink_GetHotLinkOwner	(	const API_Guid *	elemGuid,
		API_Guid *	hotlinkGuid
	)

Returns the identifier of the hotlink instance the element belongs to (see API_HotlinkType).

Parameters

elemGuid	[in] The Guid of the element.
hotlinkGuid	[out] The hotlink instance the element belongs to. APINULLGuid means the element is not part of any hotlinks.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - Any of the parameters is nullptr
• APIERR_BADID - The elemGuid is invalid or the element is deleted.

Remarks

This function retrieves the identifier of the hotlink (API_HotlinkType) instance the incoming element belongs to.

ACAPI_Hotlink_GetHotlinkProxyElementTable()

GSErrCode ACAPI_Hotlink_GetHotlinkProxyElementTable	(	const API_Guid *	hotlinkGuid,
		GS::HashTable< API_Guid, API_Guid > *	proxyElementTable
	)

Returns the mapping table of the proxy elements and the source elements of the given hotlink instance.

Since

Archicad 25

Parameters

hotlinkGuid	[in] The guid of the hotlink instance.
proxyElementTable	[out] A hashtable in which the keys are the proxy elements in the current project and the values are the source elements from the hotlinked project.

Returns

• NoError - The function has completed with success.
• APIERR_NOPLAN - There is no opened project.
• APIERR_BADID - The hotlinkGuid is invalid, it does not refer to an element.
• APIERR_BADELEMENTTYPE - The hotlinkGuid does not belong to a hotlink instance.

ACAPI_Hotlink_GetHotlinkRootNodeGuid()

GSErrCode ACAPI_Hotlink_GetHotlinkRootNodeGuid	(	const API_HotlinkTypeID *	type,
		API_Guid *	rootNodeGuid
	)

Retrieves the Guid of the Hotlink Module type or XRef type hotlink root node.

Parameters

type	[in] hotlink type selector ( APIHotlink_Module or APIHotlink_XRef)
rootNodeGuid	[out] the Guid of the selected root node

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - any of the parameters is nullptr
• APIERR_BADID - the type parameter is neither APIHotlink_Module nor APIHotlink_XRef

Remarks

This function retrieves the Guid identifier of the root hotlink node of the selected type. This root node is not a real hotlink node, it actually represents the project itself, and can be used as the parent of the main-level hotlinks when the whole structure is requested with the ACAPI_Hotlink_GetHotlinkNodeTree function.

Example

See the examples section of APIDb_GetHotlinkNodeTreeID
. Further hotlink-related code samples can be found in the Element_Test
 
example add-on.

ACAPI_Hotlink_GetHotlinkSourceStatus()

GSErrCode ACAPI_Hotlink_GetHotlinkSourceStatus	(	const IO::Location *	hotlinkLocation,
		API_HotlinkSourceStatus *	hotlinkSourceStatus
	)

Returns the status of the given hotlink source file.

Parameters

hotlinkLocation	[in] The location of the hotlink file.
hotlinkSourceStatus	[out] The status (availability) of the hotlink.

Returns

• NoError - The function has completed with success.
• APIERR_NOPLAN - There is no opened project.
• APIERR_REFUSEDPAR - The hotlink location is invalid, or the location does not point to a hotlink.
• APIERR_BADELEMENTTYPE - The hotlinkGuid does not belong to a hotlink instance.

ACAPI_Hotlink_GetHotlinkStoryInfo()

GSErrCode ACAPI_Hotlink_GetHotlinkStoryInfo

(

API_HotlinkNode *

hotlinkNode

)

Creates a hotlink node without updating its cache content.

Parameters

hotlinkNode

[in/out] the hotlink node to be created

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - hotlinkNode parameter is nullptr, or sourceLocation is nullptr or invalid.

Remarks

This function is used to add a new hotlink node to the project. The hotlink can be either APIHotlink_Module or APIHotlink_XRef type A valid sourceLocation must be specified. On success the Guid of the new hotlink node returns in the guid field of the hotlinkNode parameter. Creating a hotlink node does not make the hotlinked content appear in the project. This simply creates a reference to the source module file, and prepares a cache which contains the elements and attributes as an image of the original source. In order to place a hotlink instance on the plan, you need to create an API_HotlinkType element referring to this hotlink node with the appropriate hotlinkNodeGuid identifier. Note that XRefs are handled by the DXF/DWG add-on, and the format of their userdata is not published. This function is a non-undoable data structure modifier function. See more details on this topic at Command Overview.

ACAPI_Hotlink_ModifyHotlinkNode()

GSErrCode ACAPI_Hotlink_ModifyHotlinkNode

(

API_HotlinkNode *

hotlinkNode

)

Modifies the parameters of a hotlink node.

Parameters

hotlinkNode

[in] hotlink node data to be changed

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - hotlinkNode parameter is nullptr.
• APIERR_BADID - guid of hotlinkNode is invalid.

Remarks

This function is used to modify the data of a hotlink node. The node is identified by the guid member of the hotlinkNode parameter. Only the sourceLocation, ownerId and userData parameters can be modified. This function is a non-undoable data structure modifier function. See more details on this topic at Command Overview.

ACAPI_Hotlink_UpdateHotlinkCache()

GSErrCode ACAPI_Hotlink_UpdateHotlinkCache	(	const API_Guid *	hotlinkNodeGuid,
		API_HotlinkCacheGenerator *	hotlinkCacheGenerator = nullptr
	)

Updates the cache of the given hotlink node.

Parameters

hotlinkNodeGuid	[in] guid of the hotlink node
hotlinkCacheGenerator	[in] optional cache content generator object

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - hotlinkNodeGuid parameter is nullptr
• APIERR_BADID - hotlinkNodeGuid is invalid

Remarks

This function is used to update the cache of a hotlink node. If the hotlink content is supposed to be generated by the add-on, you need to pass a generator object. The GenerateCacheContentForHotlinkNode method of API_HotlinkCacheGenerator must be implemented to create the new (updated) content of the specified hotlink cache. When this method is called back from the ACAPI_Hotlink_UpdateHotlinkCache function, the standard element and attribute creator functions (like ACAPI_Element_Create and ACAPI_Attribute_Create) are redirected to create elements and attributes into the hotlink cache database, rather than the project database. This function is a non-undoable data structure modifier function. See more details on this topic at Command Overview.

Example

See the examples section of API_HotlinkCacheGenerator
. Further hotlink-related code samples can be found in the Element_Test
 
example add-on.