Functions for creating, handling and deleting custom (Add-On specific), Teamwork-safe Add-On Objects. These Objects provide a safer way to handle custom data than the legacy ModulData. More...

Classes
struct	API_AddonObject
	Control information of a custom data stored into the project database. More...

Typedefs
typedef GSErrCode __ACENV_CALL	APIAddonObjectSaveOldFormatHandlerProc(API_FTypeID planFileType, const GS::Array< API_AddonObject > &currentFormatAddOnObjectArray, GS::Array< API_AddonObject > &oldFormatAddOnObjectArray)
	User supplied callback procedure for converting AddOnObjects into previous format.

typedef GSErrCode __ACENV_CALL	APIAddonObjectConvertNewFormatHandlerProc(API_FTypeID planFileType, const GS::Array< API_AddonObject > &oldFormatAddOnObjectArray, GS::Array< API_AddonObject > &currentFormatAddOnObjectArray)
	User supplied callback procedure for converting AddOnObjects into current format.

typedef GSErrCode __ACENV_CALL	APIAddonObjectMergeHandlerProc(const GS::Array< API_AddonObject > &sourceAddOnObjectArray)
	User supplied callback procedure for handling AddOnObject merge operations.

Enumerations
enum	API_AddonObjectType { GeneralAddOnObject , UniqueAddOnObject , ClientOnlyAddOnObject }
	Represents the two types of an AddOnObject: general (non-unique) and unique.

Functions
GSErrCode __ACENV_CALL	ACAPI_AddOnObject_RegisterAddOnObjectHandler (void)
	Registers the add-on to be called for merging and converting its custom data stored in AddOnObjects.

GSErrCode __ACENV_CALL	ACAPI_AddOnObject_InstallAddOnObjectMergeHandler (APIAddonObjectMergeHandlerProc *mergeHandlerProc)
	Installs a callback procedure for handling the AddOnObject merge operations.

GSErrCode __ACENV_CALL	ACAPI_AddOnObject_InstallAddOnObjectSaveOldFormatHandler (APIAddonObjectSaveOldFormatHandlerProc *saveOldFormatProc)
	Installs a callback procedure for converting AddOnObject data into older format.

GSErrCode __ACENV_CALL	ACAPI_AddOnObject_InstallAddOnObjectConvertNewFormatHandler (APIAddonObjectConvertNewFormatHandlerProc *convertNewFormatProc)
	Installs a callback procedure for converting old format AddOnObject data into current format.

GSErrCode __ACENV_CALL	ACAPI_AddOnObject_CreateObject (const GS::UniString &objectName, const GSHandle &content, API_Guid *objectGuid)
	Creates an AddOnObject.

GSErrCode __ACENV_CALL	ACAPI_AddOnObject_CreateUniqueObject (const GS::UniString &objectName, API_Guid *objectGuid)
	Creates a Unique AddOnObject.

GSErrCode __ACENV_CALL	ACAPI_AddOnObject_CreateUniqueObjectMore (const GS::Array< GS::UniString > &objectNames, GS::Array< API_Guid > &objectGuids)
	Creates more Unique AddOnObjects.

GSErrCode __ACENV_CALL	ACAPI_AddOnObject_CreateClientOnlyObject (const GS::UniString &objectName, const GSHandle &content, API_Guid *objectGuid)
	Creates an AddOnObject.

GSErrCode __ACENV_CALL	ACAPI_AddOnObject_GetObjectList (GS::Array< API_Guid > *objects)
	Returns the list of the AddOnObjects.

GSErrCode __ACENV_CALL	ACAPI_AddOnObject_GetObjectContent (const API_Guid &objectGuid, GS::UniString objectName, GSHandle objectContent)
	Retrieves the content and the name of the specified AddOnObject from the project database.

GSErrCode __ACENV_CALL	ACAPI_AddOnObject_ModifyObject (const API_Guid &objectGuid, const GS::UniString newObjectName, const GSHandle newObjectContent)
	Modifies the content and/or the name of the specified AddOnObject.

GSErrCode __ACENV_CALL	ACAPI_AddOnObject_DeleteObject (const API_Guid &objectGuid)
	Retrieves an attribute from the database.

GSErrCode __ACENV_CALL	ACAPI_AddOnObject_GetObjectGuidFromName (const GS::UniString &name, API_Guid *objectGuid)
	Returns the GUID of the specified object.

GSErrCode __ACENV_CALL	ACAPI_AddOnObject_GetUniqueObjectGuidFromName (const GS::UniString &name, API_Guid *objectGuid)
	Returns the GUID of the specified Unique AddOnObject.

GSErrCode __ACENV_CALL	ACAPI_AddOnObject_GetClientOnlyObjectGuidFromName (const GS::UniString &name, API_Guid *objectGuid)
	Returns the GUID of the specified object.

