Classification Manager

Functions related to accessing and manipulating Classification and the category-related data of elements. More...

Classes
struct	API_ClassificationItem
	Specifies a classification item. More...
struct	API_ClassificationSystem
	Specifies a classification system. More...

Enumerations
enum	API_ClassificationSystemNameConflictResolutionPolicy { API_MergeConflictingSystems , API_ReplaceConflictingSystems , API_SkipConflictingSystems }
	Enum used by ACAPI_Classification_Import. More...
enum	API_ClassificationItemNameConflictResolutionPolicy { API_ReplaceConflictingItems , API_SkipConflicitingItems }
	Enum used by ACAPI_Classification_Import. More...

Functions
GSErrCode	ACAPI_Element_GetClassificationItems (const API_Guid &elemGuid, GS::Array< GS::Pair< API_Guid, API_Guid > > &systemItemPairs)
	Retrieves all of the classifications of an element.
GSErrCode	ACAPI_Element_GetClassificationItemsDefault (const API_ElemType &type, GS::Array< GS::Pair< API_Guid, API_Guid > > &systemItemPairs)
	Retrieves all of the classifications of a default elem.
GSErrCode	ACAPI_Element_GetClassificationInSystem (const API_Guid &elemGuid, const API_Guid &systemGuid, API_ClassificationItem &item)
	Retrieves a classification of an elem in a given classification system.
GSErrCode	ACAPI_Element_GetClassificationInSystemDefault (const API_ElemType &type, const API_Guid &systemGuid, API_ClassificationItem &item)
	Retrieves a classification of a default elem in a given classification system.
GSErrCode	ACAPI_Element_RemoveClassificationItem (const API_Guid &elemGuid, const API_Guid &itemGuid)
	Removes a classification from an element.
GSErrCode	ACAPI_Element_RemoveClassificationItemDefault (const API_ElemType &type, const API_Guid &itemGuid)
	Removes a classification from an element.
bool	ACAPI_Element_IsClassificationItemVisible (const API_Guid &elemGuid, const API_Guid &classificationGuid)
	Tells whether a classification item is visible for an element.
bool	ACAPI_Element_IsClassificationItemVisibleDefault (const API_ElemType &type, const API_Guid &classificationGuid)
	Tells whether a classification item is visible for an element default.
GSErrCode	ACAPI_Notification_ClassificationVisibilityChanged ()
	Sends out an APINotify_ClassificationVisibilityChanged project event notification to the other add-ons to state that at least one classification's visibility has changed.
GSErrCode	ACAPI_Classification_GetClassificationSystems (GS::Array< API_ClassificationSystem > &systems)
	Retrieves all of the classification systems in the plan.
GSErrCode	ACAPI_Classification_GetClassificationItem (API_ClassificationItem &item)
	Retrieves a classification item identified by its guid.
GSErrCode	ACAPI_Classification_GetClassificationItemParent (const API_Guid &itemGuid, API_ClassificationItem &parent)
	Retrieves the parent of a classification item.
GSErrCode	ACAPI_Classification_GetClassificationItemChildren (const API_Guid &itemGuid, GS::Array< API_ClassificationItem > &children)
	Retrieves the children of a classification item.
GSErrCode	ACAPI_Classification_GetClassificationItemSystem (const API_Guid &itemGuid, API_ClassificationSystem &system)
	Retrieves the system of a classification item.
GSErrCode	ACAPI_Classification_GetClassificationSystem (API_ClassificationSystem &system)
	Retrieves a classification system identified by its guid or by its name and edition version.
GSErrCode	ACAPI_Classification_GetClassificationSystemRootItems (const API_Guid &systemGuid, GS::Array< API_ClassificationItem > &items)
	Retrieves the root items of a classification system.
GSErrCode	ACAPI_Classification_CreateClassificationItem (API_ClassificationItem &item, const API_Guid &systemGuid, const API_Guid &parentItemGuid, const API_Guid &nextItemGuid)
	Creates a classification item.
GSErrCode	ACAPI_Classification_CreateClassificationSystem (API_ClassificationSystem &system)
	Creates a classification system.
GSErrCode	ACAPI_Classification_ChangeClassificationItem (const API_ClassificationItem &item)
	Modifies a classification item.
GSErrCode	ACAPI_Classification_ChangeClassificationSystem (const API_ClassificationSystem &system)
	Modifies a classification system.
