필수 함수

당신만의 애드온을 개발할 때, 당신은 해당 API 라이브러리를 당신의 object 파일에 링크시켜야 합니다. 이 라이브러리는 기본적으로 2개의 함수 집합을 가지고 있습니다.

• DLL/CFM-기반 공유 라이브러리의 메인 초기화 및 종료 지점을 소유하고 있습니다.
  ArchiCAD와 애드온 사이의 통신 채널을 설정합니다.
  
• ACAPinc.h 헤더 파일에 API 함수들이 나열되어 있습니다. 당신은 ArchiCAD 데이터베이스에서 작동하도록 이 함수들을 호출하십시오.

당신의 애드온을 라이브러리에 링크하기 위해 코드화되어야 하는 4개의 함수들이 있습니다.

• CheckEnvironment
• RegisterInterface
• Initialize
• FreeData

이러한 함수들의 프로토타입은 ACAPinc.h 헤더 파일에도 나열되어 있습니다.

대부분의 함수들은 (CheckEnvironment를 제외하고) type 정의 GSErrCode 기반의 오류 코드를 리턴합니다. 값 NoError는 오류가 발생하지 않았음을 의미합니다. 그러나 0이 아닌 값은 어떤 종류의 오류를 의미합니다.

위에 나열된 4개의 함수들이 서버 애플리케이션에 의해 호출되는 방식을 이해하는 것은 매우 중요합니다.

애드온은 기본적으로 메모리에 로드되지 않는 DLL 또는 CFM-기반 공유 라이브러리입니다. 사용자가 애드온의 명령들 중 하나를 호출할 때 ArchiCAD가 커맨드를 실행되도록 그것을 메모리에 로드됩니다. 애드온이 동작을 완료하면 (특정 조건들이 충족되지 않는 한) ArchiCAD는 애드온을 다시 언로드합니다.

CheckEnvironment 함수

Add-On Manager가 애드온들을 열거할 때 CheckEnvironment 함수가 호출됩니다. 애드온은 실행 환경을 체크하고 자신의 행동을 정의할 수 있습니다. 예를 들어 데모 버전에서는 작동하지 않도록 할 수 있습니다. 애드온은 이 단계에서 로드되거나 언로드됩니다. 그러나 Initialize와 FreeData 함수들은 호출되지 않습니다.

참고: 다음 2개 지점들은 서버 애플리케이션의 시작 시간에 심각한 영향을 끼칠 수 있습니다.

• 이 단계에서 당신의 모든 global 및 (비-함수) static 변수들은 초기화됩니다.
• 만약 당신이 원하는 서버 애플리케이션에서 실행하지 않는다면 해당 오류 코드가 리턴됩니다. (APIAddon_DontRegister) 이것은 AddOnManager에게 당신의 애드온을 다음 단계들로 스킵하도록 알려줍니다.

RegisterInterface 함수

열거 및 의존성 체크 뒤에 RegisterInterface 함수가 호출됩니다. 이와 같이, 1번째 단계만 통과하는 애드온만 호출됩니다. 애드온은 여기에서 메뉴 항목들과 파일 유형들을 등록하거나 툴박스 항목들을 추가해야 합니다. 이 단계에서 애드온은 로드되고 언로드됩니다. 그러나 Initialize와 FreeData 함수들은 호출되지 않습니다.

참고: 이 단계에서 당신의 모든 global 및 (비-함수) static 변수들은 초기화됩니다.

Initialize 함수

이전 단계 이후에 애드온이 메모리에 로드되면 Initialize 함수가 바로 호출됩니다. 이 함수는 애드온 스스로 초기화하고 서버 애플리케이션에 의해 호출될 콜백 함수들을 설치하는 지점입니다.

FreeData 함수

애드온이 언로드 되기 전에 FreeData 함수가 호출됩니다. 이 함수는 Initialize 함수에서 할당된 객체들을 폐기해야 하는 지점입니다. Initialize 또는 어떤 콜백 함수들이라도 성공하든 실패하든 간에 상관없이 FreeData 함수는 모든 경우에서 호출됩니다.

당신의 global 변수들의 상태를 항상 주시하고 계십시오. 그렇게 하셔야 나중에 폐기할 때 문제가 발생하지 않을 것입니다. 기본 초기화 및 할당은 Initialize 함수에서 이루어져야 합니다. 그리고 반대 작업은 FreeData 함수에서 이루어져야 합니다.

이 함수들에 대한 자세한 사항은 로드/언로드 메커니즘 제어하기 문서를 참조하시기 바랍니다.

 

애드온의 스켈레톤

당신이 구현해야 하는 최소 소스 코드는 다음과 같습니다:

#define ACExtension
#include "ACAPinc.h"

API_AddonType __ACDLL_CALL CheckEnvironment (API_EnvirParams *envirParams)
{
    ACAPI_Resource_GetLocStr (envirParams->addOnInfo.name, 32500, 1);
    ACAPI_Resource_GetLocStr (envirParams->addOnInfo.description, 32500, 2);

    return APIAddon_Normal;
}

GSErrCode __ACDLL_CALL RegisterInterface (void)
{
    return NoError;
}

GSErrCode __ACDLL_CALL Initialize (void)
{
    return NoError;
}

GSErrCode __ACDLL_CALL FreeData (void)
{
    return NoError;
}

이 스켈레톤은 컴파일, 링크, 실행될 수 있습니다만 아무 것도 수행하지 않습니다.