GSErrCode __ACENV_CALL	ACAPI_AddOnObject_ReserveObjects (const GS::Array< API_Guid > &objectGuids, GS::HashTable< API_Guid, short > *conflicts)
	In teamwork mode this function reserves the specified objects.

GSErrCode __ACENV_CALL	ACAPI_AddOnObject_ReleaseObjects (const GS::Array< API_Guid > &objectGuids)
	In teamwork mode this function releases the specified objects.

GSErrCode __ACENV_CALL	ACAPI_AddOnObject_RequestObjects (const GS::Array< API_Guid > &objectGuids, const GS::UniString &mailText)
	In teamwork mode this function sends a request mail in order to request the specified objects from the owners.

GSErrCode __ACENV_CALL	ACAPI_AddOnObject_GrantObjects (const GS::Array< API_Guid > &objectGuids, short toUserId)
	In teamwork mode this function grants the specified objects to the given user.

GSErrCode __ACENV_CALL	ACAPI_AddOnObject_GetTeamworkOwnerId (const API_Guid &objectGuid, short *ownerId)
	Returns the ownerId of the specified object in teamwork mode.

GSErrCode __ACENV_CALL	ACAPI_AddOnObject_ExistsObject (const API_Guid &objectGuid, bool *objectExists)
	Determines if the project database contains the specified AddOnObject or not.

GSErrCode __ACENV_CALL	ACAPI_AddOnObject_SetUIProperties (const API_Guid objectGuid, const GS::UniString name, const GS::UniString &localisedName, short dialogMenuStringId)
	Sets various UI properties of an AddOnObject.

Detailed Description

Functions for creating, handling and deleting custom (Add-On specific), Teamwork-safe Add-On Objects. These Objects provide a safer way to handle custom data than the legacy ModulData.

The AddOnData Manager is a service introduced in API v19.

It allows each add-on to store custom data in Archicad project database. No limitation is imposed on the structure or content, not even on the amount of saved bytes. Archicad knows nothing about its internal format, it just preserves a number of bytes in the project database and returns them upon requests.

The container of the stored data is an object called AddOnObject. This data structure has a GUID and a name. The name is optional.

AddOnobjects are identified uniquely by the GUID of the object.

Unique AddOnObjects

Unique AddOnObjects were introduced to support more restricted but safer TeamWork behaviour. Because multiple general (non-unique) AddOnObjects can exist with the same name, in TeamWork it could happen that two users created "the same" AddOnObject simultaneously, but at the end they ended up with two different AddOnObjects (with the same name). This led to a lot of confusion.

With Unique AddOnObjects - like general AddOnObjects - you can store custom data in the project database. However - unlike general AddOnObjects - their names must be and will be unique among each other. Please note that names of a Unique AddOnObject and general AddOnObjects may still be equal.

In a TeamWork project creating Unique AddOnObjects will result in a Full Send to ensure project consistency. Due to this inconvenience, it is possible to create more Unique AddOnObjects at once with the ACAPI_AddOnObject_CreateUniqueObjectMore function.

All functions that work for general AddOnObjects work for Unique AddOnObjects, too, except ACAPI_AddOnObject_GetObjectGuidFromName : to get the GUID of a Unique AddOnObject from its name use ACAPI_AddOnObject_GetUniqueObjectGuidFromName instead.

Functions

All of the ModulData Manager functions begin with the ACAPI_AddOnObject_ prefix. They are as follows:

Refer to the AddOnObject Manager example project to see detailed examples on using these functions.

Merging AddOnObjects

When merging another plan into the project, it might be necessary to keep both the original and the incoming objects, and to combine them together. Since the host application does not know the content of the objects, the owner add-on is requested to resolve the conflict.

For this purpose the add-on needs to implement an APIAddOnObjectMergeHandlerProc callback handler function, and pass the function pointer to Archicad with the For this purpose the add-on needs to implement an APIAddOnObjectMergeHandlerProc callback handler function, and pass the function pointer to Archicad with the ACAPI_AddOnObject_InstallAddOnObjectMergeHandler in the Initialize routine. It is also necessary to inform Archicad that the add-on is prepared for merging custom data: this can be done with the ACAPI_AddOnObject_RegisterAddOnObjectHandler function called from RegisterInterface. ACAPI_AddOnObject_InstallAddOnObjectMergeHandler in the Initialize routine. It is also necessary to inform Archicad that the add-on is prepared for merging custom data: this can be done with the ACAPI_AddOnObject_RegisterAddOnObjectHandler function called from RegisterInterface.

In Teamwork mode the AddOnObject can only be modified by the owner of the object. The add-on can reserve or release one or more AddOnObject using ACAPI_AddOnObject_ReserveObjects and ACAPI_AddOnObject_ReleaseObjects. Only one user can modifiy an object at one time, so no conflict resolution is needed.

Saving data into old format project

