Teamwork

Functions exposing the Teamwork functionality of Archicad, including Teamwork project and connection management, rights and permissions management and release/reserve functionalities. More...

Functions
GSErrCode	ACAPI_Teamwork_GetTWOwner (API_DatabaseUnId *databaseUnId, short *userId)
	Retrieves the TeamWork owner of a given database.
GSErrCode	ACAPI_Teamwork_ProjectSharing (API_SharingInfo *sharingInfo)
	Returns the project sharing data in the case of a TeamWork project.
GSErrCode	ACAPI_Teamwork_GetTWAccessRight (API_TWAccessRights accessRight, bool *hasRight)
	Returns if the current user has the specifed access right.
GSErrCode	ACAPI_Teamwork_GrantElements (const GS::Array< API_Guid > &elemGuids, short toUserId)
	In teamwork mode this function grants the specified elements to the given user.
bool	ACAPI_Teamwork_HasConnection (void)
	Tells whether the currently opened project is a Teamwork project.
bool	ACAPI_Teamwork_IsOnline (void)
	Tells whether the client is online connected to the BIM server.
bool	ACAPI_Teamwork_IsServerLibPart (const IO::Location &location)
	Tells whether the given location refers to a BIM Server Library Part.
GSErrCode	ACAPI_Teamwork_GetTeamworkProjectDetails (const IO::Location &twProjectLocation, GS::UniString *serverUrl=nullptr, GS::UniString *projectName=nullptr, GS::UniString *userName=nullptr)
	Extracts details from the given location about the teamwork project.
bool	ACAPI_Teamwork_HasCreateRight (const API_Guid &objectId)
	Checks whether the current Teamwork user has access right to create a certain type of object.
bool	ACAPI_Teamwork_HasDeleteModifyRight (const API_Guid &objectId)
	Checks whether the current Teamwork user has access right to delete or modify a certain type of object.
API_LockableStatus	ACAPI_Teamwork_GetLockableStatus (const API_Guid &objectId, GS::PagedArray< short > *conflicts=nullptr)
	Retrieves the reservation status of a lockable object set.
API_Guid	ACAPI_Teamwork_FindLockableObjectSet (const GS::UniString &objectSetName)
	Retrieves the unique identifier of a lockable object set with a string identifier.
GSErrCode	ACAPI_Teamwork_ReserveLockable (const API_Guid &objectId, GS::PagedArray< short > *conflicts=nullptr, bool enableDialogs=true)
	Reserves a lockable object set in Teamwork mode.
GSErrCode	ACAPI_Teamwork_ReleaseLockable (const API_Guid &objectId, bool enableDialogs=true)
	Releases a lockable object set in Teamwork mode.
GSErrCode	ACAPI_Teamwork_ReserveElements (const GS::Array< API_Guid > &elements, GS::HashTable< API_Guid, short > *conflicts=nullptr, bool enableDialogs=true)
	Reserves elements in Teamwork mode.
GSErrCode	ACAPI_Teamwork_ReleaseElements (const GS::Array< API_Guid > &elements, bool enableDialogs=true)
	Releases elements in Teamwork mode.
GSErrCode	ACAPI_Teamwork_ReserveHotlinkCacheManagement (short *conflict=nullptr)
	Reserves the Hotlink/XRef Management in Teamwork mode.
GSErrCode	ACAPI_Teamwork_ReleaseHotlinkCacheManagement (void)
	Releases the Hotlink/XRef Management in Teamwork mode.
GSErrCode	ACAPI_Teamwork_GetHotlinkCacheManagementOwner (short *owner)
	Provides the current owner of the Hotlink/XRef Management in Teamwork mode.
GSErrCode	ACAPI_Teamwork_GetUsernameFromId (short userId, GS::UniString *username)
	Retrieves the username of a user identified by a short id in a Teamwork project.
GSErrCode	ACAPI_Teamwork_SendChanges (const GS::UniString &comment=GS::EmptyUniString)
	Sends changes to the BIMcloud server.
GSErrCode	ACAPI_Teamwork_ReceiveChanges ()
	Receives changes from the BIMcloud server.
GSErrCode	ACAPI_RegisterTeamworkReserveInterface (const API_Guid &objectId, short dialogId, short tabId, short tabResId, GSResModule resModule, GSResModule dialogIconResModule, APIReservationTeamWorkPanelParentUIRefreshNeededProc *teamworkPanelParentUIRefreshNeeded, APIReservationTeamWorkPanelParentDataSaveNeededProc *teamworkPanelParentDataSaveNeeded, const GS::UniString &requestMessage, API_TWAccessRights createRight=APINoPermission, API_TWAccessRights deleteModifyRight=APINoPermission)
	Registers an interface supporting reserve/release in teamwork operations.