GSErrCode	ACAPI_Classification_DeleteClassificationItem (const API_Guid &itemGuid)
	Deletes a classification item.
GSErrCode	ACAPI_Classification_DeleteClassificationSystem (const API_Guid &systemGuid)
	Deletes a classification system.
GSErrCode	ACAPI_Classification_Import (const GS::UniString &classificationXml, API_ClassificationSystemNameConflictResolutionPolicy systemConflictPolicy, API_ClassificationItemNameConflictResolutionPolicy itemConflictPolicy)
	Imports a classification xml.

Detailed Description

Functions related to accessing and manipulating Classification and the category-related data of elements.

Enumeration Type Documentation

API_ClassificationItemNameConflictResolutionPolicy

enum API_ClassificationItemNameConflictResolutionPolicy

Enum used by ACAPI_Classification_Import.

Since

Archicad 20

API_ClassificationSystemNameConflictResolutionPolicy

enum API_ClassificationSystemNameConflictResolutionPolicy

Enum used by ACAPI_Classification_Import.

Since

Archicad 20

Function Documentation

ACAPI_Classification_ChangeClassificationItem()

GSErrCode ACAPI_Classification_ChangeClassificationItem

(

const API_ClassificationItem &

item

)

Modifies a classification item.

Parameters

item	[in] The details of the classification item.

Returns

• NoError - The function has completed with success.
• APIERR_NOACCESSRIGHT - Don't have the right to modify a classification item in this plan.
• APIERR_BADID - The item.guid does not refer to a valid classification item.
• APIERR_READONLY - The referenced classification item can not be modified (i.e. comes from a hotlink).
• APIERR_BADNAME - The item.id is not a valid identifier for a classification item (i.e. empty string).
• APIERR_NAMEALREADYUSED - The item.id is different than the current id of the referenced item and the new id is already used as a classification item id in the item's system.

ACAPI_Classification_ChangeClassificationSystem()

GSErrCode ACAPI_Classification_ChangeClassificationSystem

(

const API_ClassificationSystem &

system

)

Modifies a classification system.

Parameters

system

[in] The details of the classification system.

Returns

• NoError - The function has completed with success.
• APIERR_NOACCESSRIGHT - Don't have the right to modify a classification system in this plan.
• APIERR_BADID - The guid of the system parameter does not refer to a valid classification system.
• APIERR_READONLY - The referenced classification system can not be modified (i.e. comes from a hotlink).
• APIERR_BADNAME - The name field of the system is not a valid name for a classification system (i.e. empty string).
• APIERR_NAMEALREADYUSED - The name field of the system is different than the current name of the referenced classification system, but the new name is already used as a classification name in the current plan.
• APIERR_BADPARS - The editionDate field of the system is not a valid date.

ACAPI_Classification_CreateClassificationItem()

GSErrCode ACAPI_Classification_CreateClassificationItem	(	API_ClassificationItem &	item,
		const API_Guid &	systemGuid,
		const API_Guid &	parentItemGuid,
		const API_Guid &	nextItemGuid )

Creates a classification item.

Parameters

item	[in/out] The details of the classification item to create. Once the operation is completed successfully this will hold the guid of the created classification item.
systemGuid	[in] The guid of the classification system in which the item should be created.
parentItemGuid	[in] The guid of the item that should be the parent of the newly created item (or null guid, if it should be a root item).
nextItemGuid	[in] The guid of the item that should next in order to the created item (or null guid, if it created item should be the last).

Returns

• NoError - The function has completed with success.
• APIERR_NOACCESSRIGHT - Don't have the right to create a classification item in this plan.
• APIERR_BADID - One of the parameter guids did not refer to a valid object.
• APIERR_BADPARS - The given parent item is in a different system or the given next item is not on the same level as the item to be created.
• APIERR_BADNAME - The id field of the item is not a valid identifier for a classification item (i.e. empty string).
• APIERR_NAMEALREADYUSED - The id field of the item is already used as a classification item id within the given system.

ACAPI_Classification_CreateClassificationSystem()

GSErrCode ACAPI_Classification_CreateClassificationSystem

(

API_ClassificationSystem &

system

)

Creates a classification system.

Parameters

system

[in/out] The details of the classification system to create. Once the operation is completed successfully this will hold the guid of the created classification system.

Returns

