Database Manager

Functions related to the Database Manager, creating, manupulating and switching between different databases. More...

Classes
struct	API_Region
	Polygonal or rectangular region of the model. More...
struct	API_DatabaseUnId
	Identification parameters of a Section, Detail, Interior Elevation, Worksheet, Master Layout, Layout, and 3D Document window or window related database. More...
struct	API_ClipTran
	Defines a transformation for the clipping. More...
struct	API_WindowValidatorInfo
	Holds information on elements and custom checksums that should be validated for the window. More...

Typedefs
typedef GSErrCode	APICustomWindowHandlerProc(const API_Guid &userRefId, API_NotifyWindowEventID notifID)
	User supplied callback function for handling events in windows opened by the add-on.
using	API_DatabaseInfo = API_WindowInfo
	Identification parameters of a project database.

Functions
GSErrCode	ACAPI_Window_GetCurrentWindow (API_WindowInfo *windowInfo)
	Returns the identifier of the current (active) window.
GSErrCode	ACAPI_Window_ResetCurrentWindow ()
	Deletes the database elements of the current window and sets up a new, empty environment.
GSErrCode	ACAPI_Window_NewWindow (API_NewWindowPars *newWindowPars, APICustomWindowHandlerProc *handlerProc=nullptr)
	Opens a new window.
GSErrCode	ACAPI_Window_CloseWindow (API_WindowInfo *windowInfo)
	Closes a window.
GSErrCode	ACAPI_Window_GetOwnWindows (API_WindowTypeID *windowTypeID, GS::Array< API_Guid > *guid=nullptr)
	Returns the ids of the opened windows in an array.
GSErrCode	ACAPI_Database_GetCurrentDatabase (API_DatabaseInfo *databaseInfo)
	Returns the identifier of the current (active) database.
GSErrCode	ACAPI_Window_ResetCurrentDatabase ()
	Deletes the database elements of the current window and sets up a new, empty environment.
GSErrCode	ACAPI_Database_ChangeCurrentDatabase (API_DatabaseInfo *databaseInfo)
	Changes the current (active) database.
GSErrCode	ACAPI_Database_RedrawCurrentDatabase ()
	Redraws the current database, even it's associated window is in the background.
GSErrCode	ACAPI_Database_RebuildCurrentDatabase ()
	Rebuilds the current database, even it's associated window is in the background.
GSErrCode	ACAPI_Database_NewDatabase (API_DatabaseInfo *databaseInfo, const API_Guid *parent=nullptr, const API_Guid *child=nullptr)
	Creates a new independent detail, worksheet, layout or master layout database.
GSErrCode	ACAPI_Database_ModifyDatabase (API_DatabaseInfo *databaseInfo)
	Modifies the parameters of an independent detail, worksheet, layout or master layout database.
GSErrCode	ACAPI_Database_DeleteDatabase (API_DatabaseInfo *databaseInfo)
	Deletes an independent detail, worksheet, layout, or master layout database.
GSErrCode	ACAPI_Window_GetDatabaseInfo (API_DatabaseInfo *databaseInfo, API_DatabaseUnId *databaseId=nullptr)
	Retrieves information of the given database.
GSErrCode	ACAPI_Database_GetDBUnIdFromGuid (API_Guid *elemSetId, short *userId, UInt32 *databaseId)
	Returns the old database identifiers from the database GUID.
GSErrCode	ACAPI_Database_GetGuidFromDBUnId (short *userId, UInt32 *databaseId, API_Guid *elemSetId)
	Returns the GUID from old database identifiers.
GSErrCode	ACAPI_Database_GetDetailDatabases (API_DatabaseUnId **databaseUnIds, GS::Array< API_DatabaseUnId > *databaseUnIdArray=nullptr)
	Returns the list of unique IDs of all detail databases.
GSErrCode	ACAPI_Database_GetLayoutDatabases (API_DatabaseUnId **databaseUnIds, GS::Array< API_DatabaseUnId > *databaseUnIdArray=nullptr)
	Returns the list of unique IDs of all layout databases.
GSErrCode	ACAPI_Database_GetMasterLayoutDatabases (API_DatabaseUnId **databaseUnIds, GS::Array< API_DatabaseUnId > *databaseUnIdArray=nullptr)
	Returns the list of unique IDs of all master layout databases.
GSErrCode	ACAPI_Window_AddTextWindowContent (API_WindowInfo *windowInfo, const char *content, const GS::UniString *uniContent=nullptr)
	Adds new lines to the content of a text window.
GSErrCode	ACAPI_Database_StartClippingSession ()
	Sets up clipping session for newly created elements to be clipped.
GSErrCode	ACAPI_Database_DoClip (API_Region *clipRegion, API_ClipTran *clipTran=nullptr)
	Clips the elements created during a clipping session.
GSErrCode	ACAPI_Database_StopClippingSession ()
	Stops clipping elements.
GSErrCode	ACAPI_Database_GetLocOrigo (API_Coord3D *locOrigin)
	Returns the local origin of the current database.
GSErrCode	ACAPI_Database_GetSectionDatabases (API_DatabaseUnId **databaseUnIds, GS::Array< API_DatabaseUnId > *databaseUnIdArray=nullptr)
	Returns all the section databases in the project.
GSErrCode	ACAPI_Database_GetElevationDatabases (API_DatabaseUnId **databaseUnIds, GS::Array< API_DatabaseUnId > *databaseUnIdArray=nullptr)
	Returns all the elevation databases in the project.
GSErrCode	ACAPI_Database_GetInteriorElevationDatabases (API_DatabaseUnId **databaseUnIds, GS::Array< API_DatabaseUnId > *databaseUnIdArray=nullptr)
	Returns all the interior elevation databases in the project.
GSErrCode	ACAPI_Database_GetWorksheetDatabases (API_DatabaseUnId **databaseUnIds, GS::Array< API_DatabaseUnId > *databaseUnIdArray=nullptr)
	Returns the list of unique IDs of all detail databases.