GSErrCode	ACAPI_UnregisterTeamworkReserveInterface (const API_Guid &objectId, short dialogId=0)
	Unregisters a previously registered interface.
GSErrCode	ACAPI_RefreshTeamworkReserveInterface (const API_Guid &objectId, short dialogId, bool isTeamWorkPanelParentUIRefreshNeeded=false)
	Refreshes the registered teamwork interface.
GSErrCode	ACAPI_Teamwork_SendReleaseCommentMail (const API_Guid &objectId, short dialogId)
	Sends the release comment mail.

Detailed Description

Functions exposing the Teamwork functionality of Archicad, including Teamwork project and connection management, rights and permissions management and release/reserve functionalities.

Teamwork Control

This bunch of functions lets your add-on operate in the new Teamwork environment introduced in Archicad 13.

Functions

for checking the project status and the online-offline mode:

• ACAPI_Teamwork_HasConnection
• ACAPI_Teamwork_IsOnline

for checking the user privileges of lockable object sets:

• ACAPI_Teamwork_HasCreateRight
• ACAPI_Teamwork_HasDeleteModifyRight

for lockable object set reservation:

• ACAPI_Teamwork_GetLockableStatus
• ACAPI_Teamwork_FindLockableObjectSet
• ACAPI_Teamwork_ReserveLockable
• ACAPI_Teamwork_ReleaseLockable

for element reservation:

• ACAPI_Teamwork_ReserveElements
• ACAPI_Teamwork_ReleaseElements

for reservation of the Hotlink/XRef Management

• ACAPI_Teamwork_ReserveHotlinkCacheManagement
• ACAPI_Teamwork_ReleaseHotlinkCacheManagement
• ACAPI_Teamwork_GetHotlinkCacheManagementOwner

for monitoring reservation changes:

• ACAPI_Notification_CatchElementReservationChange
• ACAPI_Notification_CatchLockableReservationChange

for determining if a given library part is loaded from the BIM server:

• ACAPI_Teamwork_IsServerLibPart

for collecting information about the team project, the actual workspace and the effective privileges of the Team Member:

• ACAPI_Teamwork_ProjectSharing
• ACAPI_Teamwork_GetTWAccessRight
• ACAPI_Teamwork_GetUsernameFromId
• ACAPI_Teamwork_GetTeamworkProjectDetails

for sending or receiving changes to or from the BIM server:

• ACAPI_Teamwork_SendChanges
• ACAPI_Teamwork_ReceiveChanges

Lockable Object Sets

Lockable object sets are groups of objects (or may consist of a single object) which can be modified separately from the other part of the Teamwork project. Typically attribute containers are lockable object sets. These sets have a special reservation panel on their settings dialog in Teamwork mode to control the exclusive lock on that particular part of the project.

On the API interface lockable object sets are referenced by their object guid. These guids can be obtained with the ACAPI_Teamwork_FindLockableObjectSet function using pre-defined identifiers.

In some cases two or more lockable object sets need to be handled simultaneously, for example they can be locked only in the same user interface at the same time, like the Layers and Layer Combinations in the Layer Settings dialog. These sets are grouped under a special lockable object set, which is called compound lockable object set. Compounds are referenced by a pre-defined name, and their guid can also be retrieved by the ACAPI_Teamwork_FindLockableObjectSet function.

The pre-defined identifier strings of lockable object sets are listed in the Remarks section of ACAPI_Teamwork_FindLockableObjectSet.

Example

The Teamwork_Control example project of the APIDevKit shows samples how to use these functions.

Function Documentation

ACAPI_RefreshTeamworkReserveInterface()

GSErrCode ACAPI_RefreshTeamworkReserveInterface	(	const API_Guid &	objectId,
		short	dialogId,
		bool	isTeamWorkPanelParentUIRefreshNeeded = false
	)

Refreshes the registered teamwork interface.

Parameters

objectId	[in] The unique identifier of this interface (that you passed during registration).
dialogId	[in] The dialog ID you registered the interface for.
isTeamWorkPanelParentUIRefreshNeeded	[in] Update the parent UI as well?

Returns

• NoError - The function completed with success.

ACAPI_RegisterTeamworkReserveInterface()

