ACAPI_​Command_​Call

Call a command of an other add-on.

    GSErrCode  ACAPI_Command_Call (
        const API_ModulID*     mdid,
        GSType                 cmdID,
        Int32                  cmdVersion,
        GSHandle               params,
        GSPtr                  resultData,
        bool                   silentMode
    );

 

Parameters

mdid
[in] the identifier of the target add-on. It is defined by the ‘MDID’ resource.
cmdID
[in] the identifier of the command to be executed.
cmdVersion
[in] the required command version
params
[in/out] passed parameters (optional). See the Inter-add-on communication section of the ACAPI_Goodies functions
resultData
[out] results returned by the command (optional)
silentMode
[in] instruct the target add-on to work in silent mode. No option dialogs, error alerts …etc.

 

Return Values

NoError
the function completed successfully
APIERR_BADPARS
the mdid parameter is nullptr
APIERR_MODULNOTINSTALLED
the referenced add-on is not installed
APIERR_MODULCMDNOTSUPPORTED
the referenced command is not supported by the target add-on
APIERR_MODULCMDVERSNOTSUPPORTED
the requested command version is too new; not supported by the target add-on

For other common errors see the list of error codes.

 

Remarks

This function is used to call a command implemented in an other add-on.

Refer to the ACAPI_Command_Test function to test the command availability.

Refer to the Communication Manager for more detailed description on

  • how to pass parameters,
  • how to get return values,
  • how the heaps and API environments are managed by the API.

Featuring API 10  From Archicad 10 you can execute add-on command with ACAPI_Command_ExternalCall on a different plan loaded into another instance of Archicad.

Featuring API 19  From Archicad 19 you can execute add-on command forced from main event loop with ACAPI_Command_CallFromEventLoop function.

 

Example

The following sample retrieves the location of the default translator currently set for the DXF/DWG add-on (provided that the add-on is currently loaded):


IO::Location configFile;                        // translator location to be returned
API_ModulID mdid = { 1198731108, 1322668197 };  // MDID of the DXF/DWG add-on
GSHandle parHdl = nullptr;                         // handle of command call parameters

GSErrCode err = ACAPI_Goodies (APIAny_InitMDCLParameterListID, &parHdl, nullptr);
if (err == NoError) {
    API_MDCLParameter par;                      // parameter describing the output file
    BNZeroMemory (&par, sizeof (API_MDCLParameter));
    par.name = "Mode";
    par.type = MDCLPar_string;
    par.string_par = "Default";

    err = ACAPI_Goodies (APIAny_AddMDCLParameterID, parHdl, &par);
    if (err == NoError) {
        err = ACAPI_Command_Call (&mdid, 'GDCO', 1, parHdl, nullptr, true);
        if (err == NoError) {
            Int32 nPars = 0;
            err = ACAPI_Goodies (APIAny_GetMDCLParameterNumID, parHdl, &nPars);
            if (err == NoError && nPars == 1) {
                BNZeroMemory (&par, sizeof (par));
                par.index = 1;
                err = ACAPI_Goodies (APIAny_GetMDCLParameterID, parHdl, &par);
                if (err == NoError && par.type == MDCLPar_string && par.string_par[0] != 0) {
                    configFile.Set (par.string_par);
                }
            }
        }
    }
    ACAPI_Goodies (APIAny_FreeMDCLParameterListID, &parHdl, nullptr);
}

 

Requirements

Version: API 3.1 or later
Header: ACAPinc.h

 

See Also

API_ModulID, ‘MDID’
APIModulCommandProc
ACAPI_Command_Test
ACAPI_Command_ExternalCall
ACAPI_Command_CallFromEventLoop
Communication Manager
API Functions