GSErrCode	ACAPI_Database_GetDocumentFrom3DDatabases (API_DatabaseUnId **databaseUnIds, GS::Array< API_DatabaseUnId > *databaseUnIdArray=nullptr)
	Returns the list of unique IDs of all document 3D databases.
GSErrCode	ACAPI_Database_GetContainingDatabase (const API_Guid *element, API_DatabaseInfo *dbInfo)
	Obtains the unique ID of database contains the given element.
GSErrCode	ACAPI_Database_BuildWindowValidator (const API_WindowValidatorInfo *pValidatorInfo)
	Registers a new window validator for the given guid.
GSErrCode	ACAPI_Window_DestroyWindowValidator (const API_Guid *pGuid)
	Destroys an already registered validator for the given guid.
GSErrCode	ACAPI_Database_CheckWindowValidator (const API_WindowValidatorInfo *pValidatorInfo, bool *pContentChanged)
	Cheks the already added list of elements and checksums form the validator (identified by the guid) against the lists from the parameter if there was any changes.
GSErrCode	ACAPI_Database_RebuildWindowValidator (const API_WindowValidatorInfo *pValidatorInfo)
	Sets the element and checksum list for an already added validator with given guid.
GSErrCode	ACAPI_Database_JsonQuery (const GS::UniString *query, GS::UniString *result)
	Helper function to call various functions inside Archicad.
GS::Array< API_DatabaseUnId >	ACAPI_Database_GetDatabasesForType (const API_DatabaseTypeID &id)
	Helper function to collect all Archicad databases of the given type.
GS::Array< API_DatabaseUnId >	ACAPI_Database_GetDatabasesForTypes (const GS::Array< API_DatabaseTypeID > &ids)
	Helper function to collect all Archicad databases of the given types.

Detailed Description

Functions related to the Database Manager, creating, manupulating and switching between different databases.

Database Overview

The API enables you to work on the Archicad database. Various functions are present to create, get, modify and also delete elements, attributes and library parts. It is also possible to control the selection of elements, and some settings of the overall environment; for example stories, grid settings, etc.

To read the rules of data structure modifications, please read Command Overview paper.

In this section, some information is provided about how the Virtual Building database is built up, and what the links are among the different components.

---

Elements

Database items named elements directly appear in one of the project windows. Their parameters can be set in the Settings Dialogs or in the Info Box. Most of them refer to many attributes, some of them to library parts.

API functions operating on elements begin with the ACAPI_Element_ prefix. Refer to the Element Manager to see the whole collection of functions that support element manipulations.

API structures referenced by the handler functions are explained in details in the Element Database document. Refer to this document to get specific information about the data structures related to all element types.

To read general information about elements refer to the Element Overview paper.

---

Properties

Properties allows one to store user-defined name-value pairs for Model elements.

To read general information about properties refer to the Properties paper.

---

Classifications

Classifications allows one to classify elements and create custom classifications.

To read general information about classifications refer to the Classification paper.

---

Attributes

Database items named attributes are global collections of layers, pen colors, surface materials, fill patterns, etc. that are available to all eligible tools. These attribute sets are editable, and the lists and palettes in the Tool Settings dialog boxes display their current settings.

API functions operating on attributes begin with the ACAPI_Attribute_ prefix. Refer to the Attribute Manager to see the whole collection of functions that support attribute manipulations.

API structures referenced by the handler functions are explained in details in the Attribute Database document. Refer to these papers to get specific information about the data structures related to all attribute types.

To read general information about attributes refer to the Attribute Overview paper.

The API also provides a platform-independent way to use those custom controls in Archicad which provide the user a list of certain attributes he can choose from. You can read more on this in the FAQ.

---

Library Parts

Database items named Library Parts are prefabricated elements which may have instances in the project with different parameters like scaling, rotation, etc. Many elements have a reference to a specific Library Part, like windows, objects, rooms, etc. Library Parts can be created and edited through the Library Part editor dialog. The active library folders can be controlled through the Library Manager... dialog of Archicad. From v4.1, you may receive notification when the loaded libraries change.

API functions operating on a Library Part file begin with the ACAPI_LibraryPart_ prefix. Refer to the Library Part Manager to see the available collection of functions to manage a Library Part file.

API structures referenced by the handler functions are explained in details in the Library document. Refer to these papers to get specific information about the data structures related to a Library Part file.

To read general information about library parts refer to the LibPart Overview paper.

---

Structural Analytical Model

To read general information about the Structural Analytical Model refer to the Analytical Model Overview paper.

---

Environment

There are database items which do not fit into any categories listed above, but have influence on the project's appearance and to the behavior of elements; such as the preferences like parameters, the drawing scale, the 3D projection parameters and so on.

Typedef Documentation

API_DatabaseInfo

using API_DatabaseInfo = API_WindowInfo

Identification parameters of a project database.

Remarks

Database reference is used for several purposes:

• Returned while asking for the active database
• Must be setup when changing the current database
• Defines the database when creating/modifying/deleting an independent detail, worksheet, layout, or master layout database The databases are referenced with their unique ID, except Floor Plan, 3D Model, and custom window databases. The unique IDs can be found in the connecting elements (API_CutPlaneType, API_DetailType, API_WorksheetType) or listed for independent detail, worksheet, layout, and master layout databases (ACAPI_Database_GetDetailDatabases, ACAPI_Database_GetWorksheetDatabases, ACAPI_Database_GetLayoutDatabases, ACAPI_Database_GetMasterLayoutDatabases respectively). In Floor Plan and 3D Model databases, the typeID field is enough to identify them. Custom API windows (APIWind_MyDrawID, APIWind_MyTextID) are identified with typeID and index. Featuring API 10 With this structure, you can retrieve the name, the title, and the reference ID of a given window/database (see ACAPI_Window_GetDatabaseInfo). You can also rename independent detail, worksheet, layout, and master layout databases using the name and ref fields in ACAPI_Database_ModifyDatabase. See also API_WindowInfo.