GSErrCode ACAPI_RegisterTeamworkReserveInterface	(	const API_Guid &	objectId,
		short	dialogId,
		short	tabId,
		short	tabResId,
		GSResModule	resModule,
		GSResModule	dialogIconResModule,
		APIReservationTeamWorkPanelParentUIRefreshNeededProc *	teamworkPanelParentUIRefreshNeeded,
		APIReservationTeamWorkPanelParentDataSaveNeededProc *	teamworkPanelParentDataSaveNeeded,
		const GS::UniString &	requestMessage,
		API_TWAccessRights	createRight = APINoPermission,
		API_TWAccessRights	deleteModifyRight = APINoPermission
	)

Registers an interface supporting reserve/release in teamwork operations.

Parameters

objectId	[in] The unique identifier of this interface.
dialogId	[in] The dialog ID you register the interface for.
tabId	[in] The tab page ID you register the interface for.
tabResId	[in] The resource describing the tab page interface elements.
resModule	[in] The resource module identifier that identifies the module containing the tab page interface elements.
dialogIconResModule	[in] The resource module identifier that identifies the module containing the tab page icons.
teamworkPanelParentUIRefreshNeeded	[in] The callback function which is called when you have to refresh the items on the registered interface.
teamworkPanelParentDataSaveNeeded	[in] The callback function which is called before your panel is closed. You can use this function to set an internal state in your add-on which you can use later to perform teamwork-related operations (e.g., reserve or release AddOnObjects).
requestMessage	[in] The request message.
createRight	[in] The teamwork create right you assign to this interface.
deleteModifyRight	[in] The teamwork delete and modify right you assign to this interface.

Returns

• NoError - The function completed with success.
• APIERR_BADPARS - objectId is APINULLGuid or dialogId is 0 or tabId is 0.
• APIERR_NOPLAN - No project is open.
• APIERR_NOTEAMWORKPROJECT - The open project is not a teamwork project.
• APIERR_BADID - objectId is APINULLGuid.

ACAPI_Teamwork_FindLockableObjectSet()

API_Guid ACAPI_Teamwork_FindLockableObjectSet

(

const GS::UniString &

objectSetName

)

Retrieves the unique identifier of a lockable object set with a string identifier.

Since

Archicad 25

Parameters

objectSetName

[in] String identifier of the lockable object set (see below)

Returns

• NoError - The function returns the Guid of the named lockable object set if found by the given objectSetName string, otherwise it returns APINULLGuid.

Remarks

This function is used to retrieve the identifier of a named lockable object set, such as attribute types, favorites, model view options. In certain cases lockable object sets need to be reserved simultaneously. For this purpose compound lockable object sets were introduced, to hold the lockable object sets, and to make these sets be reserved together. Reserving individually a lockable object set which belongs to a compound one may result insecure functionality in the Teamwork project, should be avoided. Compound lockable object sets are indentified with a string. Currently the following compound lockable object sets are used:

• Layers, Layer Combinations (compound identifier name: "LayerSettingsDialog")
• Project Preferences Data, Dimension Standards (compound identifier name: "PreferencesDialog") Note that before API version 20, this function handled compound lockable object sets only. From API 20 you need to use this function to retrieve the guid of all lockable object sets. The list of the currently available lockable object set identifiers:

  Object set	Identifier string
  Building Materials	"BuildingMaterials"
  Cities	"Cities"
  Composites	"Composites"
  Favorites	"Favorites"
  Fill Types	"FillTypes"
  Layers, Layer Combinations	"LayerSettingsDialog"
  Line Types	"LineTypes"
  Markup Styles	"MarkupStyles"
  MEP Systems	"MEPSystems"
  Model View Options	"ModelViewOptions"
  Operation Profiles	"OperationProfiles"
  Pen Tables	"PenTables"
  Profiles	"Profiles"
  Project Info	"ProjectInfo"
  Project Location	"GeoLocation"
  Project Preferences, Dimension Standards	"PreferencesDialog"
  Graphic Overrides	"GraphicOverrides"
  Surface Materials	"Surfaces"
  Zone Categories	"ZoneCategories"

  For more information on lockable object sets see the Teamwork Control page.

Example

See the Example section of ACAPI_Teamwork_ReleaseLockable
.

ACAPI_Teamwork_GetHotlinkCacheManagementOwner()

GSErrCode ACAPI_Teamwork_GetHotlinkCacheManagementOwner

(

short *

owner

)

