ACAPI_Command_ExternalCall

또 다른 ArchiCAD 인스턴스에서 다른 애드온의 커맨드를 호출합니다.

    GSErrCode  ACAPI_Command_ExternalCall (
        const IO::Location*          projectFileLoc,
        const API_ModulID*           mdid,
        GSType                       cmdID,
        Int32                        cmdVersion,
        GSHandle                     params,
        bool                         silentMode,
        APIExternalCallBackProc*     externalCallbackProc
    );

파라미터

projectFileLoc: [in] 원격 호출을 하는 동안 열려 있는 프로젝트 파일의 위치입니다.
mdid: [in] 대상 애드온의 식별자입니다. 'MDID' 리소스로 정의합니다.
cmdID: [in] 실행할 커맨드의 식별자입니다.
cmdVersion: [in] 필수 커맨드 버전입니다.
params: [in/out] 전달된 파라미터들입니다. (선택사항) ACAPI_Goodies 함수들의 애드온 간 통신 섹션을 보십시오.
silentMode: [in] 대상 애드온에게 사일런트 모드로 작동하도록 지시합니다. 옵션 다이얼로그, 오류 경고 등이 나타나지 않습니다.
externalCallbackProc: [in] 응답을 비동기적으로 처리하기 위한 선택적인 콜백 프로시저입니다.

리턴 값

NoError: 함수가 성공적으로 완료되었습니다.
APIERR_BADPARS: mdid 또는 projectFileLoc 파라미터가 NULL입니다.
APIERR_REFUSEDPAR: projectFileLoc에 의해 정의된 위치가 비어 있거나 유효하지 않습니다.
APIERR_MODULNOTINSTALLED: 참조된 애드온이 설치되어 있지 않습니다.
APIERR_MODULCMDNOTSUPPORTED: 참조된 커맨드가 대상 애드온에 의해 지원되지 않습니다.
APIERR_MODULCMDVERSNOTSUPPORTED: 요청한 커맨드 버전이 너무 새로운 것입니다; 대상 애드온이 지원하지 않습니다.
APIERR_CANCEL: 외부 동작이 취소되었습니다. (사용자에 의해, 혹은 통신 문제로 인해)

다른 공통 오류들에 대해서는 오류 코드들의 리스트를 보십시오.

설명

이 함수는 ArchiCAD의 또 다른 인스턴스에 로드된 다른 도면에서 애드온에 구현된 커맨드를 호출하는 데 사용합니다.

시스템은 요청된 프로젝트가 다음 방식으로 커맨드를 수행할 수 있다고 규정합니다:

만약 ArchiCAD 애플리케이션이 지정된 도면을 이미 연 채로 실행 중이라면, 외부 호출에 대하여 그것을 예약하도록 시도합니다. (만약 현재 다른 동작으로 인해 바쁘다면, 애플리케이션을 이용할 수 있을 때까지 대기함)
만약 ArchiCAD가 현재 열려 있는 도면이 없이 실행 중이라면 (비어 있음), 애플리케이션을 예약하고 프로젝트 파일을 로드하게 만듭니다.
만약 실행 중인 ArchiCAD가 없다면, 요청한 프로젝트 파일을 로드하도록 새로운 애플리케이션 인스턴스를 실행합니다.

외부 ArchiCAD 인스턴스가 애드온 커맨드 호출을 실행하도록 예약된 후에는, ACAPI_Command_Call 함수와 비슷하게 작동합니다. 서버 측에서 피호출자 애드온은 커맨드 요청이 또 다른 애플리케이션 인스턴스로부터 왔는지 깨닫지 못합니다. 유일한 차이점은 APIModulCommandProc 핸들러를 호출할 때 resultData 파라미터가 항상 NULL이라는 것입니다. 왜냐하면 이 포인터는 ArchiCAD 간에 전달될 수 없기 때문입니다. 그러나 당신은 결과를 호출자에게 전달하기 위해 파라미터들을 변경하는 params 핸들의 내용을 변경할 수 있습니다.

