Подключение модуля

В зависимости от выбранного варианта связи с модулем (экспортируемые функции или COM), информация об этом должна быть задана с помощью следующих тегов:

Тег Значение
clsid CLSID объекта. Модуль представляет собой COM-объект (ActiveX object) или элемент ActiveX (ActiveX control)
progid ProgID объекта. Модуль представляет собой COM-объект или элемент ActiveX
moduleПуть к библиотеке (.dll файлу). Интерфейс с модулем предоставляется через экспортируемые функции.

При запуске модуля ZuluGIS проверяет наличие одного из перечисленных выше тегов в последовательности, указанной в таблице. В случае наличия тегов clsid или progid, ZuluGIS проверяет, является ли объект элементом ActiveX (ActiveX control), если нет, то он рассматривается как COM-объект поддерживающий OLE Automation.

Далее загрузка и подключение модуля происходит по одному из трех сценариев:

Подключение модуля в виде простой DLL

Ниже представлен фрагмент манифеста модуля в виде простой DLL:

<plugin id="myplugin" name="My Plugin">
    <module>MyPlugin.dll</module>
...

Порядок загрузки модуля:

  1. Загружается библиотека, указанная в теге module с помощью функции LoadLibrary Win32 API.

  2. Получение адреса функции подключения модуля. По умолчанию такой функцией является:

    extern ”C” BOOL __declspec(dllexport) __stdcall ConnectZuluPlugin(IPluginConnector *pConn, LPDWORD lpdwCookie);

    Для получения адреса используется декорированное (mangled) имя этой функции, которое при компиляции модуля в Microsoft Visual C++ будет иметь вид _ConnectZuluPlugin@8.

    В случае использование функции с другим именем или если декорация (mangling) имен отличается от MSVC (например, Borland Delphi или Borland C++Builder), имя функции с помощью тега connectmethod:

    <plugin id="myplugin" name="My Plugin">
        <module>MyPlugin.dll</module>
        <connectmethod name="MyConnectMethod"/>
    ...

    Значение атрибута name должно отвечать соглашениям для вызова функции GetProcAddress Win32 API.

  3. Вызывается функция подключения. Первым параметром этой функции передается адрес на дуальный интерфейс IPluginConnector object, представляющий собой объект-посредник между ZuluGIS и дополнительным модулем. Второй параметр – указатель на двойное слово (DWORD), в которое может быть записано любое определяемое модулем значение и использоваться по усмотрению разработчика модуля. В дальнейшем, при вызове остальных методов модуля первым параметром будет передаваться указанный DWORD. Таким образом, dwCookie служит неким this (по аналогии с языком C++) или дескриптором (handle) для конкретного подключения модуля. При успешном подключении функция должна вернуть значение TRUE.

Подключение модуля в виде COM-объекта

Ниже представлен пример регистрации модуля в виде COM-объекта:

<plugin id="myplugin" name="My Plugin">
    <progid>MyPlugin.MyPluginObject</progid>
...

либо:

<plugin id="myplugin" name="My Plugin">
    <clsid>{12345678-1234-1234-1234-1234567890AB}</clsid>
...

Порядок загрузки модуля:

  1. Создание экземпляра объекта посредством вызова функции CoCreateInstance Win32 API. Объект задается либо с помощью тегом progid, либо clsid, как удобней разработчику. При создании объекта, ZuluGIS запрашивает у него интерфейс IDispatch, поэтому объект должен либо поддерживать непосредственно интерфейс IDispatch, либо дуальный интерфейс, порожденный от IDispatch.

  2. Вызов метода подключения. По умолчанию этот метод имеет следующий вид:

    IDL:
    [id(dispid)] HRESULT ConnectZuluPlugin([in] IDispatch *pConn,[out,retval] VARIANT_BOOL *pRetVal);
    'Visual Basic:
    Public Function ConnectZuluPlugin(Connector As IPluginConnector) As Boolean 

    Если для подключения предполагается использовать другое имя метода, то это имя можно указать с помощью элемента connectmethod:

    <plugin id="myplugin" name="My Plugin">
        <connectmethod name="MyConnectMethod"/>

    В случае успеха метод должен вернуть значение True (VARIANT_TRUE).   

Подключение модуля в виде элемента ActiveX

Модуль в виде элемента ActiveX задается в манифесте также как и COM-модуль с помощью элемента progid или clsid. Для того, чтобы система знала что указанный объект - элемент ActiveX, необходимо добавить атрибут control:

<plugin id="myplugin" name="My Plugin">
    <progid control="1">MyPlugin.MyPluginObject</progid>
...

или

<plugin id="myplugin" name="My Plugin">
    <clsid control="1">{12345678-1234-1234-1234-1234567890AB}</clsid>
...

ZuluGIS загружает модуль в следующем порядке:

  1. Создается панель, куда внедряется экземпляр указанного элемента ActiveX по указанному ProgID или CLSID;

  2. Вызывается метод подключения. Формат метода подключения аналогичен подключению обычного COM-объекта.

Панель, в которую внедряется элемент ActiveX по-умолчанию отображается плавающей, способной «схлопываться» и «докироваться» как и другие рабочие окна ZuluGIS, а при закрытии вызывает выгрузку плагина, если не задано иное поведение.

Поведение панели можно задать в манифесте с помощью элемента controlbar (см. «Управление окном модуля»)

Метод подключения модуля

Вызов метода подключения предоставляет возможность произвести инициализацию загруженного модуля и проанализировать возможность его дальнейшей работы.

В случае, когда метод подключения модуля возвращает значение FALSE, подключение модуля прерывается и модуль выгружается из памяти. В случае, если загрузка модуля вызвана выполнением команды, предоставляемой данным модулем, выполнение указанной команды прерывается с возвратом в систему результата FALSE.

Первым параметром методу подключения передается объект IPluginConnector object, который является посредником между ZuluGIS и модулем. Свойство Zulu property (IPluginConnector) этого объекта дает доступ к корневому объекту объектной модели системы.

Обычно объект IPluginConnector сохраняется во внутренней переменной для дальнейшего использования. Однако, когда модуль выгружается, при выполнении метода отсоединения модуля этот объект должен быть высвобожден.