config.xml Message Handler Extension

A Message Handler extension lets a plugin offer a service that other plugins (or the plugin itself) can call, without a hard dependency between them. Plugins cooperate by sending messages to a named topic; any plugin that has registered a handler for that topic can respond.

Declaration of a message-handler extension in the config.xml:

<extension type="message-handler">
    <id>compute-price</id>
    <message>XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/PRICE-REQUEST</message>
    <entry-point>on_price_request</entry-point>
    <caption>Price calculation service</caption>
    <description>Calculates the price of a part on request.</description>
</extension>

The following information can be supplied:

• id - (Mandatory) An identifier for the handler that is unique within the plugin. It is used (together with the plugin's GUID) to address this specific handler.
• message - (Mandatory) The topic this handler listens to, written in the long form PUBLISHER-GUID/TOPIC. The PUBLISHER-GUID part is the GUID of the plugin that defines the topic (which may be a different plugin than the one implementing the handler). The topic is matched case-insensitively.
• entry-point - (Mandatory) Name of the Lua function that is invoked when a message is sent to this handler.
• caption - (Mandatory) A short, human-readable name for the handler. It is returned by pymsg.list_message_handlers and can be shown to the user when several handlers are available. This text is translatable in the .xlif file.
• description - A short descriptive text for the handler. It is also returned by pymsg.list_message_handlers. This text is translatable in the .xlif file.

The handler function

The entry point is invoked with the two values that the sender passed to pymsg.send_message: a subject and a value. It returns a status and a result value:

function on_price_request(subject, value)
    -- ... do the work ...
    return true, { price = 42.0 }
end

Both the incoming subject/value and the returned status/value are copied between the calling plugin and the handler (see Sending and receiving messages for which value types can be transferred).

Topics

A topic is just an agreed-upon string. The plugin that designs a cooperation defines the topic and publishes its meaning (which subject/value a sender should pass and what the handler returns). Other plugins can then implement a handler for that topic, or send messages to it. Because the topic includes the publisher's GUID, topics defined by different publishers never collide.

Execution context

A message handler runs with the same rights as the plugin scope that sent the message. Each message is handled in a fresh, isolated execution; a handler can itself send further messages, but a plugin that is currently handling a message cannot be re-entered (a re-entrant or cyclic send fails gracefully — see pymsg.send_message).

Version Support:

Minimum PYTHA Version: V26

See also:

config.xml, pymsg, pymsg.send_message, pymsg.list_message_handlers, Anatomy of a Lua Api Plugin, Localization and Translation