호출자는 명령 요청(비동기 동작)을 보낸 후 즉시 리턴하거나, 외부 호출이 완료될 때까지 기다리는(동기 동작) 함수를 결정할 수 있습니다. 응답을 비동기로 수집하려면 APIExternalCallBackProc 핸들러 함수를 전달해야 합니다; 만약 이 파라미터가 NULL이면, 함수는 외부 동작이 완료될 때까지 리턴하지 않습니다. 비동기 방식의 장점은 서로 다른 프로젝트 파일들이 있어도 더 많은 호출들을 동시에 시작할 수 있으며 내부 작업 스케줄러가 실행 순서를 최적화하게 된다는 것입니다.

만약 당신이 비동기 응답에 대하여 대기하는 루프를 사용한다면, 불필요한 프로세서 시간을 예약하지 않는 것을 참고 바랍니다. GSRoot 모듈의 TIWait 함수를 호출하여 다른 스레드들이 실행되도록 하십시오.

더 자세한 설명은 통신 관리자를 참조하십시오.

파라미터들을 전달하는 방법,
리턴 값들을 가져오는 방법,
API로 힙(heap)과 API 환경을 관리하는 방법.

예제

다음 샘플은 외부 ArchiCAD에서 표준 DXF/DWG 애드온을 동기식으로 호출하여 예제 프로젝트의 요소들을 지정한 DWG 파일로 내보냅니다:

API_ModulID mdid = { 1198731108, 1322668197 };  // DXF/DWG 애드온의 MDID

IO::Location projectFileLoc;
API_SpecFolderID specFolderID = API_ApplicationFolderID;
ACAPI_Environment (APIEnv_GetSpecFolderID, &specFolderID, &projectFileLoc);
projectFileLoc.AppendToLocal ("ArchiCAD Examples");
projectFileLoc.AppendToLocal ("Residential House");
projectFileLoc.AppendToLocal ("Residential House.pla");

IO::Location outputLoc;
specFolderID = API_UserDocumentsFolderID;
ACAPI_Environment (APIEnv_GetSpecFolderID, &specFolderID, &outputLoc);
outputLoc.AppendToLocal ("Residential House.DWG");

IO::Location configFile;                        // 이 출력에 대하여 적용된 번역기
specFolderID = API_DefaultsFolderID;
ACAPI_Environment (APIEnv_GetSpecFolderID, &specFolderID, &configFile);
configFile.AppendToLocal ("DXF-DWG Translators");
configFile.AppendToLocal ("For as is output.Xml");

GSHandle parHdl = NULL;                         // 커맨드 호출 파라미터들의 핸들

GSErrCode err = ACAPI_Goodies (APIAny_InitMDCLParameterListID, &parHdl, NULL);
if (err == NoError) {
    API_MDCLParameter par;                      // 출력 파일을 설명하는 파라미터
    char str[512];
    IO::URL url;

    BNZeroMemory (&par, sizeof (API_MDCLParameter));
    par.name = "FileName";
    par.type = MDCLPar_string;
    outputLoc.ToURL (&url);
    CHTruncate ((const char*) url, str, sizeof (str));
    par.string_par = str;
    err = ACAPI_Goodies (APIAny_AddMDCLParameterID, parHdl, &par);

    if (err == NoError) {
        BNZeroMemory (&par, sizeof (API_MDCLParameter));
        par.name = "ConfigFile";
        par.type = MDCLPar_string;
        configFile.ToURL (&url);
        CHTruncate ((const char*) url, str, sizeof (str));
        par.string_par = str;
        err = ACAPI_Goodies (APIAny_AddMDCLParameterID, parHdl, &par);
    }

    if (err == NoError) {
        err = ACAPI_Command_ExternalCall (&projectFileLoc, &mdid, 'SAV2', 1, parHdl, true, NULL);
        if (err != NoError) {
            DBPrintf ("DXF/DWG export %s\n", (err == APIERR_CANCEL) ? "canceled" : "failed");
        }
    }

    ACAPI_Goodies (APIAny_FreeMDCLParameterListID, &parHdl, NULL);
}

비동기 외부 모듈 호출 샘플에 대해서는 통신 관리자 예제 애드온을 확인해 보시기 바랍니다.

요구사항

버전: API 10 또는 이후

헤더: ACAPinc.h

참고사항

API_ModulID, 'MDID'
APIExternalCallBackProc
APIModulCommandProc
ACAPI_Command_Call
ACAPI_Command_Test
통신 관리자
API 함수