Command Connection

Functions for invoking commands available on the Archicad JSON interface. More...

Functions
GSErrCode	ACAPI_Command_GetHttpConnectionPort (UShort *portNumber)
	Returns the HTTP port number, on which Archicad is expecting requests.
GSErrCode	ACAPI_Command_ExecuteJSONRequest (const GS::ObjectState &commandRequest, GS::ObjectState &commandResult)
	Executes an Archicad JSON interface command.

Detailed Description

Functions for invoking commands available on the Archicad JSON interface.

Function Documentation

ACAPI_Command_ExecuteJSONRequest()

GSErrCode ACAPI_Command_ExecuteJSONRequest	(	const GS::ObjectState &	commandRequest,
		GS::ObjectState &	commandResult )

Executes an Archicad JSON interface command.

Since

Archicad 29

Parameters

commandRequest	[in] the command request to be executed. Must contain the "command" field, and must comply with the command schema definition.
commandResult	[out] result of the executed command.

Returns

• NoError - The function has completed with success.
• APIERR_BADNAME - No executable command was found with name given by the "command" field.
• APIERR_BADPARS - The object state request does not match the corresponding scheme definition.
• APIERR_GENERAL - An error occurred during the execution. The detailed description of the error can be obtained from the "error" field of commandResult.

Remarks

You can use this function as a shortcut for invoking a command available on the Archicad JSON interface (see https://archicadapi.graphisoft.com/JSONInterfaceDocumentation), with skipping the HTTP communication layer. The requested command name and the command parameters are structured into the GS::ObjectState object. You may also use this function to call a command implemented by an add-on (see ACAPI_AddOnAddOnCommunication_InstallAddOnCommandHandler).

Example

void ACAPI_Command_ExecuteJSONRequest_Example ()
{
    GS::ObjectState commandRequest ("command", "API.GetProductInfo");
    GS::ObjectState commandResult;
    GSErrCode err = ACAPI_Command_ExecuteJSONRequest (commandRequest, commandResult);
    if (err == NoError) {
        const GS::ObjectState* result = commandResult.Get ("result");
        if (result != nullptr) {
            Int32 version, buildNumber;
            result->Get ("version", version);
            result->Get ("buildNumber", buildNumber);
            ACAPI_WriteReport ("API.GetProductInfo: \n- version: %d\n- build number: %d", true, version, buildNumber);
        }
    }
}

Also refer to the AddOnCommand_Test example project of the API Development Kit.

ACAPI_Command_GetHttpConnectionPort()

GSErrCode ACAPI_Command_GetHttpConnectionPort

(

UShort *

portNumber

)

Returns the HTTP port number, on which Archicad is expecting requests.

Parameters

portNumber

[out] HTTP port number.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - the portNumber parameter is nullptr.
• APIERR_GENERAL - there is an internal error and the HTTP server could not be started.

Remarks

This function is used to get the HTTP port on which the Add-On commands, registered via ACAPI_AddOnAddOnCommunication_InstallAddOnCommandHandler, can be accessed.