Call

Call

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

Parameters:
  PluginId: string (plugin's GUID in textual representation)
  ...     : zero or more additional parameters

Returns:
  ...     : zero or more return values

Description:
  1. The function implements the "asynchronous" plugin call.
     If the plugin call turned out to be asynchronous (e.g. if the plugin displayed
     a dialog on the screen) then the function returns true without waiting for the plugin
     return, and the macro continues its execution.

  2. If the plugin call turned out to be synchronous, the macro gets values corresponding
     to those returned by the plugin:
     - If the plugin is not found or returned 0, then false is returned to the macro.
     - If the plugin returned 1 or INVALID_HANDLE_VALUE, then true is returned to the macro.
     - If the plugin returned a pointer to a FarMacroCall structure, see p. 4.

  3. Arguments are passed to the plugin in accordance with their Lua types:
       nil      -> FMVT_NIL
       boolean  -> FMVT_BOOLEAN
       number   -> FMVT_DOUBLE
       int64    -> FMVT_INTEGER (int64 - kind of userdata, created by bit64 library)
       string   -> FMVT_STRING  (automatically converted from UTF-8 to UTF-16LE)
       {string} -> FMVT_BINARY  (in order to pass an arbitrary string without UTF-8 -> UTF16LE
                                conversion, the string should be placed in a table as an element
                                with its key==1)

  4. Values returned by the plugin via a FarMacroCall structure are passed to the macro
     the following way:
       FMVT_NIL     -> nil
       FMVT_BOOLEAN -> boolean
       FMVT_DOUBLE  -> number
       FMVT_INTEGER -> number, if it "fits" in 53 bits, otherwise int64
       FMVT_STRING  -> string (automatically converted from UTF-16LE to UTF-8)
       FMVT_BINARY  -> table (the table contains a string as an element with its key==1;
                              the string is placed as is, without conversion)
       FMVT_POINTER -> light userdata
       FMVT_ARRAY   -> table (array of elements; the table contains 2 fields:
                              ["type"] = "array", and
                              ["n"] = number of array elements)

See also:
Restrictions in the use of some functions