If the structure of the custom data has changed since the previous version, you need to implement an APIAddonObjectSaveOldFormatHandlerProc callback function to be able to convert your data when saving into an older format project. In order to be called this handler, the function pointer must be passed with ACAPI_AddOnObject_InstallAddOnObjectSaveOldFormatHandler, and the data handling feature must be registered with ACAPI_AddOnObject_RegisterAddOnObjectHandler.

When Archicad calls this function, the add-on should create the converted data according to the given plan file format, and pass it back to the application.

If the add-on does not install this converter callback routine, the available current format data is saved into the old version project as well.

Converting data when reading an old format project

If the structure of the custom data has changed since the older versions, you need to implement an APIAddonObjectConvertNewFormatHandlerProc callback function to be able to convert your data when opening an older format project. In order to be called this handler, the function pointer must be passed with ACAPI_AddOnObject_InstallAddOnObjectConvertNewFormatHandler, and registration with ACAPI_AddOnObject_RegisterAddOnObjectHandler is also needed.

When Archicad calls this function, the add-on should create the current version data, and pass it back to the application.

If the add-on does not install this converter callback routine, the available orignal format data will be kept in the current version project as well.

Typedef Documentation

◆ APIAddonObjectConvertNewFormatHandlerProc

typedef GSErrCode __ACENV_CALL APIAddonObjectConvertNewFormatHandlerProc(API_FTypeID planFileType, const GS::Array< API_AddonObject > &oldFormatAddOnObjectArray, GS::Array< API_AddonObject > &currentFormatAddOnObjectArray)

User supplied callback procedure for converting AddOnObjects into current format.

Parameters

planFileType	[in] The original version of the plan of the project is being opened.
oldFormatAddOnObjectArray	[in] AddOnObject data in original format.
currentFormatAddOnObjectArray	[out] Array for the converted AddOnObject data in current format.

Returns

NoError - The function has completed with success.

Remarks: In order to convert the add-on's AddOnObject data into current format, you need to implement this callback function, and pass it to Archicad with ACAPI_AddOnObject_InstallAddOnObjectConvertNewFormatHandler during the Initialize phase. It is also necessary to notify Archicad about this capability of the add-on by calling ACAPI_AddOnObject_RegisterAddOnObjectHandler from the RegisterInterface function.

◆ APIAddonObjectMergeHandlerProc

APIAddonObjectMergeHandlerProc

User supplied callback procedure for handling AddOnObject merge operations.

Parameters

sourceAddOnObjectArray [in] The list of the source AddOnObjects.

Returns

NoError - The function has completed with success.

Remarks: This is the function to be called when a file merge operation is performed. The handler function should merge the source objects into the project database by calling AddOnObject-related API functions (e.g. ACAPI_AddOnObject_ModifyObject).

◆ APIAddonObjectSaveOldFormatHandlerProc

typedef GSErrCode __ACENV_CALL APIAddonObjectSaveOldFormatHandlerProc(API_FTypeID planFileType, const GS::Array< API_AddonObject > &currentFormatAddOnObjectArray, GS::Array< API_AddonObject > &oldFormatAddOnObjectArray)

User supplied callback procedure for converting AddOnObjects into previous format.

Parameters

planFileType	[in] The old format plan version the project is being saved.
currentFormatAddOnObjectArray	[in] AddOnObject data in current format.
oldFormatAddOnObjectArray	[out] Array for the converted AddOnObject data in old format.

Returns

NoError - The function has completed with success.

Remarks: In order to save the add-on's AddOnObject data in the proper format into a previous version project file, you need to implement this callback function, and pass it to Archicad with ACAPI_AddOnObject_InstallAddOnObjectSaveOldFormatHandler during the Initialize phase. It is also necessary to notify Archicad about this capability of the add-on by calling ACAPI_AddOnObject_RegisterAddOnObjectHandler from the RegisterInterface function.

Function Documentation

◆ ACAPI_AddOnObject_CreateClientOnlyObject()

GSErrCode __ACENV_CALL ACAPI_AddOnObject_CreateClientOnlyObject	(	const GS::UniString &	objectName,
		const GSHandle &	content,
		API_Guid *	objectGuid
	)

Creates an AddOnObject.

Parameters

objectName	[in] The name of the AddOnObject.
content	[in] The content of the AddOnObject.
objectGuid	[out] The GUID of the created object.

Returns

NoError - The function has completed with success.