Provides the current owner of the Hotlink/XRef Management in Teamwork mode.

Parameters

owner

[out] userId of the current owner if there is any (must not be nullptr).

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - The given parameter is nullptr.
• APIERR_NOPLAN - There is no open project.
• APIERR_NOTEAMWORKPROJECT - The current project is not a Teamwork project.

Remarks

Use this function to get the current owner of the Hotlink/XRef Management. You can find out more about the owner from the API_SharingInfo structure which can be obtained by calling the ACAPI_Environment function with the ACAPI_Teamwork_ProjectSharing function code. The userId of the current Teamwork Client can be retrieved from the API_ProjectInfo structure which can be obtained by calling the ACAPI_Environment function with the ACAPI_ProjectOperation_Project function code. If the Hotlink/XRef Management is not reserved by anybody the result will be 0.

Example

short owner;
GSErrCode err = ACAPI_GetHotlinkCacheManagementOwner (&owner);
if (err == NoError) {
    API_ProjectInfo projectInfo;
    ACAPI_Environment (APIEnv_ProjectID, &projectInfo);
    if (projectInfo.userId == owner)
        ACAPI_WriteReport ("The Hotlink/XRef Management is being reserved by this client.", true);
}

ACAPI_Teamwork_GetLockableStatus()

API_LockableStatus ACAPI_Teamwork_GetLockableStatus	(	const API_Guid &	objectId,
		GS::PagedArray< short > *	conflicts = nullptr
	)

Retrieves the reservation status of a lockable object set.

Since

Archicad 25

Parameters

objectId	[in] Unique identifier of the lockable object set
conflicts	[out] List of conflicting users (optional, can be nullptr or omitted)

Returns

• APILockableStatus_NotExist - No Teamwork connection, or the passed objectId parameter does not identifies a valid lockable object set
• APILockableStatus_Free - The given lockable object set is available for reservation, not locked
• APILockableStatus_Editable - The given lockable object set is editable, already reserved by the current user
• APILockableStatus_Locked - The given lockable object set is reserved by someone else
• APILockableStatus_NotAvailable - Server is offline or not available

Remarks

This function is used to retrieve the current reservation status of a lockable object set. In a Teamwork project object sets (like attributes, favorites, project info, etc.) can be locked by any project members having sufficient access rights, using the reservation panel on the settings dialogs. Once the user gains the lock, the object set is syncronized from the server project, that is the user practically works with exactly the same data the server has. When releasing it, the modifications to the object set are sent back to the server. Note that a reserved lockable object set is still editable in offline mode, though you cannot release the object set until the connection status becomes online.

Example

See the Example section of the ACAPI_Teamwork_ReserveLockable
and ACAPI_Teamwork_ReleaseLockable
functions.

ACAPI_Teamwork_GetTeamworkProjectDetails()

GSErrCode ACAPI_Teamwork_GetTeamworkProjectDetails	(	const IO::Location &	twProjectLocation,
		GS::UniString *	serverUrl = nullptr,
		GS::UniString *	projectName = nullptr,
		GS::UniString *	userName = nullptr
	)

Extracts details from the given location about the teamwork project.

Since

Archicad 25

Parameters

twProjectLocation	[in] The location URI of the teamwork project.
serverUrl	[out] The URL of the teamwork (BIMcloud) server.
projectName	[out] The name of the project on the server.
userName	[out] The username of the logged in user.

Returns

• NoError - The function has completed with success.
• APIERR_NOTEAMWORKPROJECT - The given project is not Teamwork project.

Remarks

This function extracts information only from the given location. It does not try to reach the server and does not retrieve any data from it.

Example

GS::UniString   serverUrl;
GS::UniString   projectName;
GS::UniString   userName;
GSErrCode err = ACAPI_Teamwork_GetTeamworkProjectDetails (twProjectLocation,
                                                                 &serverUrl,
                                                                 &projectName,
                                                                 &userName);
 
if (err != NoError) {
    ACAPI_WriteReport ("The given location does not refer to a teamwork project.", true);
}

ACAPI_Teamwork_GetTWAccessRight()

GSErrCode ACAPI_Teamwork_GetTWAccessRight	(	API_TWAccessRights	accessRight,
		bool *	hasRight
	)

Returns if the current user has the specifed access right.

Parameters

accessRight	[in] The access right to check.
hasRight	[out] The status of the access right in question.

Returns

• NoError - The function completed with success.
• APIERR_BADPARS - hasRight is nullptr

Remarks