• NoError - The function has completed with success.
• APIERR_NOACCESSRIGHT - Don't have the right to create a classification system in this plan.
• APIERR_BADNAME - The name field of the system is not a valid name for a classification system (i.e. empty string).
• APIERR_NAMEALREADYUSED - The name field of the system is already used as a classification system name in the current plan with the same edition version.
• APIERR_BADPARS - The editionDate field of the system is not a valid date.

ACAPI_Classification_DeleteClassificationItem()

GSErrCode ACAPI_Classification_DeleteClassificationItem

(

const API_Guid &

itemGuid

)

Deletes a classification item.

Parameters

itemGuid

[in] The identifier of classification item to delete.

Returns

• NoError - The function has completed with success.
• APIERR_NOACCESSRIGHT - Don't have the right to delete a classification item in this plan.
• APIERR_BADID - The guid of the item parameter does not refer to a valid classification.
• APIERR_READONLY - The referenced classification item can not be deleted (i.e. comes from a hotlink).

ACAPI_Classification_DeleteClassificationSystem()

GSErrCode ACAPI_Classification_DeleteClassificationSystem

(

const API_Guid &

systemGuid

)

Deletes a classification system.

Parameters

systemGuid

[in] The identifier of classification system to delete.

Returns

• NoError - The function has completed with success.
• APIERR_NOACCESSRIGHT - Don't have the right to delete a classification system in this plan.
• APIERR_BADID - The systemGuid parameter does not refer to a valid classification system.
• APIERR_READONLY - The referenced classification system can not be deleted (i.e. comes from a hotlink).

ACAPI_Classification_GetClassificationItem()

GSErrCode ACAPI_Classification_GetClassificationItem

(

API_ClassificationItem &

item

)

Retrieves a classification item identified by its guid.

Parameters

item	[in/out] The item.guid is the identifier of the classification item to retrieve. Once the operation is completed successfully this will hold the retrieved classification item.

Returns

• NoError - The function has completed with success.
• APIERR_BADID - The item.guid did not refer to a valid classification item.

ACAPI_Classification_GetClassificationItemChildren()

GSErrCode ACAPI_Classification_GetClassificationItemChildren	(	const API_Guid &	itemGuid,
		GS::Array< API_ClassificationItem > &	children )

Retrieves the children of a classification item.

Parameters

itemGuid	[in] The guid of the item whose children should be retrieved.
children	[out] The retrieved children classification items.

Returns

• NoError - The function has completed with success.
• APIERR_BADID - The itemGuid did not refer to a valid classification item.

ACAPI_Classification_GetClassificationItemParent()

GSErrCode ACAPI_Classification_GetClassificationItemParent	(	const API_Guid &	itemGuid,
		API_ClassificationItem &	parent )

Retrieves the parent of a classification item.

Parameters

itemGuid	[in] The guid of the item whose parent should be retrieved.
parent	[out] The retrieved parent classification item. Will be an empty classification item, with null guid, if the specified item doesn't have a parent.

Returns

• NoError - The function has completed with success.
• APIERR_BADID - The itemGuid did not refer to a valid classification item.

ACAPI_Classification_GetClassificationItemSystem()

GSErrCode ACAPI_Classification_GetClassificationItemSystem	(	const API_Guid &	itemGuid,
		API_ClassificationSystem &	system )

Retrieves the system of a classification item.

Parameters

itemGuid	[in] The guid of the item whose system should be retrieved.
system	[out] The retrieved classification system.

Returns

• NoError - The function has completed with success.
• APIERR_BADID - The itemGuid did not refer to a valid classification item.

ACAPI_Classification_GetClassificationSystem()

GSErrCode ACAPI_Classification_GetClassificationSystem

(

API_ClassificationSystem &

system

)

Retrieves a classification system identified by its guid or by its name and edition version.

Parameters

system

[in] The system.guid or the system.name and system.editionVersion together that identify the classification system to retrieve. [out] The retrieved classification system.

Returns

• NoError - The function has completed with success.
• APIERR_BADID - The system.guid is not null and did not refer to a valid classification system or the system.name and system.editionVersion together did not refer to a valid classification system.

ACAPI_Classification_GetClassificationSystemRootItems()

GSErrCode ACAPI_Classification_GetClassificationSystemRootItems	(	const API_Guid &	systemGuid,
		GS::Array< API_ClassificationItem > &	items )

Retrieves the root items of a classification system.

Parameters

