차례

  1. 시작하기 전에
  2. 개요
  3. PLUGIN/1.0
    1. descript.txt
    2. DLL 형식
    3. NOTIFY 이벤트 일람
      1. OnSecondChange
      2. OnGhostChange
      3. OnShellChange
      4. OnVisibleChange
      5. OnBoot

시작하기 전에

이 플러그인이라는 것은 일단 스펙에는 있지만 실제 Materia 583 에서는 동작하지 않는 것 같습니다. 왜 이렇게 단정하냐면 예전에 "나니카 문자열 변환기 - String Patcher for Nanika -" 라는 것을 만들 때 처음에는 이 플러그인 형식으로 만들려고 했으나 도대체 Materia 본체에서 읽어들이지를 않으니 작동을 하지 않는 것이었습니다. 그럼 왜 번역을 하냐고요? 일단 있으니까.. -_-; 그리고 본가가 아닌 다른 곳 - SSP에서 PLUGIN/2.0 스펙으로 확장해 사용하기 때문입니다. SpecPlugin에서는 일단 본가의 내용을 따라 PLUGIN/1.0만을 다루며, PLUGIN/2.0 프로토콜에 대한 자세한 사항은 SSP 개발 사이트의 PLUGIN/2.0 스펙을 참고 바랍니다.

개요

plugin 디렉토리에 다음 형식으로 파일을 배치하면, 그 DLL 는 Embryo 기동과 동시에 로드 되어 종료까지 상주한다. Embryo 는 NOTIFY 인터페이스에 의해, 이러한 DLL 에 이벤트의 통지를 한다. Embryo 의 pop-up menu에는 「플러그 인」부메뉴가 있어, 그곳으로부터 각 플러그 인의 설정을 할 수가 있다. 이상 3가지 이외의 일은 아무것도 하지 않는다. 이 구조에 의해 이 DLL 은 exe 를 실행시킴으로써 이 DLL 이 로드되어, 메세지 훅등 트리키(Tricky)한 수법을 이용하지 않고 정확하게 본체의 상태를 파악하는 것이 가능한 외부 프로그램으로서 동작한다. 

home
  +--plugin
      +--dummy
          +--descript.txt
          +--dummy.dll

PLUGIN/1.0

descript.txt

descript.txt 에는 이 플러그 인 고유의 정의 정보를 기술한다. 특히 생략 가능하다고 명기하지 않는 한 모든 엔트리는 필수. 

name, 더미 
filename, dummy.dll

name 엔트리에는 이 플러그 인의 명칭을 표현한다.

filename 엔트리에는 실체가 되는 DLL 의 파일명을 표현한다.

DLL 형식

plugin DLL 은 다음 함수를 export 한다. 

extern "C" __declspec(dllexport) HGLOBAL __cdecl getversion(long *len); 
extern "C" __declspec(dllexport) BOOL __cdecl load(HGLOBAL h, long len); 
extern "C" __declspec(dllexport) BOOL __cdecl unload(); 
extern "C" __declspec(dllexport) void __cdecl notify(HGLOBAL h, long *len); 
extern "C" __declspec(dllexport) void __cdecl configure(HWND h);

데이터는 모두 HGLOBAL (주: GMEM_FIXED로 선언된 Global Memory 핸들)로 보내지며 long len 에는 그 데이터의 크기가 저장된다. 건네받는 핸들의 해방(Free)은 모두 건네받은 측(DLL)에 맡기고 있어 건네준 쪽(본체측)에서는 해방을 하지 않는다.

getversion 은 로드시에 불려진다. Plugin DLL 는 PLUGIN/1.0 이라고 하는 10 바이트의 캐릭터 라인을 돌려주지 않으면 안 된다.

load 및 unload 는 각각 DLL 의 로드시/언로드시에 불려진다. load 에는 인수로서 plugin 이 위치 하는 디렉토리의 절대 패스를 건네받는다. plugin 이 독자적으로 설정 파일등을 관리하는 경우, 스스로에 속하는 파일은 모두 이 디렉토리보다 하층에 배치하지 않으면 안 된다.

notify 는 이벤트 통지시에 불려진다. notify 로 건네받는 캐릭터 라인은 아래와 같은 일정한 포맷을 가진다. 

NOTIFY PLUGIN/1.0 
Event: OnGhostChanged 
Reference0: 사쿠라

각 행은 CR+LF 로 구분되며 CR+LF 2개로 종료된다. 이 캐릭터 라인을 분석해서, 플러그 인은 스스로의 동작에 필요한 정보를 얻을 수가 있다.

인자

이벤트 식별자의 일람은 후술 한다.

이벤트를 통지한다, 라는 점에서는, notify 는 Shiori 등의 request 와 매우 닮아 있다. 그러나 본체측이 스크립트를 요구하고 있지 않다는 점으로써 크게 다르다(플러그 인에 인격은 없다). 그 때문에 커멘드는 request 가 아닌 notify 이고, 반환값은 void 이다.

configure 는 pop-up menu상으로부터 이 플러그 인이 선택될 경우, 즉 설정 다이얼로그를 열지 않으면 안 되는 경우에 불려진다. 설정 항목이 없다고 해도 이 함수는 반드시 있을 필요가 있다. 또 유저의 혼란을 막기 위해 최소한 MessageBox 등을 이용해 about 대화창을 띄우는 정도의 동작은 하지 않으면 안 된다.

NOTIFY 이벤트 일람

이하, 이벤트에 참조 정보가 존재하지 않는 경우는 그 기술 자체를 생략 한다.

OnSecondChange

초변화

OnGhostChange

고스트 변화

인수

OnShellChange

쉘 변화

인수

OnVisibleChange

보이는지 상태 변화

OnBoot

기동

CategorySpec

Nanika: SpecPlugin (2008-08-10 19:56:16에 localhost가(이) 마지막으로 수정)