APICustomWindowHandlerProc

typedef GSErrCode APICustomWindowHandlerProc(const API_Guid &userRefId, API_NotifyWindowEventID notifID)

User supplied callback function for handling events in windows opened by the add-on.

Parameters

userRefId	[in] The reference GUID of the custom window, as supplied to ACAPI_Window_NewWindow.
notifID	[in] The type of the event for the custom window.

Returns

• NoError - The function has completed with success.

Remarks

This function will be called when installed with ACAPI_Window_NewWindow. The following types of events will come for your custom window:

Event type	Description
APINotifyWindow_Rebuild	The user chose Rebuild from the menu.
APINotifyWindow_Activate	Your window was activated.
APINotifyWindow_Close	The user closed your window.

Function Documentation

ACAPI_Database_BuildWindowValidator()

GSErrCode ACAPI_Database_BuildWindowValidator

(

const API_WindowValidatorInfo *

pValidatorInfo

)

Registers a new window validator for the given guid.

Parameters

pValidatorInfo

Contains the guid of a window which will be the owner of the new validator and an element and checksum list to track their changes.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - pValidatorInfo is nullptr
• APIERR_MEMFULL - Not enough memory to complete the operation.
• APIERR_GENERAL - There is already a validator registered for this guid.

ACAPI_Database_ChangeCurrentDatabase()

GSErrCode ACAPI_Database_ChangeCurrentDatabase

(

API_DatabaseInfo *

databaseInfo

)

Changes the current (active) database.

Since

Archicad 25

Parameters

databaseInfo

[in] parameters of the database to be created (type, reference index)

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - databasePars is nullptr
• APIERR_NOPLAN - no open project
• APIERR_BADDATABASE - the requested database does not exist

Remarks

This function is used to change the current database in the background. All the subsequent API calls to any database dependent function will work on the specified database. This function can be very expensive in case of low memory condition. The server application tries to keep as many database object in the memory as possibly, however it can happen, that some of them must be swapped out. Switching to an other database means, that the server application loads it into the memory, which may cause others to be unloaded. It can be a relatively long time. Refer to the ACAPI_Window_ChangeWindow function in the case you want to change not only the database in the background, but the current front window also.

Example

GSErrCode ChangeCurrentDatabaseToDatabaseOfSectionElement (const API_Guid& guid)
{
    API_Element element = {};
    element.header.guid = guid;
 
    GSErrCode err = ACAPI_Element_Get (&element);
 
    if (err != NoError)
        return err;
 
    if (element.header.type != API_CutPlaneID)
        return Error;
 
    API_DatabaseInfo databasePars = {};
    databasePars.typeID = APIWind_SectionID;
    databasePars.databaseUnId = element.cutPlane.segment.databaseID;
 
    err = ACAPI_Database (APIDb_ChangeCurrentDatabaseID, &databasePars);
 
    return err;
}

ACAPI_Database_CheckWindowValidator()

GSErrCode ACAPI_Database_CheckWindowValidator	(	const API_WindowValidatorInfo *	pValidatorInfo,
		bool *	pContentChanged
	)

Cheks the already added list of elements and checksums form the validator (identified by the guid) against the lists from the parameter if there was any changes.

Parameters

pValidatorInfo	Contains the guid of a window which is the owner of the validator and the current, and the element and checksum list to check against.
pContentChanged	Out paramter for the result. true if there was a change false otherwise.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - pValidatorInfo or pContentChanged is nullptr
• APIERR_MEMFULL - Not enough memory to complete the operation.
• APIERR_GENERAL - There is no validator registered for this guid.

Remarks

This function is a non-undoable data structure modifier function. See more details on this topic at Command Overview.

ACAPI_Database_DeleteDatabase()

GSErrCode ACAPI_Database_DeleteDatabase

(

API_DatabaseInfo *

databaseInfo

)

Deletes an independent detail, worksheet, layout, or master layout database.

Parameters

databaseInfo

[in] parameters of the database to be deleted

Returns

• NoError - The function has completed with success.
• APIERR_NOPLAN - no floor plan window opened
• APIERR_BADPARS - api_dbInfo is nullptr, or contains invalid database reference
• APIERR_REFUSEDPAR - the passed typeID is not APIWind_DetailID, APIWind_WorksheetID, APIWind_LayoutID or APIWind_MasterLayoutID
• APIERR_REFUSEDCMD - attempted to delete database during signing in a Teamwork file
• APIERR_NOTMINE - unsufficient privileges to delete database in Teamwork mode
• APIERR_GENERAL - failed to delete the database

Remarks

This function is used to delete an independent detail drawing, worksheet layout or master layout database. This operation is not undoable. 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

API_DatabaseInfo dbInfo;
BNZeroMemory (&dbInfo, sizeof (API_DatabaseInfo));
 
GSErrCode err = ACAPI_Database (APIDb_GetCurrentDatabaseID, &dbInfo, nullptr);
if (err == NoError && dbInfo.typeID == APIWind_LayoutID)
    ACAPI_Database (APIDb_DeleteDatabaseID, &dbInfo, nullptr);

ACAPI_Database_DoClip()

GSErrCode ACAPI_Database_DoClip	(	API_Region *	clipRegion,
		API_ClipTran *	clipTran = nullptr
	)

Clips the elements created during a clipping session.

Parameters

clipRegion	the region to clip elements to
clipTran	clipping transformation

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - clipRegion is nullptr
• APIERR_NESTING - the clip session is opened for the database

Remarks

You can create elements to be clipped into the current database with a clipping region and transformation. Use the ACAPI_Database_StartClippingSession database function to open a temporary database, create the elements with ACAPI_Element_Create into it, then call ACAPI_Database_DoClip to merge them into the actual database applying the given clipping parameters. Don't forget to close the clipping session with the ACAPI_Database_StopClippingSession database function to restore the target database. Note that only the 2D drawing elements will be clipped. Construction elements, like walls, columns will NOT take part in the clipping algorithm.