systemGuid	[in] The guid of the classification system whose root items should be retrieved.
items	[out] The retrieved root classification items of the referenced system.

Returns

• NoError - The function has completed with success.
• APIERR_BADID - The systemGuid did not refer to a valid classification system.

ACAPI_Classification_GetClassificationSystems()

GSErrCode ACAPI_Classification_GetClassificationSystems

(

GS::Array< API_ClassificationSystem > &

systems

)

Retrieves all of the classification systems in the plan.

Parameters

systems

[out] The retrieved classification systems.

Returns

• NoError - The function has completed with success.

ACAPI_Classification_Import()

GSErrCode ACAPI_Classification_Import	(	const GS::UniString &	classificationXml,
		API_ClassificationSystemNameConflictResolutionPolicy	systemConflictPolicy,
		API_ClassificationItemNameConflictResolutionPolicy	itemConflictPolicy )

Imports a classification xml.

Parameters

classificationXml	[in] The classification xml to import.
systemConflictPolicy	[in] Specifies how to resolve classification system conflicts. API_ClassificationSystemNameConflictResolutionPolicy Meaning API_MergeConflictingSystems Merge the conflicting systems API_ReplaceConflictingSystems Replace the system in the plan with the imported one API_SkipConflictingSystems Keep the system in the plan intact, and discard the imported one
itemConflictPolicy	[in] Specifies how to resolve classification item conflicts. API_ClassificationItemNameConflictResolutionPolicy Meaning API_ReplaceConflictingItems Replace the item in the plan with the imported one API_SkipConflicitingItems Keep the item in the plan intact, and discard the imported one

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - Invalid classification XML.

ACAPI_Element_GetClassificationInSystem()

GSErrCode ACAPI_Element_GetClassificationInSystem	(	const API_Guid &	elemGuid,
		const API_Guid &	systemGuid,
		API_ClassificationItem &	item )

Retrieves a classification of an elem in a given classification system.

Parameters