Remarks: This function is used to store custom data into project database. The custom data is represented by AddOnObject. This data is avaible in teamwork only in clinet side, it won't be send to the teamwork server. If you need to ensure that the AddOnObject send between users use ACAPI_AddOnObject_CreateObject. The content handle will be copied inside the function so it has to be deleted after the function call. The stored data can be accessed using objectGuid parameter. The objectName parameter can also be used for identifying the custom data. It can be also emtpy. Archicad does not check if the name is unique. If you need to ensure that only one AddOnObject exists with the same name, then use Unique AddOnObjects. See more: ACAPI_AddOnObject_CreateUniqueObject. The content handle will be copied inside the function so it has to be deleted after the function call. The stored data can be accessed using objectGuid parameter. The objectName parameter can also be used for identifying the custom data. It can be also emtpy. Archicad does not check if the name is unique. If you need to ensure that only one AddOnObject exists with the same name, then use Unique AddOnObjects. See more: ACAPI_AddOnObject_CreateUniqueObject.

◆ ACAPI_AddOnObject_CreateObject()

GSErrCode __ACENV_CALL ACAPI_AddOnObject_CreateObject	(	const GS::UniString &	objectName,
		const GSHandle &	content,
		API_Guid *	objectGuid
	)

Creates an AddOnObject.

Parameters

objectName	[in] The name of the AddOnObject.
content	[in] The content of the AddOnObject.
objectGuid	[out] The GUID of the created object.

Returns

NoError - The function has completed with success.

Remarks: This function is used to store custom data into project database. The custom data is represented by AddOnObject. This data is avaible in teamwork only in clinet side, it won't be send to the teamwork server. If you need to ensure that the AddOnObject send between users use ACAPI_AddOnObject_CreateObject. The content handle will be copied inside the function so it has to be deleted after the function call. The stored data can be accessed using objectGuid parameter. The objectName parameter can also be used for identifying the custom data. It can be also emtpy. Archicad does not check if the name is unique. If you need to ensure that only one AddOnObject exists with the same name, then use Unique AddOnObjects. See more: ACAPI_AddOnObject_CreateUniqueObject. The content handle will be copied inside the function so it has to be deleted after the function call. The stored data can be accessed using objectGuid parameter. The objectName parameter can also be used for identifying the custom data. It can be also emtpy. Archicad does not check if the name is unique. If you need to ensure that only one AddOnObject exists with the same name, then use Unique AddOnObjects. See more: ACAPI_AddOnObject_CreateUniqueObject.

◆ ACAPI_AddOnObject_CreateUniqueObject()

GSErrCode __ACENV_CALL ACAPI_AddOnObject_CreateUniqueObject	(	const GS::UniString &	objectName,
		API_Guid *	objectGuid
	)

Creates a Unique AddOnObject.

Parameters

objectName	[in] The name of the Unique AddOnObject.
objectGuid	[out] The GUID of the created object. Value is undefined if an error happened.

Returns

NoError - The function has completed with success.
APIERR_CANCEL - If the user refused to Send Receive all changes.
APIERR_NAMEALREADYUSED - If there is already a Unique AddOnObject with the given objectName.
APIERR_NOTEAMWORKPROJECT - Indicates that the project is an Offline TeamWork project. Due to possible conflicts, it is not allowed to create Unique AddOnObjects in an Offline Teamwork Project.
APIERR_SERVICEFAILED - The created Unique AddOnObject could not be sent to the TeamWork server.

Remarks: Unique AddOnObjects were introduced to support more restricted but safer TeamWork behaviour. Because multiple general (non-unique) AddOnObjects can exist with the same name, in TeamWork it could happen that two users created "the same" AddOnObject simultaneously, but at the end they ended up with two different AddOnObjects. This led to a lot of confusion. With Unique AddOnObjects - like general AddOnObjects - you can store custom data in the project database. However - unlike general AddOnObjects - their names must be and will be unique among each other. Please note that names of a Unique AddOnObject and general AddOnObjects may be equal. In a TeamWork project creating Unique AddOnObjects will result in a Full Receive and a Full Send to ensure project consistency. Due to this inconvenience, it is possible to create more Unique AddOnObjects at once with the ACAPI_AddOnObject_CreateUniqueObjectMore function. Unlike general AddOnObjects - to ensure no data conflict occurs - it is not possible to give default content to a Unique AddOnObject. To do so, you must call ACAPI_AddOnObject_ModifyObject function. The stored data can be accessed using the returned objectGuid. All functions that work for general AddOnObjects work for Unique AddOnObjects, too, except ACAPI_AddOnObject_GetObjectGuidFromName : to get the GUID of a Unique AddOnObject from its name use ACAPI_AddOnObject_GetUniqueObjectGuidFromName instead.

◆ ACAPI_AddOnObject_CreateUniqueObjectMore()

GSErrCode __ACENV_CALL ACAPI_AddOnObject_CreateUniqueObjectMore	(	const GS::Array< GS::UniString > &	objectNames,
		GS::Array< API_Guid > &	objectGuids
	)

Creates more Unique AddOnObjects.

Parameters

objectNames	[in] The names of the Unique AddOnObjects. The names must be unique.
objectGuids	[out] The GUIDs of the created objects. One guid is returned to each given name. Empty array is returned if an error happened.

Returns

