Внешние модули ИнГео

Содержание

Введение
Создание экземпляра модуля
Описание интерфейсов
Файл описания внешнего модуля
Подключение внешнего модуля
Заключение

Введение

Начиная с версии 4.3 в ГИС ИнГЕО добавлена возможность создания внешних модулей расширения, реализованных в виде COM-интерфейсов.

Внешний модуль реализуется в виде интерфейса стандарта COM, но без необходимости регистрации COM-класса. Экземпляр модуля расширения может создаваться как обычным для COM образом, так и упрощенным - при помощи специальной функции, экспортируемой из DLL-библиотеки.

Со стороны ИнГЕО модулю расширения передается другой интерфейс, предназначенный для доступа к объектам ИнГЕО.

Помимо файла DLL-библиотеки, в каталоге установки ИнГЕО необходимо размещать специальный вспомогательный файл с описанием внешнего модуля.

В начало

Создание экземпляра модуля

Экземпляр модуля может быть создан как обычным для COM способом, так и упрощенным.

При обычном способе необходимо создать COM-класс, реализующий интерфейс IInPlugin.

При упрощенном способе необходимо создать DLL-библиотеку, которая экспортирует функцию создания экземпляра модуля расширения с именем "CreateInPlugin". Ниже приведено описание функции на Delphi:

function CreateInPlugin(const aPluginName: WideString): IInPlugin; stdcall;

Параметр Описание

aPluginName Название модуля расширения, экземпляр которого необходимо создать. Может быть использовано для библиотек, реализующих несколько модулей расширений.

В начало

Описание интерфейсов

Как было сказано выше, функция CreateInPlugin должна создать экземпляр модуля и вернуть его в виде интерфейса IInPlugin.

Описание IInPlugin:

IInPlugin = interface(IUnknown)
  ['{418B6595-915E-4E2B-A388-7146FDC3D73C}']
  procedure Start(const aSite: IInPluginSite); safecall;
  procedure Stop; safecall;
  procedure ExecuteAction(const anActionName: WideString); safecall;
end;

Метод Start вызывается в момент запуска модуля. Через параметр aSite со стороны ИнГЕО внешнему модулю передается интерфейс , предназначенный для доступа к объектам ИнГЕО. Внешний модуль может запомнить ссылку на этот интерфейс, и удерживать ее до вызова метода Stop.

Метод Stop вызывается в момент остановки модуля. В реализации этого метода внешний модуль обязан освободить все ссылки на объекты ИнГЕО, которые он захватил во время работы.

Метод ExecuteAction является обработчиком команд, связанных с внешним модулем.

Со своей стороны ИнГЕО передает внешнему модулю интерфейс IInPluginSite:

IInPluginSite = interface(IDispatch)
  ['{47C4FA1A-A346-4E6D-96E2-1B22C7533C89}']
  function Get_ContextCard: IInContextCard; safecall;
  function Get_Application: IIngeoApplication; safecall;
  function Get_Module: IInModule; safecall;
  function FindScopeObject(const aName: WideString): IDispatch; safecall;
end;

Указанный интерфейс содержит ряд методов для доступа к объектам ИнГЕО:

Метод Описание

Get_ContextCard Возвращает интерфейс на объект, который является карточкой контекста для данного внешнего модуля. Карточка контекста используется при внедрении в интерфейс пользователя ИнГЕО (например, при добавлении пунктов меню). После остановки модуля, все элементы пользователя ИнГЕО, созданные с использованием этой карточки контекста, будут уничтожены.

Get_Application
Возвращает интерфейс на главный объект ИнГЕО.

Get_Module Возвращает интерфейс IInModule, представляющий собой программный модуль ИнГЕО, в рамках которого запущен внешний модуль.

FindScopeObject Возвращает интерфейс на именованные объекты, доступные в среде выполнения внешнего модулю. Всегда доступен объект с именем "Application". В программной среде макета печати дополнительно доступен объект "LayoutWindow" (IInLayoutWindow).

В начало

Файл описания внешнего модуля

Файл описания внешнего модуля должен лежать в каталоге установке ИнГЕО или в любом из его подкаталогов любого уровня вложенности. Файл должен содержать текст в формате XML и иметь расширение "inm". Структура файла описывается в нижеследующей таблице. При описании XML-структуры используется следующая нотация:
название - название элемента;
@название - название атрибута;
text() - внутренний текст элемента.

Элемент/атрибут Описание

modules Корневой элемент.

module Элемент описания отдельного модуля.

    @name название модуля (должно удовлетворять правилам именования идентификаторов в языках программирования).

    @caption Заголовок модуля. Будет отображаться в списке модулей.

    @description Дополнительное описание модуля. Небольшой текст с информацией о модуле.

    @category Категория, к которой относится модуль. Используется в диалоге выбора модулей, в котором они группируются по категориям. Например "Импорт/экспорт". Названия категорий не чувствительны к регистру букв. Категории представляют собой иерархическую структуру. Для определения местоположения модуля в этой структуре в названии категории следует использовать символ "\" для разделения подкатегорий.

    dependency Зависимости от других модулей. Список зависимых модулей указывается тогда, когда необходимо, что бы до запуска данного модуля некоторые другие модули уже были запущены.

      text() Название модуля, от запуска которых зависит данный модуль.

    @plugin-source
Источник модуля. Может быть названием COM-класса (например "Project1.Object1"), идентификатором COM-класса (например "{3605F781-82BF-11D3-9665-000021C6D845}") или именем файла DLL, содержащего функцию CreateInPlugin.