In non-teamwork mode hasRight is always true. You can use this function to check the user's permissions.

ACAPI_Teamwork_GetTWOwner()

GSErrCode ACAPI_Teamwork_GetTWOwner	(	API_DatabaseUnId *	databaseUnId,
		short *	userId
	)

Retrieves the TeamWork owner of a given database.

Parameters

databaseUnId	[in] The unique ID of the database
userId	[out] The TeamWork user ID of the owner of the specified database

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - The dbUnID or the userId parameter is nullptr, or dbUnID is not valid

Remarks

This function is used to get the user ID of the owner of a database. You can get the user ID of the current TeamWork client with ACAPI_ProjectOperation_Project.

Example

short userId = 0;
API_DatabaseInfo databaseInfo;
BNZeroMemory (&databaseInfo, sizeof (API_DatabaseInfo));
ACAPI_Database (APIDb_GetCurrentDatabaseID, &databaseInfo, nullptr);
if (ACAPI_Database (APIDb_GetTWOwnerID, &(databaseInfo.databaseUnId), &userId) == NoError)
    DBPrintf ("TeamWork owner ID of the current database: %d\n", userId);

ACAPI_Teamwork_GetUsernameFromId()

GSErrCode ACAPI_Teamwork_GetUsernameFromId	(	short	userId,
		GS::UniString *	username
	)

Retrieves the username of a user identified by a short id in a Teamwork project.

Since

Archicad 25

Parameters

userId	[in] Unique identifier of the user
username	[out] The name of the user

Returns

• NoError - The function has completed with success.
• APIERR_NOPLAN - There is no open project.
• APIERR_NOTEAMWORKPROJECT - The current project is not Teamwork project.

Example

The Teamwork_Control
example project of the DevKit shows samples how to use this function.

ACAPI_Teamwork_GrantElements()

GSErrCode ACAPI_Teamwork_GrantElements	(	const GS::Array< API_Guid > &	elemGuids,
		short	toUserId
	)

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

Parameters

elemGuids	[in] The list of the elements 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 elemGuids is empty, contains APINULLGuid, or not all the elements are on the same floor.
• APIERR_BADID - If any of the elemGuids is not an AddOnObject GUID.

Remarks

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

ACAPI_Teamwork_HasConnection()

bool ACAPI_Teamwork_HasConnection

(

void

)

Tells whether the currently opened project is a Teamwork project.

Returns

• true - The current project is a shared Teamwork project.
• false - The current project is a solo project, or there is no open project at all.

Remarks

This function tells if the currently project was opened in Teamwork mode, that is the user is joined to a shared Teamwork project on a BIM Server. Note that being connected to a Teamwork project does not mean necessarily online connection to the server. In order to check the online-offline status, use ACAPI_Teamwork_IsOnline.

Example

if (!ACAPI_Teamwork_HasConnection ())
    ACAPI_WriteReport ("This function is available only in Teamwork mode", true);

ACAPI_Teamwork_HasCreateRight()

bool ACAPI_Teamwork_HasCreateRight

(

const API_Guid &

objectId

)

Checks whether the current Teamwork user has access right to create a certain type of object.

Parameters

objectId

[in] Unique identifier of the object

Returns

• true - The current user has sufficient privileges to create the given type of objects.
• false - The current user is not allowed to create the given type of objects.

Remarks

Use this function to decide whether the current Teamwork user has right to create a given type of objects. The access rights are pre-set by the Project Administrator.

Example

API_Guid objectSetGuid = ACAPI_Teamwork_FindLockableObjectSet ("LineTypes");
if (!ACAPI_Teamwork_HasCreateRight (objectSetGuid))
    ACAPI_WriteReport ("You have insufficient privileges to create Line Type attributes", true);

ACAPI_Teamwork_HasDeleteModifyRight()

bool ACAPI_Teamwork_HasDeleteModifyRight

(

const API_Guid &

objectId

)

Checks whether the current Teamwork user has access right to delete or modify a certain type of object.

Parameters

objectId

[in] Unique identifier of the object

Returns

• true - The current user has sufficient privileges to delete or modify the given type of objects.
• false - The current user is not allowed to delete or modify the given type of objects.

Remarks

Use this function to decide whether the current Teamwork user has right to delete or modify a given type of objects. The access rights are pre-set by the Project Administrator.

Example

API_Guid objectSetGuid = ACAPI_Teamwork_FindLockableObjectSet ("FillTypes");
if (!ACAPI_Teamwork_HasDeleteModifyRight (objectSetGuid))
    ACAPI_WriteReport ("You have insufficient privileges to modify/delete Fill Type attributes", true);

