pymsg.send_message

Invokes one specific message handler and returns its result. The handler is identified by an address obtained from pymsg.list_message_handlers.

pymsg.send_message(message, address, subject, value)

Parameter	Type	Description
message	string	The topic, either as the long form PUBLISHER-GUID/TOPIC or as a short topic TOPIC (the calling plugin's GUID is then assumed). The handler addressed must actually handle this topic.
address	string	The opaque handler address returned by pymsg.list_message_handlers.
subject	any	First argument passed to the handler. May be any transferable value (see pymsg).
value	any	Second argument passed to the handler. May be any transferable value.

Return value

Returns two values, status and value:

• On a successful call, these are exactly the two values the handler returned (a handler is expected to return a status and a result value).
• If the call could not be carried out, status is false and value is a string describing the problem. This happens when:
  • the address does not resolve to an installed handler,
  • the addressed handler does not handle the given message topic,
  • the target plugin is currently busy and cannot be re-entered (for example a message sent to your own plugin while it is already handling a message, or a cyclic chain of messages),
  • the handler raised an error while running.

The subject/value arguments and the returned value are copied between the two plugins. See pymsg for the list of transferable value types.

Example:

local handlers = pymsg.list_message_handlers("PRICE-REQUEST")
if #handlers > 0 then
    local status, result = pymsg.send_message("PRICE-REQUEST", handlers[1].address, part, { currency = "EUR" })
    if status then
        pyui.alert("Price: " .. tostring(result.price))
    else
        pyui.alert("Price request failed: " .. tostring(result))
    end
end

Remarks:

A handler always runs in its own isolated execution and inherits the rights of the calling scope. Because the two plugins do not share state, values are deep-copied in both directions; modifying the subject table inside the handler does not affect the caller's copy.

Version Support:

Minimum PYTHA Version: V26

See also:

pymsg, pymsg.list_message_handlers, config.xml: Message Handler Extension