elemGuid	[in] The guid of the element.
systemGuid	[in] The guid of the classification system in which the classification item should be retrieved.
item	[out] The retrieved classification item (empty with null guid if the elem doesn't have a classification in the given system).

Returns

• NoError - The function has completed with success.
• APIERR_BADID - The elemGuid did not refer to a valid element or systemGuid did not refer to a valid classification system.

ACAPI_Element_GetClassificationInSystemDefault()

GSErrCode ACAPI_Element_GetClassificationInSystemDefault	(	const API_ElemType &	type,
		const API_Guid &	systemGuid,
		API_ClassificationItem &	item )

Retrieves a classification of a default elem in a given classification system.

Since

Archicad 26

Parameters

type	[in] Type of the default element.
systemGuid	[in] The guid of the classification system in which the classification item should be retrieved.
item	[out] The retrieved classification item (empty with null guid if the elem doesn't have a classification in the given system).

Returns

• NoError - The function has completed with success.
• APIERR_BADID - The type did not refer to a valid default element or systemGuid did not refer to a valid classification system.

Remarks

From version 26 the typeID and variationID parameters were merged into a single API_ElemType parameter.

ACAPI_Element_GetClassificationItems()

GSErrCode ACAPI_Element_GetClassificationItems	(	const API_Guid &	elemGuid,
		GS::Array< GS::Pair< API_Guid, API_Guid > > &	systemItemPairs )

Retrieves all of the classifications of an element.

Parameters

elemGuid	[in] The guid of the element.
systemItemPairs	[out] A list of classification system and classification item guid pairs, that represent the element's classifications.

Returns

• NoError - The function has completed with success.
• APIERR_BADID - The elemGuid did not refer to a valid element.

ACAPI_Element_GetClassificationItemsDefault()

GSErrCode ACAPI_Element_GetClassificationItemsDefault	(	const API_ElemType &	type,
		GS::Array< GS::Pair< API_Guid, API_Guid > > &	systemItemPairs )

Retrieves all of the classifications of a default elem.

Since

Archicad 26

Parameters

type	[in] Type of the default element.
systemItemPairs	[out] A list of classification system and classification item guid pairs, that represent the element's classifications.

Returns

• NoError - The function has completed with success.
• APIERR_BADID - The type did not refer to a valid default element.

Remarks

From version 26 the typeID and variationID parameters were merged into a single API_ElemType parameter.

ACAPI_Element_IsClassificationItemVisible()

bool ACAPI_Element_IsClassificationItemVisible	(	const API_Guid &	elemGuid,
		const API_Guid &	classificationGuid )

Tells whether a classification item is visible for an element.

Parameters

elemGuid	[in] The element GUID to search for.
classificationGuid	[in] The classification item GUID to search for.

Returns

• true - The given classification item is visible for the element. It can return true even if the parent of the classification item is hidden.
• false - The given classification item is not visible for the element or invalid parameters.

Example

GSErrCode GetVisibleClassificationItems (const API_Guid& elemGuid, GS::Array<GS::Pair<API_Guid, API_Guid>>& visibleClassifications)
{
    GS::Array<GS::Pair<API_Guid, API_Guid>> systemItemPairs;
    GSErrCode error = ACAPI_Element_GetClassificationItems (APINULLGuid, systemItemPairs);
    if (error == NoError) {
        for (UInt32 i = 0; i < systemItemPairs.GetSize (); ++i) {
            if (ACAPI_Element_IsClassificationItemVisible (elemGuid, systemItemPairs[i].second)) {
                visibleClassifications.Push (systemItemPairs[i]);
            }
        }
    }
    return error;
}

ACAPI_Element_IsClassificationItemVisibleDefault()

bool ACAPI_Element_IsClassificationItemVisibleDefault	(	const API_ElemType &	type,
		const API_Guid &	classificationGuid )

Tells whether a classification item is visible for an element default.

Since

Archicad 26

Parameters

type	[in] Type of the default element.
classificationGuid	[in] The classification item GUID to search for.

Returns

• true - The given classification item is visible for the element default. It can return true even if the parent of the classification item is hidden.
• false - The given classification item is not visible for the element default or invalid parameters.

Remarks

From version 26 the typeID and variationID parameters were merged into a single API_ElemType parameter.

Example

GSErrCode GetVisibleClassificationItems (const API_ElemType& type, GS::Array<GS::Pair<API_Guid, API_Guid>>& visibleClassifications)
{
    GS::Array<GS::Pair<API_Guid, API_Guid>> systemItemPairs;
    GSErrCode error = ACAPI_Element_GetClassificationItems (APINULLGuid, systemItemPairs);
    if (error == NoError) {
        for (UInt32 i = 0; i < systemItemPairs.GetSize (); ++i) {
            if (ACAPI_Element_IsClassificationItemVisibleDefault (type, systemItemPairs[i].second)) {
                visibleClassifications.Push (systemItemPairs[i]);
            }
        }
    }
    return error;
}

ACAPI_Element_RemoveClassificationItem()

GSErrCode ACAPI_Element_RemoveClassificationItem	(	const API_Guid &	elemGuid,
		const API_Guid &	itemGuid )

Removes a classification from an element.

Parameters

elemGuid	[in] The identifier of the element whose classification should be removed.
itemGuid	[in] The guid of the classification item, that should be removed from the element.

Returns

• NoError - The function has completed with success.
• APIERR_BADID - The elemGuid did not refer to a valid element or itemGuid did not refer to a valid classification item.
• APIERR_BADPARS - The element did not have the specified classification.
• APIERR_READONLY - The element can not be modified (i.e. from a hotlink) or you do not have the right to remove classifications from elements in the current teamwork plan.

ACAPI_Element_RemoveClassificationItemDefault()

GSErrCode ACAPI_Element_RemoveClassificationItemDefault	(	const API_ElemType &	type,
		const API_Guid &	itemGuid )

Removes a classification from an element.

Since

Archicad 26

Parameters

type	[in] Type of the default element.
itemGuid	[in] The guid of the classification item, that should be removed from the element.

Returns

• NoError - The function has completed with success.
• APIERR_BADID - The type did not refer to a valid default element or itemGuid did not refer to a valid classification item.
• APIERR_BADPARS - The element did not have the specified classification.
• APIERR_READONLY - The element can not be modified (i.e. from a hotlink) or you do not have the right to remove classifications from elements in the current teamwork plan.

Remarks

From version 26 the typeID and variationID parameters were merged into a single API_ElemType parameter.

ACAPI_Notification_ClassificationVisibilityChanged()

GSErrCode ACAPI_Notification_ClassificationVisibilityChanged

(

)

Sends out an APINotify_ClassificationVisibilityChanged project event notification to the other add-ons to state that at least one classification's visibility has changed.

Returns

• NoError - The function completed successfully.