NoError - The function has completed with success.
APIERR_BADPARS - If the objectNames array is empty or the names in it are not unique among each other.
APIERR_NAMEALREADYUSED - If there is already a Unique AddOnObject with one of the given objectNames.
APIERR_NOTEAMWORKPROJECT - Indicates that the project is an Offline TeamWork project. Due to possible conflicts, it is not allowed to create Unique AddOnObjects in an Offline Teamwork Project.
APIERR_SERVICEFAILED - The created Unique AddOnObjects could not be sent to the TeamWork server.

Remarks: In a TeamWork project creating Unique AddOnObjects will result in a Full Receive and a Full Send to ensure project consistency. Due to this inconvenience, it is possible to create more Unique AddOnObjects at once with this function. For more info, see ACAPI_AddOnObject_CreateUniqueObject.

◆ ACAPI_AddOnObject_DeleteObject()

GSErrCode __ACENV_CALL ACAPI_AddOnObject_DeleteObject ( const API_Guid & objectGuid )

Retrieves an attribute from the database.

Parameters

objectGuid [in] The GUID of the object.

Returns

NoError - The function has completed with success.
APIERR_BADID - The object does not exist.
APIERR_NOTMINE - The object is not owned by the current user in teamwork mode.

Remarks: This function is used to delete an AddOnObject from the project database.

◆ ACAPI_AddOnObject_ExistsObject()

GSErrCode __ACENV_CALL ACAPI_AddOnObject_ExistsObject	(	const API_Guid &	objectGuid,
		bool *	objectExists
	)

Determines if the project database contains the specified AddOnObject or not.

Parameters

objectGuid	[in] The GUID of the specified object..
objectExists	[out] true if the object exists, otherwise false.

Returns

NoError - The function has completed with success.
APIERR_BADPARS - The passed parameter objectGuid is APINULLGuid or objectExists is nullptr
APIERR_BADID - The object specified by GUID exists, but its type is not AddOnObject.

◆ ACAPI_AddOnObject_GetClientOnlyObjectGuidFromName()

GSErrCode __ACENV_CALL ACAPI_AddOnObject_GetClientOnlyObjectGuidFromName	(	const GS::UniString &	name,
		API_Guid *	objectGuid
	)

Returns the GUID of the specified object.

Parameters

name	[in] The name of the specified object.
objectGuid	[out] The GUID of the object, if the project database contains AddOnObject with the specified name, otherwise APINULLGuid.

Returns

NoError - The function has completed with success.
APIERR_BADPARS - The passed parameter objectGuid is nullptr.

Remarks: If more AddOnObjects exist with the same name, it is not specified which GUID will be returned. Please note that this is a linear time function. This function cannot be used to get the GUID of a Unique AddOnObject or AddOnObject or the get GUID-s from other teamwork users. You can use Unique AddOnObjects if it is important to have only one AddOnObject with the same name. See AddOnObject Manager for more information. Please note that this is a linear time function. This function cannot be used to get the GUID of a Unique AddOnObject. You can use Unique AddOnObjects if it is important to have only one AddOnObject with the same name. See AddOnObject Manager for more information.

◆ ACAPI_AddOnObject_GetObjectContent()

GSErrCode __ACENV_CALL ACAPI_AddOnObject_GetObjectContent	(	const API_Guid &	objectGuid,
		GS::UniString *	objectName,
		GSHandle *	objectContent
	)

Retrieves the content and the name of the specified AddOnObject from the project database.

Parameters

objectGuid	[in] The GUID of the object.
objectName	[out] The name of the specified object.
objectContent	[out] The content of the specified object.

Returns

NoError - The function has completed with success.
APIERR_BADPARS - The passed parameter objectGuid is APINULLGuid or either objectName or objectContent is nullptr.
APIERR_BADID - No object with the specified GUID exists.

Remarks: Archicad allocates the target buffer in content parameter; the caller add-on is responsible to dispose it with BMKillHandle.

◆ ACAPI_AddOnObject_GetObjectGuidFromName()

GSErrCode __ACENV_CALL ACAPI_AddOnObject_GetObjectGuidFromName	(	const GS::UniString &	name,
		API_Guid *	objectGuid
	)

Returns the GUID of the specified object.

Parameters

name	[in] The name of the specified object.
objectGuid	[out] The GUID of the object, if the project database contains AddOnObject with the specified name, otherwise APINULLGuid.

Returns

NoError - The function has completed with success.
APIERR_BADPARS - The passed parameter objectGuid is nullptr.

Remarks: If more AddOnObjects exist with the same name, it is not specified which GUID will be returned. Please note that this is a linear time function. This function cannot be used to get the GUID of a Unique AddOnObject or AddOnObject or the get GUID-s from other teamwork users. You can use Unique AddOnObjects if it is important to have only one AddOnObject with the same name. See AddOnObject Manager for more information. Please note that this is a linear time function. This function cannot be used to get the GUID of a Unique AddOnObject. You can use Unique AddOnObjects if it is important to have only one AddOnObject with the same name. See AddOnObject Manager for more information.