ACAPI_Teamwork_IsOnline()

bool ACAPI_Teamwork_IsOnline

(

void

)

Tells whether the client is online connected to the BIM server.

Returns

• true - The Teamwork user is working in online mode.
• false - The Teamwork user is working in offline mode.

Remarks

Use this function to check if the connection status between the client application and the BIM server is online. Note that a Teamwork user joined to a shared project is still in Teamwork mode even if the connection staus is offline. To check whether the project the user is working with is a Teamwork project, use ACAPI_Teamwork_HasConnection.

Example

if (!ACAPI_Teamwork_IsOnline ()) {
    ACAPI_WriteReport ("Sorry, the BIM Server is currently not available", true);

ACAPI_Teamwork_IsServerLibPart()

bool ACAPI_Teamwork_IsServerLibPart

(

const IO::Location &

location

)

Tells whether the given location refers to a BIM Server Library Part.

Parameters

location

[in] Location of a library part.

Returns

• true - The given location is a BIM Server Library Part.
• false - The given location is not a BIM Server Library Part.

ACAPI_Teamwork_ProjectSharing()

GSErrCode ACAPI_Teamwork_ProjectSharing

(

API_SharingInfo *

sharingInfo

)

Returns the project sharing data in the case of a TeamWork project.

Parameters

sharingInfo

data of the registered members of the team project

Returns

• NoError - The function completed with success.
• APIERR_BADPARS - sharingInfo is nullptr.
• APIERR_NOPLAN - sharingInfo is nullptr.
• APIERR_MEMFULL - Low memory condition.

Remarks

This function is used to get the registered members of the opened team project. Member data are returned through an array of API_UserInfo records. Do not forget to dispose the member data handle if it is not needed any more.

Example

API_SharingInfo    sharingInfo;
Int32               i;
char               buffer[256];
GSErrCode          err;
 
BNZeroMemory (&sharingInfo, sizeof (API_SharingInfo));
err = ACAPI_Environment (APIEnv_ProjectSharingID, &sharingInfo, nullptr, nullptr);
if (err) {
    GiveMessage_Err ("Error in APIEnv_ProjectSharingID", err);
    return;
}
 
for (i = 0; i < sharingInfo.nUsers; i++) {
    sprintf (buffer, "  \"%10s\"   id:%2d   %s",
             (*sharingInfo.users)[i].name,
             (*sharingInfo.users)[i].userId,
             (*sharingInfo.users)[i].connected ? "Connected" : "");
    if ((*sharingInfo.users)[i].userId == projectInfo.userId)
        buffer[0] = '*';
    GiveMessage (buffer, false);
}
 
BMKillHandle ((GSHandle *) &sharingInfo.users);

ACAPI_Teamwork_ReceiveChanges()

GSErrCode ACAPI_Teamwork_ReceiveChanges

(

)

Receives changes from the BIMcloud server.

Since

Archicad 25

Returns

• NoError - The function has completed with success.
• APIERR_NOPLAN - There is no open project.
• APIERR_NOTEAMWORKPROJECT - The current project is not a Teamwork project.

Example

The Teamwork_Control
example project of the DevKit shows examples of how to use this function.

ACAPI_Teamwork_ReleaseElements()

GSErrCode ACAPI_Teamwork_ReleaseElements	(	const GS::Array< API_Guid > &	elements,
		bool	enableDialogs = true
	)

Releases elements in Teamwork mode.

Since

Archicad 25

Parameters

elements	[in] List of elements to be released.
enableDialogs	[in] Show dialogs during the process? (optional, by default the dialogs are enabled)

Returns

• NoError - The function has completed with success.
• APIERR_NOPLAN - There is no open project.
• APIERR_NOTEAMWORKPROJECT - The current project is not Teamwork project.

Remarks

This function is used to release the elements specified with the guid list. This function is a non-undoable data structure modifier function. See more details on this topic at Command Overview.

Example

GS::PagedArray<API_Guid> elements;
 
elements.Push (elementToRelease.header.guid);
 
ACAPI_Teamwork_ReleaseElements (elements);

ACAPI_Teamwork_ReleaseHotlinkCacheManagement()

GSErrCode ACAPI_Teamwork_ReleaseHotlinkCacheManagement

(

void

)

Releases the Hotlink/XRef Management in Teamwork mode.

Returns

• NoError - The function has completed with success.
• Error - The Hotlink/XRef Management is reserved by another team member.
• APIERR_NOPLAN - There is no open project.
• APIERR_NOTEAMWORKPROJECT - The current project is not a Teamwork project.

Remarks

This function is used to release the Hotlink/XRef Management. This function performs complete operations, so it cannot be called neither during undoable operations nor during non-undoable commands. See more details on this topic at Command Overview.

Example

GSErrCode err = ACAPI_Teamwork_ReleaseHotlinkCacheManagement ();
if (err != NoError) {
    ACAPI_WriteReport ("The Hotlink/XRef Management has been successfully released.", true);
}

ACAPI_Teamwork_ReleaseLockable()

GSErrCode ACAPI_Teamwork_ReleaseLockable	(	const API_Guid &	objectId,
		bool	enableDialogs = true
	)

Releases a lockable object set in Teamwork mode.

Since

Archicad 25

Parameters

objectId	[in] Unique identifier of the lockable object set
enableDialogs	[in] Show dialogs during the process?

Returns

• NoError - The function has completed with success.
• APIERR_NOPLAN - There is no open project.
• APIERR_NOTEAMWORKPROJECT - The current project is not Teamwork project.
• APIERR_BADID - The given objectId is not a valid lockable object set identifier.
• APIERR_SERVICEFAILED - The object set cannot be unlocked, or the operation has failed due to communication or server error.

Remarks

This function is used to release a lockable object set previously reserved by the current user. The modifications to the object set are sent to the server project right before the server actually unlocks the objects. This function is a non-undoable data structure modifier function. See more details on this topic at Command Overview.

Example

API_Guid objectSetGuid = ACAPI_Teamwork_FindLockableObjectSet ("LayerSettingsDialog");
API_LockableStatus lockableStatus = ACAPI_Teamwork_GetLockableStatus (objectSetGuid);
 
if (lockableStatus == APILockableStatus_Editable) {
    GSErrCode errCode = ACAPI_Teamwork_ReleaseLockable (objectSetGuid);
    if (errCode == NoError)
        ACAPI_WriteReport ("Layer Settings has been released succesfully", true);
    else
        ACAPI_WriteReport ("Releasing Layer Settings has failed", true);
} else {
    ACAPI_WriteReport ("Layer Settings was not reserved", true);
}

ACAPI_Teamwork_ReserveElements()

GSErrCode ACAPI_Teamwork_ReserveElements	(	const GS::Array< API_Guid > &	elements,
		GS::HashTable< API_Guid, short > *	conflicts = nullptr,
		bool	enableDialogs = true
	)

Reserves elements in Teamwork mode.

Since

Archicad 25

Parameters

elements	[in] List of elements to be reserved.
conflicts	[out] List of elements which cannot be reserved (optional, can be nullptr).
enableDialogs	[in] Show dialogs during the process? (optional, by default the dialogs are enabled)

Returns

• NoError - The function has completed with success.
• APIERR_NOPLAN - There is no open project.
• APIERR_NOTEAMWORKPROJECT - The current project is not Teamwork project.

Remarks

This function attempts to reserve the elements specified with the guid list. If the conflicts parameter is given, the function returns the list of unsuccessful reservations with the userId of the conflicting team members. This function is a non-undoable data structure modifier function. See more details on this topic at Command Overview.

Example

GS::PagedArray<API_Guid>        elements;
GS::HashTable<API_Guid, short>  conflicts;
 
elements.Push (elementToReserve.header.guid);
 
ACAPI_Teamwork_ReserveElements (elements, &conflicts);
if (conflicts.IsEmpty ())
    ACAPI_WriteReport ("The element has been reserved successfully", true);

ACAPI_Teamwork_ReserveHotlinkCacheManagement()

GSErrCode ACAPI_Teamwork_ReserveHotlinkCacheManagement

(

short *

conflict = nullptr

)

Reserves the Hotlink/XRef Management in Teamwork mode.

Parameters

conflict

[out] userId of the current owner if there is any (optional, can be nullptr).

Returns

• NoError - The function has completed with success.
• Error - The Hotlink/XRef Management is reserved by another team member.
• APIERR_NOPLAN - There is no open project.
• APIERR_NOTEAMWORKPROJECT - The current project is not a Teamwork project.

Remarks

This function is used to reserve the Hotlink/XRef Management. If the conflict parameter is given, it will contain the userId of the conflicting team member if there is any. You can find out more about the owner from the API_SharingInfo structure which can be obtained by calling the ACAPI_Environment function with the ACAPI_Teamwork_ProjectSharing function code. The userId of the current Teamwork Client can be retrieved from the API_ProjectInfo structure which can be obtained by calling the ACAPI_Environment function with the ACAPI_ProjectOperation_Project function code. This function performs complete operations, so it cannot be called neither during undoable operations nor during non-undoable commands. See more details on this topic at Command Overview.

Example

short conflict;
GSErrCode err = ACAPI_Teamwork_ReserveHotlinkCacheManagement (&conflict);
if (err != NoError) {
    ACAPI_WriteReport ("The Hotlink/XRef Management has been successfully reserved by this client.", true);
} else {
    ACAPI_WriteReport ("The Hotlink/XRef Management has already been reserved.", true);
}

ACAPI_Teamwork_ReserveLockable()

GSErrCode ACAPI_Teamwork_ReserveLockable	(	const API_Guid &	objectId,
		GS::PagedArray< short > *	conflicts = nullptr,
		bool	enableDialogs = true
	)

Reserves a lockable object set in Teamwork mode.

Since

Archicad 25

Parameters

objectId	[in] Unique identifier of the lockable object set
conflicts	[out] List of conflicting users (optional, can be nullptr or omitted)
enableDialogs	[in] Show dialogs during the process? (optional, by default the dialogs are enabled)

Returns

• NoError - The function has completed with success.
• APIERR_NOPLAN - There is no open project.
• APIERR_NOTEAMWORKPROJECT - The current project is not Teamwork project.
• APIERR_BADID - The given objectId is not a valid lockable object set identifier.
• APIERR_SERVICEFAILED - The lock cannot be obtained, or the operation has failed due to communication or server error.

Remarks

This function is used to reserve a lockable object set in Teamwork mode. Before reserving a lockable object set, make sure that the current user has sufficient privileges to edit the object set (ACAPI_Teamwork_HasDeleteModifyRight). It is recommended to check the locking status also before reservation (ACAPI_Teamwork_GetLockableStatus). Do not forget to release the lockable object set when reservation is not needed any more. This function is a non-undoable data structure modifier function. See more details on this topic at Command Overview.

Example

API_Guid objectSetGuid = ACAPI_Teamwork_FindLockableObjectSet ("Profiles");
API_LockableStatus lockableStatus = ACAPI_Teamwork_GetLockableStatus (objectSetGuid);
 
if (lockableStatus == APILockableStatus_Free) {
    GSErrCode errCode = ACAPI_Teamwork_ReserveLockable (objectSetGuid);
    if (errCode == NoError)
        ACAPI_WriteReport ("Profile attributes has been reserved succesfully", true);
    else
        ACAPI_WriteReport ("Reservation of Profile attributes has failed", true);
} else if (lockableStatus == APILockableStatus_Editable) {
    ACAPI_WriteReport ("Profile attributes has already been reserved", true);
} else {
    ACAPI_WriteReport ("Profile attributes cannot be reserved at the moment", true);
}

ACAPI_Teamwork_SendChanges()

GSErrCode ACAPI_Teamwork_SendChanges

(

const GS::UniString &

comment = GS::EmptyUniString

)

Sends changes to the BIMcloud server.

Since

Archicad 25

Parameters

comment

[in] Comment attached to the Send operation.

Returns

• NoError - The function has completed with success.
• APIERR_NOPLAN - There is no open project.
• APIERR_NOTEAMWORKPROJECT - The current project is not a Teamwork project.

Example

The Teamwork_Control
example project of the DevKit shows examples of how to use this function.

ACAPI_Teamwork_SendReleaseCommentMail()

GSErrCode ACAPI_Teamwork_SendReleaseCommentMail	(	const API_Guid &	objectId,
		short	dialogId
	)

Sends the release comment mail.

Parameters

objectId	[in] The unique identifier of this interface (that you passed during registration).
dialogId	[in] The dialog ID you registered the interface for.

Returns

• NoError - The function completed with success.

ACAPI_UnregisterTeamworkReserveInterface()

GSErrCode ACAPI_UnregisterTeamworkReserveInterface	(	const API_Guid &	objectId,
		short	dialogId = 0
	)

Unregisters a previously registered interface.

Parameters

objectId	[in] The unique identifier of this interface (that you passed during registration).
dialogId	[out] The dialog ID you registered the interface for.

Returns

• NoError - The function completed with success.
• APIERR_BADID - objectId is not registered.