msys.registerControl

March 26, 2020 Contributors

Name

msys.registerControl — Register a command with the control channel subsystem

Synopsis

msys.registerControl(prefix, closure);

prefix: string
closure: string

Description

This function registers a command with the control channel subsystem (see ec_console). A command prefixed with prefix will be dispatched to closure. Because this function registers a control. it is not associated with a particular phase or callout.

Enable this function with the statement require('msys.core');.

Find below an example of a command that forces email messages into the delayed queue.

require("msys.core");

local function delay_domain(cc)
  -- Check the number of parameters
  if cc.argc < 2 then
    print("You must pass a parameter to this command");
    return;
  end
  local domain = cc.argv[1];
  local dr = msys.core.dns_get_domain(domain);
  if dr ~= nil then
    msys.core.mail_queue_delay_domain(dr, "451 4.4.1 [internal] manually delayed domain]");
    print(domain, "added to the delayed queue.");
  end
end

msys.registerControl("delay_domain", delay_domain);

Warning

Be sure to check the number of parameters passed to the registered command. Referencing a non-existent element of the cc.argv array causes a segmentation fault.

This code creates the ec_console command: delay_domain "domain" . Be sure to use quotation marks around the domain that you wish to delay. Registered control functions can return string responses back to ec_console by using Lua’s print() function as shown in “registerControl example”.

Because this function is in the msys namespace, an explicit require is not necessary.

Command Construct Userdata

The function that performs the registered action, in “registerControl example”, delay_domain, accepts as a parameter command_construct userdata. cc.argc returns the number of arguments supplied by the console command, with the first argument being the command name, so this example will have two arguments. cc.argv[0] is the command name and cc.argv[1] is the name of the domain that you wish to add to the delayed queue. For more sophisticated argument parsing use require("msys.getopt");. For more information examine the getopt.lua file found in the /opt/msys/ecelerity/libexec/scriptlets/msys directory.

See Also

msys.core.dns_get_domain and command_construct