Dongle/Message API

Dongle provides a mechanism for registering and triggering custom "messages" between addons on the same client. This is not a communications module for multiple clients, but rather allows for detatched synchronous inter-addon messages. The API is very similar to the events API, but only works for custom messages, which must be registered seperately from events.

This API was introduced with Dongle-1.0

Certain code within Dongle fires messages in order to notify all dongle objects of the change. These messages are detailed in the API documentation that fires the message under the section "Fires Message".

Register a callback for the given message. These handlers are not called in a predictable order, so don't rely on temporal registration to enforce behavior.

• message (string) - The name of the custom message. As a constant, this is typically in "ALL_CAPS". To ensure no collisions, it is good practice to name your events after your addon, such as "DONGLE_PROFILE_CREATED".
• func (function, string) - A function to be called, or the name of a method to call within the DongleObject.

• func(message, ...)
• DongleObject[func](DongleObject, message, ...)

• If func is specified as a function, the DongleObject is not passed as the first argument, the handler will only receive the arguments sent with the message.
• If func is a string, then DongleObject[func] is called with DongleObject as the first argument, along with the message's arguments.
• Each dongle object may only register for each message once.

Unregisters the given message for this object, if registered.

• message (string) - The name of the custom message.

Unregisters all messages for this object.

Triggers the given message for all registrants immediately. These handlers are wrapped in a safecall to ensure that if one fails, the others will receive their messages.

• message (string) - The name of the custom message.
• ... - Any additional arguments to be passed to handlers