Имя файла библиотеки может содержать две специальных заменяемых вставки:
"{APP}" - все вхождения этой последовательности в имени библиотеки будет заменены на название каталога, в котором расположена ГИС ИнГЕО.
Название каталога не содержит замыкающего "\". Например: "C:\Program Files\Integro\Ingeo".
"{INM}" - все вхождения этой последовательности в имени библиотеки будет заменены на название каталога, в котором расположен этот файл описания внешнего модуля.
Название каталога не содержит замыкающего "\". Например: "C:\Program Files\Integro\Ingeo\Modules\Module1".
Заменяемые вставки позволяют использовать относительные пути вместо абсолютных. Вставки не чувствительны к регистру букв.

    @plugin-name Название внешнего модуля, которое будет передаваться в процедуру "CreateInPlugin", экспортируемую из DLL-библиотеки. Данный атрибут используется только в том случае, если атрибут @plugin-source содержит имя DLL-файла.

В начало

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

Для того, чтобы модуль появился в списке модулей ИнГЕО, достаточно просто разместить файлы DLL и INM в каталог установки ИнГЕО или любом из его подкаталогов любой вложенности. Для запуска модуля в ИнГЕО необходимо воспользоваться командой "ИнГЕО..." из меню "Файл -> Программные модули" или нажать клавишу "F7".

В начало

Заключение

В заключение хотелось бы отметить следующее: файл INM является обычным программным модулем ИнГЕО. Если он будет содержать описание команд, меню, скриптов, то последние будут загружены и запущены после запуска внешнего модуля.

Систему внешних модулей можно рассматривать как небольшое развитие системы программных модулей ИнГЕО. Если рассматривать вопрос с такой точки зрения, то новшество свелось к тому, что у программного модуля появилось два свойства:
"Источник внешнего модуля" и "Название внешнего модуля".

Если эти свойства заданы, то в момент запуска программного модуля будет также запускаться внешний модуль, реализация которого содержится в указанной DLL.

Порядок очередности запуска следующий: сначала стартует программный модуль, затем скрипты. Порядок остановки - обратный.

Если объект внешнего модуля помимо интерфейса IInPlugin реализует интерфейс IDispatch, тогда из скриптов программного модуля будет возможен доступ к объекту внешнего модуля посредством встроенной переменной с именем "Plugin".

В начало

Параметр	Описание
aPluginName	Название модуля расширения, экземпляр которого необходимо создать. Может быть использовано для библиотек, реализующих несколько модулей расширений.

Метод	Описание
Get_ContextCard	Возвращает интерфейс на объект, который является карточкой контекста для данного внешнего модуля. Карточка контекста используется при внедрении в интерфейс пользователя ИнГЕО (например, при добавлении пунктов меню). После остановки модуля, все элементы пользователя ИнГЕО, созданные с использованием этой карточки контекста, будут уничтожены.
Get_Application	Возвращает интерфейс на главный объект ИнГЕО.
Get_Module	Возвращает интерфейс IInModule, представляющий собой программный модуль ИнГЕО, в рамках которого запущен внешний модуль.
FindScopeObject	Возвращает интерфейс на именованные объекты, доступные в среде выполнения внешнего модулю. Всегда доступен объект с именем "Application". В программной среде макета печати дополнительно доступен объект "LayoutWindow" (IInLayoutWindow).

Элемент/атрибут	Описание
modules	Корневой элемент.
module	Элемент описания отдельного модуля.
@name	название модуля (должно удовлетворять правилам именования идентификаторов в языках программирования).
@caption	Заголовок модуля. Будет отображаться в списке модулей.
@description	Дополнительное описание модуля. Небольшой текст с информацией о модуле.
@category	Категория, к которой относится модуль. Используется в диалоге выбора модулей, в котором они группируются по категориям. Например "Импорт/экспорт". Названия категорий не чувствительны к регистру букв. Категории представляют собой иерархическую структуру. Для определения местоположения модуля в этой структуре в названии категории следует использовать символ "\" для разделения подкатегорий.
dependency	Зависимости от других модулей. Список зависимых модулей указывается тогда, когда необходимо, что бы до запуска данного модуля некоторые другие модули уже были запущены.
text()	Название модуля, от запуска которых зависит данный модуль.
@plugin-source	Источник модуля. Может быть названием COM-класса (например "Project1.Object1"), идентификатором COM-класса (например "{3605F781-82BF-11D3-9665-000021C6D845}") или именем файла DLL, содержащего функцию CreateInPlugin. Имя файла библиотеки может содержать две специальных заменяемых вставки: "{APP}" - все вхождения этой последовательности в имени библиотеки будет заменены на название каталога, в котором расположена ГИС ИнГЕО. Название каталога не содержит замыкающего "\". Например: "C:\Program Files\Integro\Ingeo". "{INM}" - все вхождения этой последовательности в имени библиотеки будет заменены на название каталога, в котором расположен этот файл описания внешнего модуля. Название каталога не содержит замыкающего "\". Например: "C:\Program Files\Integro\Ingeo\Modules\Module1". Заменяемые вставки позволяют использовать относительные пути вместо абсолютных. Вставки не чувствительны к регистру букв.
@plugin-name	Название внешнего модуля, которое будет передаваться в процедуру "CreateInPlugin", экспортируемую из DLL-библиотеки. Данный атрибут используется только в том случае, если атрибут @plugin-source содержит имя DLL-файла.