Example

API_Region          clipRegion;
API_Element         element;
GSErrCode           err;
 
BNZeroMemory (&clipRegion, sizeof (API_Region));
clipRegion.box.xMin = 0.0;
clipRegion.box.xMax = 2.0;
clipRegion.box.yMin = 1.54;
clipRegion.box.yMax = 2.54;
 
err = ACAPI_Database (APIDb_StartClippingSessionID, nullptr, nullptr);
if (err == NoError) {
    /* ... */
    err = ACAPI_Element_Create (&element, nullptr);
    /* ... */
    err = ACAPI_Database (APIDb_DoClipID
, &clipRegion, nullptr);
}
err = ACAPI_Database (APIDb_StopClippingSessionID, nullptr, nullptr);

ACAPI_Database_GetContainingDatabase()

GSErrCode ACAPI_Database_GetContainingDatabase	(	const API_Guid *	element,
		API_DatabaseInfo *	dbInfo
	)

Obtains the unique ID of database contains the given element.

Parameters

element	[in] The referred element.
dbInfo	[out] The owner database ID.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - The guid or dbInfo parameter is nullptr.
• APIERR_NOPLAN - There is no open project.

Remarks

This function is used to get the ID of owner database of the referred element.

ACAPI_Database_GetCurrentDatabase()

GSErrCode ACAPI_Database_GetCurrentDatabase

(

API_DatabaseInfo *

databaseInfo

)

Returns the identifier of the current (active) database.

Parameters

databaseInfo

[out] The identification parameters of the current database

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - databaseInfo is nullptr
• APIERR_BADWINDOW - the type of the current database is not known by the API

Remarks

This function is used to return the parameters of the current database of the server application. It can be used to identify which database the subsequent API calls will work on. Generally the current window and the window of the current database are the same. However you must be careful; the database dependent functions work on the current database not on the database of the current window. You can change the current database by calling the ACAPI_Database_ChangeCurrentDatabase function.

Example

API_DatabaseInfo    databaseInfo;
GSErrCode           err;
 
BNZeroMemory (&databaseInfo, sizeof (API_DatabaseInfo));
err = ACAPI_Database (APIDb_GetCurrentDatabaseID, &databaseInfo, nullptr);

ACAPI_Database_GetDatabasesForType()

GS::Array< API_DatabaseUnId > ACAPI_Database_GetDatabasesForType

(

const API_DatabaseTypeID &

id

)

Helper function to collect all Archicad databases of the given type.

Parameters

id	The database type to collect.

Returns

A list of database idetifiers for the given type, or any empty list if no such databases exist in the current project.

ACAPI_Database_GetDatabasesForTypes()

GS::Array< API_DatabaseUnId > ACAPI_Database_GetDatabasesForTypes

(

const GS::Array< API_DatabaseTypeID > &

ids

)

Helper function to collect all Archicad databases of the given types.

Parameters

ids	List of database types to collect.

Returns

A list of database idetifiers for the given types, or any empty list if no such databases exist in the current project.

ACAPI_Database_GetDBUnIdFromGuid()

GSErrCode ACAPI_Database_GetDBUnIdFromGuid	(	API_Guid *	elemSetId,
		short *	userId,
		UInt32 *	databaseId
	)

Returns the old database identifiers from the database GUID.

Parameters

elemSetId	[in] Unique identifier of the database.
userId	[out] First old identifier.
databaseId	[out] Second old identifier.

Returns

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

Remarks

This function is used to convert the old database identifiers to the new guid.

Example

API_DatabaseInfo databaseInfo;
ACAPI_Database (APIDb_GetCurrentDatabaseID
, &databaseInfo, nullptr);
 
UInt32 currentDatabaseId;
short  userId;
 
ACAPI_Database (APIDb_GetDBUnIdFromGuidID
, &databaseInfo.databaseUnId.elemSetId, &userId, &currentDatabaseId);

ACAPI_Database_GetDetailDatabases()

GSErrCode ACAPI_Database_GetDetailDatabases	(	API_DatabaseUnId **	databaseUnIds,
		GS::Array< API_DatabaseUnId > *	databaseUnIdArray = nullptr
	)

Returns the list of unique IDs of all detail databases.

Parameters

databaseUnIds	[out] The list of detail database unique IDs. Note this is not handle; it's the address of a pointer. See the example below.
databaseUnIdArray	[out] the array of detail databases, in a more recent form. Pass the address of an appropriate GS::Array<> to get the result. This parameter has precedence over the other databaseUnIds parameter.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - dbUnIDs is nullptr
• APIERR_NOPLAN - the plan database does not exist

Remarks

This function is used to return the database unique IDs of all detail databases, including independent details as well. Currently this is the only way you can access independent details. Independent details don't have a corresponding detail marker on the floor plan or in any of the sections/elevations. One detail database may belong to many detail markers (i.e. if you place the same marker several times, they will all refer to the same detail database). You can switch to any of the detail databases by calling the ACAPI_Database_ChangeCurrentDatabase function.

Example

The Attribute Manager add-on uses this function to collect all the used attributes from the detail databases.

ACAPI_Database_GetDocumentFrom3DDatabases()

GSErrCode ACAPI_Database_GetDocumentFrom3DDatabases	(	API_DatabaseUnId **	databaseUnIds,
		GS::Array< API_DatabaseUnId > *	databaseUnIdArray = nullptr
	)

Returns the list of unique IDs of all document 3D databases.

Parameters

databaseUnIds	[out] The list of document 3D database unique IDs. Note this is not handle; it's the address of a pointer. See the example below.
databaseUnIdArray	[out] the array of 3D document databases, in a more recent form. Pass the address of an appropriate GS::Array<> to get the result. This parameter has precedence over the other databaseUnIds parameter.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - dbUnIDs is nullptr
• APIERR_NOPLAN - the plan database does not exist

