Взаимодействие с плагинами

...=Plugin.Call(PluginId,...)

Вызвать плагин, имеющий идентификатор PluginId с параметрами ....

Параметры:

PluginId
string (GUID плагина в текстовом представлении)
...

ноль или более дополнительных параметров

Параметры передаются плагину в соответствии с их Lua-типами:

  • nil ⟶ FMVT_NIL
  • boolean ⟶ FMVT_BOOLEAN
  • number ⟶ FMVT_DOUBLE
  • int64 ⟶ FMVT_INTEGER (int64 — тип userdata, создаваемый библиотекой bit64)
  • string ⟶ FMVT_STRING (автоматически преобразуется из UTF-8 в UTF-16LE)
  • {string} ⟶ FMVT_BINARY (для того, чтобы передать произвольный стринг без преобразования UTF-8 ⟶ UTF16LE, его нужно передавать, помещённым в таблицу как элемент с ключом 1)

Возвращает:

...

ноль или более возвращаемых значений

Величины, возвращаемые плагином через структуру FarMacroCall, передаются макросу следующим образом:

  • FMVT_NIL ⟶ nil
  • FMVT_BOOLEAN ⟶ boolean
  • FMVT_DOUBLE ⟶ number
  • FMVT_INTEGER ⟶ number, если “укладывается” в 53 бита, иначе int64
  • FMVT_STRING ⟶ string (автоматически преобразуется из UTF-16LE в UTF-8)
  • FMVT_BINARY ⟶ table (в таблице передаётся строка как элемент с ключом 1; передаётся как есть, без преобразования)
  • FMVT_POINTER ⟶ light userdata
  • FMVT_ARRAY ⟶ table: массив элементов; в таблице установлено два поля:
    • ["type"] = "array", и
    • ["n"] = количество элементов массива

Plugin.Call вызывает экспортируемую функцию OpenW требуемого плагина, передавая указанные параметры.

Дальнейшие действия зависят от того, как плагин обработал этот параметр.

Функция возвращает false, если вызываемого плагина нет. В других случаях функция возвращает значения, полученные от плагина.

  1. Функция осуществляет “асинхронный” вызов плагина. Если вызов в действительности оказался асинхронным (например, если плагин вывел диалог на экран), функция возвращает true, не дожидаясь возврата от плагина, и макрос продолжает исполнение.

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

    • Если плагин не найден или вернул 0, макросу возвращается false.
    • Если плагин вернул 1 или INVALID_HANDLE_VALUE, макросу возвращается true.
    • Если плагин вернул указатель на структуру FarMacroCall, см. выше.
...=Plugin.SyncCall(PluginId,...)

Синхронный вызов плагина

Данная функция работает идентично Plugin.Call, за исключением того, что:

  1. Её вызов — всегда синхронный, то есть возврат управления макросу происходит только после возврата функции OpenW плагина.
  2. Данная функция не имеет [ограничений][async_limits] в использовании, которые есть у Plugin.Call.
N=Plugin.Command(Guid,Command)

Аналог вызова плагина по префиксу из панелей без необходимости запоминать/очищать/восстанавливать текущее содержимое командной строки.

Guid можно посмотреть в диалоге “Plugin information” (F3 в списке F11 или Alt+Shift+F9): поле “Plugin GUID”.

Если плагин с таким Guid не поддерживает вызов по префиксу или при вызове не из панелей — функция вернёт ошибку.

Функция возвращает true — плагин/пункт найден или false — в случае ошибки.

N=Plugin.Config(Guid[,MenuGuid])

Аналог вызова плагина из меню “Параметры плагинов” без необходимости задавать горячие клавиши или искать плагин в списке. Работает только в панелях.

Guid и MenuGuid можно посмотреть в диалоге “Plugin information” (F3 в списке): поля “Plugin GUID” и “Plugin item GUID” соответственно.

Обязательно нужно указать Guid плагина. MenuGuid требуется указывать в том случае, если плагин экспортирует более одного пункта меню.

Если плагин отсутствует в списке “Параметры плагинов” или при вызове не из панелей — функция вернёт ошибку.

Функция возвращает true — плагин/пункт найден или false — в случае ошибки.

N=Plugin.Exist(Guid)

Позволяет узнать наличие в системе плагина с идентификатором Guid.

Функция возвращает true — плагин/пункт найден или false — в случае ошибки.

N=Plugin.Menu(Guid[,MenuGuid])

Аналог вызова плагина из меню плагинов по F11 без необходимости задавать горячие клавиши или искать плагин в списке.

Guid и MenuGuid можно посмотреть в диалоге “Plugin information” (F3 в списке): поля “Plugin GUID” и “Plugin item GUID” соответственно.

Обязательно нужно указать Guid плагина. MenuGuid требуется указывать в том случае, если плагин экспортирует более одного пункта меню.

Если плагин отсутствует в списке F11 для текущей макрообласти — функция вернёт ошибку.

Функция возвращает true — плагин/пункт найден или false — в случае ошибки.

Пример использования — открыть FarColorer\Outliner list:

local ColorerID = "D2F36B62-A470-418D-83A3-ED7A3710E5B5"
local ColorerMenuID = "45453CAC-499D-4B37-82B8-0A77F7BD087C"
if Plugin.Menu(ColorerID,ColorerMenuID) then
  Keys("5")
end
N=Plugin.Load(DllPath[,ForceLoad])

Загрузить плагин с именем dll-модуля DllPath. Если указан ForceLoad (число, отличное от 0), то плагин загружается сразу в память.

Функция возвращает число, отличное от 0 — плагин загружен или 0 — в случае ошибки.

N=Plugin.Unload(DllPath)

Выгрузить плагин с именем dll-модуля DllPath.

Функция возвращает 1 — плагин выгружен или 0 — в случае ошибки.