◆ ACAPI_AddOnObject_GetObjectList()

GSErrCode __ACENV_CALL ACAPI_AddOnObject_GetObjectList ( GS::Array< API_Guid > * objects )

Returns the list of the AddOnObjects.

Parameters

objects [out] This array will be filled with the GUIDs of the AddOnObjects.

Returns

NoError - The function has completed with success.
APIERR_BADPARS - The passed parameter objects is nullptr

Remarks: The function returns both general and Unique AddOnObjects.

◆ ACAPI_AddOnObject_GetTeamworkOwnerId()

GSErrCode __ACENV_CALL ACAPI_AddOnObject_GetTeamworkOwnerId	(	const API_Guid &	objectGuid,
		short *	ownerId
	)

Returns the ownerId of the specified object in teamwork mode.

Parameters

objectGuid	[in] The GUID of the specified object.
ownerId	[out] The teamwork owner user of the specified object.

Returns

NoError - The function has completed with success.
APIERR_BADPARS - The passed parameter objectGuid is APINULLGuid or ownerId is nullptr
APIERR_BADID - AddOnObject does not exist.

◆ ACAPI_AddOnObject_GetUniqueObjectGuidFromName()

GSErrCode __ACENV_CALL ACAPI_AddOnObject_GetUniqueObjectGuidFromName	(	const GS::UniString &	name,
		API_Guid *	objectGuid
	)

Returns the GUID of the specified Unique AddOnObject.

Parameters

name	[in] The name of the specified object.
objectGuid	[out] The GUID of the object, if the project database contains Unique AddOnObject with the specified name, otherwise APINULLGuid.

Returns

NoError - The function has completed with success.
APIERR_BADPARS - The passed parameter objectGuid is NULL.

Remarks: This function cannot be used to get the GUID of a general (non-unique) AddOnObject. Please note that this is a linear time function. This function cannot be used to get the GUID of a general (non-unique) AddOnObject.

◆ ACAPI_AddOnObject_GrantObjects()

GSErrCode __ACENV_CALL ACAPI_AddOnObject_GrantObjects	(	const GS::Array< API_Guid > &	objectGuids,
		short	toUserId
	)

In teamwork mode this function grants the specified objects to the given user.

Parameters

objectGuids	[in] The list of the objects which must be granted.
toUserId	[in] The teamwork owner, to which the objects must be granted.

Returns

NoError - The function has completed with success.
APIERR_BADPARS - The passed parameter objectGuids is empty or contains APINULLGuid.
APIERR_BADID - If any of the objectGuids is not an AddOnObject GUID.

Remarks: If the function has completed with success then the specified objects will be granted to the given user. The process runs in silent mode, no dialogs or messages will interrupt.

◆ ACAPI_AddOnObject_InstallAddOnObjectConvertNewFormatHandler()

GSErrCode __ACENV_CALL ACAPI_AddOnObject_InstallAddOnObjectConvertNewFormatHandler ( APIAddonObjectConvertNewFormatHandlerProc * convertNewFormatProc )

Installs a callback procedure for converting old format AddOnObject data into current format.

Parameters

convertNewFormatProc [in] The callback procedure to convert AddOnObject data. Passing nullptr in this parameter uninstalls the previously installed handler function.

Returns

NoError - The function has completed with success.

Remarks: In order to convert the add-on's AddOnObject data into current format, you need to implement this callback function, and pass it to Archicad with ACAPI_AddOnObject_InstallAddOnObjectConvertNewFormatHandler during the Initialize phase. It is also necessary to notify Archicad about this capability of the add-on by calling ACAPI_AddOnObject_RegisterAddOnObjectHandler from the RegisterInterface function. This handler function is called whenever the user opens an old version project, and the add-on has any AddOnObject stored in the original project. The data should be constructed according to the current version into API_AddonObject structures, and these structures should be pushed into the currentFormatAddOnObjectArray array. The memory allocated for the converted AddOnObject by the add-on's handler function will be released by the caller application. You must pay attention to not create more than one API_AddonObject s with the same name if the AddOnObject is Unique.

◆ ACAPI_AddOnObject_InstallAddOnObjectMergeHandler()

GSErrCode __ACENV_CALL ACAPI_AddOnObject_InstallAddOnObjectMergeHandler ( APIAddonObjectMergeHandlerProc * mergeHandlerProc )

Installs a callback procedure for handling the AddOnObject merge operations.

Parameters

mergeHandlerProc [in] The callback procedure which will handle the AddOnObject data merge. Can be nullptr ; this removes the installed callback.

Returns

NoError - The function has completed with success.