Remarks

This function is used to return the database unique IDs of all document 3D databases. Currently this is the only way you can access these kind of databases because they don't have markers. You can switch to any of the other databases by calling the ACAPI_Database_ChangeCurrentDatabase function.

Example

The Attribute Manager add-on uses this function to collect all the used attributes from the document 3D databases.

ACAPI_Database_GetElevationDatabases()

GSErrCode ACAPI_Database_GetElevationDatabases	(	API_DatabaseUnId **	databaseUnIds,
		GS::Array< API_DatabaseUnId > *	databaseUnIdArray = nullptr
	)

Returns all the elevation databases in the project.

Parameters

databaseUnIds	the array of elevation databases (address of a pointer! not a handle).
databaseUnIdArray	[out] the array of elevation databases, in a more recent form. Pass the address of an appropriate GS::Array<> to get the result. This parameter has precedence over the other databaseUnIds parameter.

Returns

• NoError - The function has completed with success.

Remarks

Don't forget to dispose the allocated pointer with BMpFree.

ACAPI_Database_GetGuidFromDBUnId()

GSErrCode ACAPI_Database_GetGuidFromDBUnId	(	short *	userId,
		UInt32 *	databaseId,
		API_Guid *	elemSetId
	)

Returns the GUID from old database identifiers.

Parameters

userId	[in] First old identifier.
databaseId	[in] Second old identifier.
elemSetId	[out] Unique identifier of the database.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - One of the parameters is nullptr. Or databaseId is 0.

Remarks

This function is used to convert new database identifier guid to the old identifiers.

Example

The Environment Control example add-on uses this function to get floor plan s guid.

ACAPI_Database_GetInteriorElevationDatabases()

GSErrCode ACAPI_Database_GetInteriorElevationDatabases	(	API_DatabaseUnId **	databaseUnIds,
		GS::Array< API_DatabaseUnId > *	databaseUnIdArray = nullptr
	)

Returns all the interior elevation databases in the project.

Parameters

databaseUnIds	the array of interior elevation databases (address of a pointer! not a handle).
databaseUnIdArray	[out] the array of interior elevation databases, in a more recent form. Pass the address of an appropriate GS::Array<> to get the result. This parameter has precedence over the other databaseUnIds parameter.

Returns

• NoError - The function has completed with success.

Remarks

Don't forget to dispose the allocated pointer with BMpFree.

ACAPI_Database_GetLayoutDatabases()

GSErrCode ACAPI_Database_GetLayoutDatabases	(	API_DatabaseUnId **	databaseUnIds,
		GS::Array< API_DatabaseUnId > *	databaseUnIdArray = nullptr
	)

Returns the list of unique IDs of all layout databases.

Parameters

databaseUnIds	[out] The list of layout database unique IDs. Note: this is not handle; it's the address of a pointer. You'll have to dispose it with BMpFree when you don't need it any more.
databaseUnIdArray	[out] the array of layout databases, in a more recent form. Pass the address of an appropriate GS::Array<> to get the result. This parameter has precedence over the other databaseUnIds parameter.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - dbUnIDs is nullptr
• APIERR_NOPLAN - the plan database does not exist

Remarks

You can get the list of all layout databases with this function, then you can use ACAPI_Database_ChangeCurrentDatabase to switch to that database.

Example

See the Example of the APIDb_GetDatabaseInfoID
function.

ACAPI_Database_GetLocOrigo()

GSErrCode ACAPI_Database_GetLocOrigo

(

API_Coord3D *

locOrigin

)

Returns the local origin of the current database.

Parameters

locOrigin

the local origin

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - locOrigin is nullptr
• APIERR_BADDATABASE - the query is valid only for the plan, section, detail and 3D window.

Remarks

This function is used to get the local origin of the current database. This can be modified by the user by clicking on the User Origin button on the coordinate box. The value is measured relative to the origin of the virtual coordinate system.

ACAPI_Database_GetMasterLayoutDatabases()

GSErrCode ACAPI_Database_GetMasterLayoutDatabases	(	API_DatabaseUnId **	databaseUnIds,
		GS::Array< API_DatabaseUnId > *	databaseUnIdArray = nullptr
	)

Returns the list of unique IDs of all master layout databases.

Parameters

databaseUnIds	[out] The list of master layout database unique IDs. Note this is not handle; it's the address of a pointer.
databaseUnIdArray	[out] the array of master layout databases, in a more recent form. Pass the address of an appropriate GS::Array<> to get the result. This parameter has precedence over the other databaseUnIds parameter.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - dbUnIDs is nullptr
• APIERR_NOPLAN - the plan database does not exist

Remarks

You can use this function to enumerate all master layout databases.

Example

See the Example of the APIDb_GetDatabaseInfoID
function.

ACAPI_Database_GetSectionDatabases()

GSErrCode ACAPI_Database_GetSectionDatabases	(	API_DatabaseUnId **	databaseUnIds,
		GS::Array< API_DatabaseUnId > *	databaseUnIdArray = nullptr
	)

Returns all the section databases in the project.

Parameters

databaseUnIds	the array of section databases (address of a pointer! not a handle).
databaseUnIdArray	[out] the array of section databases, in a more recent form. Pass the address of an appropriate GS::Array<> to get the result. This parameter has precedence over the other databaseUnIds parameter.

Returns

• NoError - The function has completed with success.

Remarks

Don't forget to dispose the allocated pointer with BMpFree.

ACAPI_Database_GetWorksheetDatabases()

GSErrCode ACAPI_Database_GetWorksheetDatabases	(	API_DatabaseUnId **	databaseUnIds,
		GS::Array< API_DatabaseUnId > *	databaseUnIdArray = nullptr
	)

Returns the list of unique IDs of all detail databases.

Parameters