Remarks: This function should be called in the Initialize function of your add-on to pass the pointer of the APIAddOnObjectMergeHandlerProc callback routine implemented for resolving conflicts between two lists of the AddOnObjects of the add-on during a merge operation.

◆ ACAPI_AddOnObject_InstallAddOnObjectSaveOldFormatHandler()

GSErrCode __ACENV_CALL ACAPI_AddOnObject_InstallAddOnObjectSaveOldFormatHandler ( APIAddonObjectSaveOldFormatHandlerProc * saveOldFormatProc )

Installs a callback procedure for converting AddOnObject data into older format.

Parameters

saveOldFormatProc [in] The callback procedure to convert AddOnObject data. Passing nullptr in this parameter uninstalls the previously installed handler function.

Returns

NoError - The function has completed with success.

Remarks: In order to save the add-on's AddOnObject data in the proper format into a previous version project file, you need to implement this callback function, and pass it to Archicad with ACAPI_AddOnObject_InstallAddOnObjectSaveOldFormatHandler during the Initialize phase. It is also necessary to notify Archicad about this capability of the add-on by calling ACAPI_AddOnObject_RegisterAddOnObjectHandler from the RegisterInterface function. This handler function is called whenever the user saves the project into an older format, and the add-on has any AddOnObject stored currently into the project. The data should be constructed according to the required version into API_AddonObject structures, and these structures should be pushed into the oldFormatAddOnObjectArray array. The memory allocated for the converted AddOnObjects by the add-on's handler function will be released by the caller application. If you need to delete an AddOnObject (e.g. it cannot be read by a previous version) then simply don't push it into the array. Order of the converted API_AddonObject s is irrelevant. You must pay attention to not create more than one API_AddonObject s with the same name if the AddOnObject is Unique. Because Unique AddOnObjects is an API 21 () feature, please pay special attention to converting AddOnObjects with UniqueAddOnObject API_AddonObjectType by either setting their type to GeneralAddOnObject or leaving them from oldFormatAddOnObjectArray.

◆ ACAPI_AddOnObject_ModifyObject()

GSErrCode __ACENV_CALL ACAPI_AddOnObject_ModifyObject	(	const API_Guid &	objectGuid,
		const GS::UniString *	newObjectName,
		const GSHandle *	newObjectContent
	)

Modifies the content and/or the name of the specified AddOnObject.

Parameters

objectGuid	[in] The GUID of the object.
newObjectName	[in] The new name of the specified object. If nullptr, the name of the object remains the original name. Must be nullptr if modifying a Unique AddOnObject.
newObjectContent	[in] The new content of the specified object. If nullptr, the content of the object remains the original content. Must not be nullptr if modifying a Unique AddOnObject.

Returns

NoError - The function has completed with success.
APIERR_BADPARS - If the passed objectGuid parameter is NULLGuid, or if neither newObjectName nor newObjectContent is filled, or if modifying a Unique AddOnObject and either newObjectName is not nullptr (it must be) or newObjectContent is nullptr (it must not be).
APIERR_BADID - The specified object does not exist.
APIERR_NOTMINE - The object is not owned by the current user in teamwork mode.

Remarks: This function is used for modifying the content or the name of the specified AddOnObject. The newObjectContent handle will be copied inside the function so it has to be deleted after the function call.

◆ ACAPI_AddOnObject_RegisterAddOnObjectHandler()

GSErrCode __ACENV_CALL ACAPI_AddOnObject_RegisterAddOnObjectHandler ( void )

Registers the add-on to be called for merging and converting its custom data stored in AddOnObjects.

Returns

NoError - The function has completed with success.

Remarks: Call this function from RegisterInterface to let Archicad know that the add-on has APIAddOnObjectMergeHandlerProc and/or APIAddOnObjectSaveOldFormatHandlerProc and/or APIAddOnObjectConvertNewFormatHandlerProc callback function implemented for merging and converting its custom data. In order this functions to be called on the adequate event, the add-on needs to pass the function pointers to Archicad from Initialize with ACAPI_AddOnObject_InstallAddOnObjectMergeHandler, ACAPI_AddOnObject_InstallAddOnObjectSaveOldFormatHandler and ACAPI_AddOnObject_InstallAddOnObjectConvertNewFormatHandler, respectively.

◆ ACAPI_AddOnObject_ReleaseObjects()

GSErrCode __ACENV_CALL ACAPI_AddOnObject_ReleaseObjects ( const GS::Array< API_Guid > & objectGuids )

In teamwork mode this function releases the specified objects.

Parameters

objectGuids [in] The list of the objects which must be released.

Returns

NoError - The function has completed with success.
APIERR_BADPARS - The passed parameter objectGuids is empty or contains APINULLGuid.
APIERR_BADID - If any of the objectGuids is not an AddOnObject GUID.

Remarks: If any of the specified objects were modified, Send Changes operation will be performed in order to send the modified objects to server.

◆ ACAPI_AddOnObject_RequestObjects()