databaseUnIds	[out] The list of worksheet database unique IDs. Note this is not handle; it's the address of a pointer. See the example below.
databaseUnIdArray	[out] the array of worksheet databases, in a more recent form. Pass the address of an appropriate GS::Array<> to get the result. This parameter has precedence over the other databaseUnIds parameter.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - dbUnIDs is nullptr
• APIERR_NOPLAN - the plan database does not exist

Remarks

This function is used to return the database unique IDs of all worksheets databases, including independent details as well. Currently this is the only way you can access independent details. [Independent worksheets don't have a corresponding detail marker on the floor plan or in any of the sections/elevations.???] [One worksheet database may belong to many worksheet markers (i.e. if you place the same marker several times, they will all refer to the same worksheet database).???] You can switch to any of the worksheet databases by calling the ACAPI_Database_ChangeCurrentDatabase function.

Example

The Attribute Manager add-on uses this function to collect all the used attributes from the detail databases.

ACAPI_Database_JsonQuery()

GSErrCode ACAPI_Database_JsonQuery	(	const GS::UniString *	query,
		GS::UniString *	result
	)

Helper function to call various functions inside Archicad.

Parameters

query	The request towards Archicad
result	The answer from Archicad

Returns

• NoError - The function has completed with success.
• Other error code - query is invalid.

Remarks

The following queries/commands are available:

Query	Result
"getTopWindow"	The title of the top window.
"lineConsolidation"	Calls the Line Consolidation menu command.
"fillNormalization"	Calls the Fill Consolidation menu command.
"usedAttributes"	Returns the list of used attributes.
"numberOfTraceReferences"	Returns the number of trace references.

ACAPI_Database_ModifyDatabase()

GSErrCode ACAPI_Database_ModifyDatabase

(

API_DatabaseInfo *

databaseInfo

)

Modifies the parameters of an independent detail, worksheet, layout or master layout database.

Parameters

databaseInfo

[in/out] parameters of the database to be created

Returns

• NoError - the function has completed with success.
• APIERR_NOPLAN - no floor plan window opened
• APIERR_BADPARS - databaseInfo is nullptr
• APIERR_REFUSEDPAR - the passed typeID is not APIWind_DetailID, APIWind_WorksheetID, APIWind_LayoutID or APIWind_MasterLayoutID
• APIERR_REFUSEDCMD - attempted to modify database parameters during signing in a Teamwork file
• APIERR_NOTMINE - unsufficient privileges to modify database parameters in Teamwork mode
• APIERR_GENERAL - failed to modify the database parameters

Remarks

With this function you can rename an independent detail, worksheet, layout or master layout database, and change their reference ID. Note that you cannot change the title parameter of the database. You can also change the Master of a Layout database by passing a valid masterLayoutUnId. This function is a non-undoable data structure modifier function. See more details on this topic at Command Overview.

Example

API_DatabaseInfo dbInfo;
BNZeroMemory (&dbInfo, sizeof (API_DatabaseInfo));
 
GSErrCode err = ACAPI_Database (APIDb_GetCurrentDatabaseID, &dbInfo, nullptr);
if (err == NoError && dbInfo.typeID == APIWind_LayoutID) {
    CHCopyC ("Renamed Layout", dbInfo.name);
    ACAPI_Database (APIDb_ModifyDatabaseID, &dbInfo, nullptr);
}

ACAPI_Database_NewDatabase()

GSErrCode ACAPI_Database_NewDatabase	(	API_DatabaseInfo *	databaseInfo,
		const API_Guid *	parent = nullptr,
		const API_Guid *	child = nullptr
	)

Creates a new independent detail, worksheet, layout or master layout database.

Parameters

databaseInfo	[in/out] parameters of the database to be created
parent	The parent of the new item.
child	If it is nullptr, then the new item will be inserted to the first place on the actual level, otherwise the it will be inserted after the child.

Returns

• NoError - the function has completed with success.
• APIERR_REFUSEDCMD - the function was refused to execute, because it was called inside an undo scope.
• APIERR_NOPLAN - no floor plan window opened
• APIERR_BADPARS - databaseInfo is nullptr
• APIERR_REFUSEDPAR - the passed typeID is not APIWind_DetailID, APIWind_WorksheetID, APIWind_LayoutID or APIWind_MasterLayoutID
• APIERR_GENERAL - could not create new database

Remarks

This function is used to create a new database with the given name and ref parameters. No associated window will be opened. In case of Layout databases you must specify an existing Master Layout in masterLayoutUnId. If the database is created successfully, the unique ID of the database returns in the databaseUnId field. This function is a non-undoable data structure modifier function. See more details on this topic at Command Overview.

Example

API_DatabaseInfo dbInfo;
BNZeroMemory (&dbInfo, sizeof (API_DatabaseInfo));
dbInfo.typeID = APIWind_DetailID;
sprintf (dbInfo.name, "Dooku 1");
sprintf (dbInfo.ref, "D01");
 
if (ACAPI_Database (APIDb_NewDatabaseID, &dbInfo, nullptr) == NoError) {
    char msgStr[1024];
    sprintf (msgStr, "New detail database is created with unId:%d-%d", dbInfo.databaseUnId.id1, dbInfo.databaseUnId.id2);
    ACAPI_WriteReport (msgStr, true);
}

ACAPI_Database_RebuildCurrentDatabase()

GSErrCode ACAPI_Database_RebuildCurrentDatabase

(

)

Rebuilds the current database, even it's associated window is in the background.

Returns

• NoError - The function has completed with success.
• APIERR_NOPLAN - No open project.

Remarks

This function is used to rebuild the current database in the background. Only the visible region of the associated window will be updated. This function is a non-undoable data structure modifier function. See more details on this topic at Command Overview.

ACAPI_Database_RebuildWindowValidator()

GSErrCode ACAPI_Database_RebuildWindowValidator

(

const API_WindowValidatorInfo *

pValidatorInfo

)

Sets the element and checksum list for an already added validator with given guid.

Parameters

pValidatorInfo

Contains the guid of a window which is the owner of the validator and the new element and checksum list.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - pValidatorInfo is nullptr
• APIERR_MEMFULL - Not enough memory to complete the operation.
• APIERR_GENERAL - There is no validator registered for this guid.

Remarks

This function is a non-undoable data structure modifier function. See more details on this topic at Command Overview.

ACAPI_Database_RedrawCurrentDatabase()

GSErrCode ACAPI_Database_RedrawCurrentDatabase

(

)

Redraws the current database, even it's associated window is in the background.

Returns

• NoError - The function has completed with success.
• APIERR_NOPLAN - No open project.

Remarks

This function is used to redraw the current database in the background. Only the visible region of the associated window will be updated from the update picture.

ACAPI_Database_StartClippingSession()

GSErrCode ACAPI_Database_StartClippingSession

(

)

Sets up clipping session for newly created elements to be clipped.

Returns

• NoError - The function has completed with success.
• APIERR_NESTING - the clip session is opened for the database

Remarks

This function creates a temporary database and redirects the subsequent ACAPI_Element_Create calls into it. The elements created during this session then can be copied into the actual element database with the ACAPI_Database_DoClip command applying the given clipping region and transformation. You must close the clipping session with the ACAPI_Database_StopClippingSession database function to restore the target database. Note that only the 2D drawing elements will be clipped. Construction elements, like walls, columns will NOT take part in the clipping algorithm.

Example

API_Region          clipRegion;
API_Element         element;
GSErrCode           err;
 
BNZeroMemory (&clipRegion, sizeof (API_Region));
clipRegion.box.xMin = 0.0;
clipRegion.box.xMax = 2.0;
clipRegion.box.yMin = 1.54;
clipRegion.box.yMax = 2.54;
 
err = ACAPI_Database (APIDb_StartClippingSessionID
, nullptr, nullptr);
if (err == NoError) {
    /* ... */
    err = ACAPI_Element_Create (&element, nullptr);
    /* ... */
    err = ACAPI_Database (APIDb_DoClipID, &clipRegion, nullptr);
}
err = ACAPI_Database (APIDb_StopClippingSessionID, nullptr, nullptr);

ACAPI_Database_StopClippingSession()

GSErrCode ACAPI_Database_StopClippingSession

(

)

Stops clipping elements.

Returns

• NoError - The function has completed with success.
• APIERR_GENERAL - no opened clipping session for the database

Remarks

This function is used to close the automatic clip service of the server application. Use when a clipping session has been opened by the ACAPI_Database_StartClippingSession database function, if clipping newly created elements is not necessary any more.

ACAPI_Window_AddTextWindowContent()

GSErrCode ACAPI_Window_AddTextWindowContent	(	API_WindowInfo *	windowInfo,
		const char *	content,
		const GS::UniString *	uniContent = nullptr
	)

Adds new lines to the content of a text window.

Parameters

windowInfo	[in] window identification
content	[in] the text to append
uniContent	[in] the Unicode text to append

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - windowPars is nullptr,
• APIERR_REFUSEDPAR - not APIWind_MyTextID is referenced,
• APIERR_WINDNOTEXIST - the referenced window does not exist

Remarks

This function is used to append new lines to a text window. It is limited to use for custom text windows only, which is opened by ACAPI_Window_NewWindow in the same addon. The Report Window, Missing Library Parts Window etc cannot be addressed with this function. The string must be '\0' terminated. Line feeds should be passed with '
' characters.

Example

API_WindowInfo      windowInfo = {};
GS::UniString       buffer;
GSErrCode           err;
 
windowInfo.typeID = APIWind_MyTextID;
windowInfo.refCon = 1;
 
buffer = GS::UniString::Printf ("Number of lines: %d\nOK\n", nLine);
 
err = ACAPI_Database (APIDb_AddTextWindowContentID, &windowInfo, nullptr, &buffer);

ACAPI_Window_CloseWindow()

GSErrCode ACAPI_Window_CloseWindow

(

API_WindowInfo *

windowInfo

)

Closes a window.

Parameters

windowInfo

parameters of the window to be closed (type and reference index)

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - windowPars is nullptr.
• APIERR_REFUSEDCMD - the function is called from notification level.
• APIERR_REFUSEDPAR - not APIWind_MyTextID or APIWind_MyDrawID is requested.
• APIERR_WINDNOTEXIST - a window with the same type and reference index is not opened.
• APIERR_NOPLAN - no open project

Remarks

This function is used to close a previously opened custom window. It is the inverse function of ACAPI_Window_NewWindow, so it is limited to close simple text or drawing windows. Such a window can be closed from the same addon, which it was opened from.

Example

API_WindowInfo      windowInfo;
GSErrCode           err;
 
BNZeroMemory (&windowInfo, sizeof (API_WindowInfo));
windowInfo.typeID = APIWind_MyDrawID;
windowInfo.index  = 1;
 
err = ACAPI_Database (APIDb_CloseWindowID, &windowInfo, nullptr);

ACAPI_Window_DestroyWindowValidator()

GSErrCode ACAPI_Window_DestroyWindowValidator

(

const API_Guid *

pGuid

)

Destroys an already registered validator for the given guid.

Parameters

pGuid

The guid of the owner window of the validator.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - pValidatorInfo is nullptr
• APIERR_MEMFULL - Not enough memory to complete the operation.
• APIERR_GENERAL - There is no validator registered for this guid.

ACAPI_Window_GetCurrentWindow()

GSErrCode ACAPI_Window_GetCurrentWindow

(

API_WindowInfo *

windowInfo

)

Returns the identifier of the current (active) window.

Parameters

windowInfo

[out] The identification parameters of the front window

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - windowInfo is nullptr.
• APIERR_BADWINDOW - the type of the current front window is not known by the API

Remarks

This function is used to return the parameters of the front window of the server application. It can be used to identify which window your command was called on. Generally the current window and the window of the current database are the same. However you must be careful; the database dependent functions work on the current database not on the database of the current window. The interface functions work on the current window always. Note that this function fills out only the fields which are needed to identify the window type and the database behind the window. In order to retrieve the additional parameters of the database (title, name, ref, masterLayoutUnId) call the ACAPI_Window_GetDatabaseInfo function with the databaseUnId of the current window. Use the ACAPI_Window_ChangeWindow function to change the current window.

Example

API_WindowInfo windowInfo;
BNZeroMemory (&windowInfo, sizeof (API_WindowInfo));
GSErrCode err = ACAPI_Database (APIDb_GetCurrentWindowID, &windowInfo, nullptr);

ACAPI_Window_GetDatabaseInfo()

GSErrCode ACAPI_Window_GetDatabaseInfo	(	API_DatabaseInfo *	databaseInfo,
		API_DatabaseUnId *	databaseId = nullptr
	)

Retrieves information of the given database.

Parameters

databaseInfo	[in/out] parameters of the database
databaseId	[out] Second old identifier.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - databaseInfo is nullptr
• APIERR_BADDATABASE - the passed database reference is not valid

Remarks

This function is used to retrieve information about a database specified with databaseUnId.

Example

GS::Array<API_DatabaseUnId> dbases;
 
GSErrCode err = ACAPI_Database (APIDb_GetLayoutDatabasesID, nullptr, &dbases);
if (err == NoError) {
    for (const auto& dbUnId : dbases) {
        API_DatabaseInfo dbPars = {};
        dbPars.databaseUnId = dbUnId;
 
        err = ACAPI_Database (APIDb_GetDatabaseInfoID
, &dbPars, nullptr);
        if (err == NoError) {
            char msgStr[1024];
            sprintf (msgStr, "Layout database [%d] unId:(%d-%d) title:\"%s\" name:\"%s\" ref:\"%s\"",
                    dbPars.index, dbPars.databaseUnId.id1, dbPars.databaseUnId.id2, dbPars.title, dbPars.name, dbPars.ref);
            ACAPI_WriteReport (msgStr, false);
        }
    }
}

ACAPI_Window_GetOwnWindows()

GSErrCode ACAPI_Window_GetOwnWindows	(	API_WindowTypeID *	windowTypeID,
		GS::Array< API_Guid > *	guid = nullptr
	)

Returns the ids of the opened windows in an array.

Parameters

windowTypeID	[in] TypeID of the opened windows.
guid	[out] An array of guids of the opened windows.

Returns

• NoError - The function has completed with success.
• APIERR_NOPLAN - There is no open project. The operation cannot be executed without an open project.
• APIERR_BADPARS - Incorrect windowTypeID or guid was specified.

ACAPI_Window_NewWindow()

GSErrCode ACAPI_Window_NewWindow	(	API_NewWindowPars *	newWindowPars,
		APICustomWindowHandlerProc *	handlerProc = nullptr
	)

Opens a new window.

Parameters

newWindowPars	[in] parameters of the window to be created (type and reference index)
handlerProc	[in] Callback function to handle special (e.g. activate) events. Specify nullptr if you are not interested in these events.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - windowPars is nullptr.
• APIERR_REFUSEDCMD - the function is called from notification level.
• APIERR_REFUSEDPAR - not APIWind_MyTextID or APIWind_MyDrawID is requested.
• APIERR_WINDEXIST - a window with the same type and reference index already opened.
• APIERR_NOPLAN - no open project

Remarks

This function is used to open a new window. It is limited to opening simple text or drawing windows. The drawing window will have limited functionality and database beyond, compared to a normal 2D model window. It can have real 2D elements only (lines, arcs, etc.), construction elements like walls or beams cannot appear in this database. The database cannot be modified by the user, the input and edit functionality on these windows are disabled for the user. These type of windows are excellent to visualize the output of your algorithms, for example in case of listings. An add-on can open any number of drawing and text windows at the same time. Once an add-on opens such a window, it will be responsible for rebuilding its content when it is necessary. Archicad will post notifications for such an event. Upon receiving a notification Archicad will pass the windowPars->userRefCon parameter to the add-on to identify which window it should work on. Refer to the Notification Manager to get further details.

Example

API_NewWindowPars   windowPars;
GSErrCode           err;
 
BNZeroMemory (&windowPars, sizeof (API_NewWindowPars));
windowPars.typeID = APIWind_MyDrawID;  // create a drawing window
windowPars.userRefCon = 1;
GS::snuprintf (windowPars.wTitle, sizeof (windowPars.wTitle) / sizeof (GS::uchar_t), L("API window: %ld"), userRefCon);
 
err = ACAPI_Database (APIDb_NewWindowID, &windowPars, nullptr);

ACAPI_Window_ResetCurrentDatabase()

GSErrCode ACAPI_Window_ResetCurrentDatabase

(

)

Deletes the database elements of the current window and sets up a new, empty environment.

Returns

• NoError - The function has completed with success.
• APIERR_BADDATABASE - The current database is not a custom drawing or owned by an other addon,

Remarks

This function is used to delete all elements from the current database. It returns an error if the active database is not a custom window owned by the caller addon. To reset the content of the current (front) window use the ACAPI_Window_ResetCurrentWindow function.

ACAPI_Window_ResetCurrentWindow()

GSErrCode ACAPI_Window_ResetCurrentWindow

(

)

Deletes the database elements of the current window and sets up a new, empty environment.

Returns

• NoError - The function has completed with success.
• APIERR_BADWINDOW - The current database is not a custom drawing or owned by an other addon.

Remarks

This function is used to delete all elements from the current window. It returns an error if the active window is not a custom window owned by the caller addon. You can use the ACAPI_Window_ResetCurrentDatabase function to reset the content of any window being in the background.