GSErrCode __ACENV_CALL ACAPI_AddOnObject_RequestObjects	(	const GS::Array< API_Guid > &	objectGuids,
		const GS::UniString &	mailText
	)

In teamwork mode this function sends a request mail in order to request the specified objects from the owners.

Parameters

objectGuids	[in] The list of the objects which must be requested.
mailText	[in] The text of the request mail.

Returns

NoError - The function has completed with success.
APIERR_BADPARS - The passed parameter objectGuids is empty or contains APINULLGuid.
APIERR_BADID - If any of the objectGuids is not an AddOnObject GUID.

◆ ACAPI_AddOnObject_ReserveObjects()

GSErrCode __ACENV_CALL ACAPI_AddOnObject_ReserveObjects	(	const GS::Array< API_Guid > &	objectGuids,
		GS::HashTable< API_Guid, short > *	conflicts
	)

In teamwork mode this function reserves the specified objects.

Parameters

objectGuids	[in] The list of the objects which must be released.
conflicts	[out] Can be nullptr. If some of the specified objects cannot be reserved because of reservations of other users, this table will be filled with the conflicts.

Returns

NoError - The function has completed with success.
APIERR_BADPARS - The passed parameter objectGuids is empty or contains APINULLGuid.
APIERR_BADID - If any of the objectGuids is not an AddOnObject GUID.

Remarks: If any of the specified objects were modified by another user, Receive Changes operation will be performed in order to get the latest version of the objects from the server.

◆ ACAPI_AddOnObject_SetUIProperties()

GSErrCode __ACENV_CALL ACAPI_AddOnObject_SetUIProperties	(	const API_Guid *	objectGuid,
		const GS::UniString *	name,
		const GS::UniString &	localisedName,
		short	dialogMenuStringId
	)

Sets various UI properties of an AddOnObject.

Parameters

objectGuid	[in] GUID of the specified object. Can be NULL if name-based identification is intended.
name	[in] The name of the specified object. Can be NULL if only GUID-based identification is intended.
localisedName	[in] The localised name of the specified object (or objects if objectGuid is NULL and there are more AddOnObjects with the same name).
dialogMenuStringId	[in] The id of the menu which must be called if Show button is pressed on Teamwork User interface.

Returns

NoError - The function has completed with success.
APIERR_BADPARS - Both objectGuid and name are NULL, or localisedName is empty string.

Remarks: This function is used to register UI properties for AddOnObject. UI properties are localised name and the menu command id. The registered properties will be used for all AddOnObjects which have the specified GUID or name. If Archicad looks for a UI property, first tries to find it by GUID. If the property is not found, Archicad also tries to find it by name. So the registration can be done even if no instance of AddOnObject exists: in this case objectGuid should be NULL. Please note that if only the name is given for a UI property, then all AddOnObjects (both general and unique) with this name will have the same UI property.

Classes

Typedefs

Enumerations

Functions

Detailed Description

Unique AddOnObjects

Functions

Merging AddOnObjects

Saving data into old format project

Converting data when reading an old format project

Typedef Documentation

◆ APIAddonObjectConvertNewFormatHandlerProc

◆ APIAddonObjectMergeHandlerProc

◆ APIAddonObjectSaveOldFormatHandlerProc

Function Documentation

◆ ACAPI_AddOnObject_CreateClientOnlyObject()

◆ ACAPI_AddOnObject_CreateObject()

◆ ACAPI_AddOnObject_CreateUniqueObject()

◆ ACAPI_AddOnObject_CreateUniqueObjectMore()

◆ ACAPI_AddOnObject_DeleteObject()

◆ ACAPI_AddOnObject_ExistsObject()

◆ ACAPI_AddOnObject_GetClientOnlyObjectGuidFromName()

◆ ACAPI_AddOnObject_GetObjectContent()

◆ ACAPI_AddOnObject_GetObjectGuidFromName()

◆ ACAPI_AddOnObject_GetObjectList()

◆ ACAPI_AddOnObject_GetTeamworkOwnerId()

◆ ACAPI_AddOnObject_GetUniqueObjectGuidFromName()

◆ ACAPI_AddOnObject_GrantObjects()

◆ ACAPI_AddOnObject_InstallAddOnObjectConvertNewFormatHandler()

◆ ACAPI_AddOnObject_InstallAddOnObjectMergeHandler()

◆ ACAPI_AddOnObject_InstallAddOnObjectSaveOldFormatHandler()

◆ ACAPI_AddOnObject_ModifyObject()

◆ ACAPI_AddOnObject_RegisterAddOnObjectHandler()

◆ ACAPI_AddOnObject_ReleaseObjects()

◆ ACAPI_AddOnObject_RequestObjects()

◆ ACAPI_AddOnObject_ReserveObjects()

◆ ACAPI_AddOnObject_SetUIProperties()