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

Contents 1 Dongle Messages 2 DongleObject:RegisterMessage(message, func) 2.1 Arguments 2.2 Callback Signature 2.3 Behavior 3 DongleObject:UnregisterMessage(message) 3.1 Arguments 4 DongleObject:UnregisterAllMessages() 5 DongleObject:TriggerMessage(message, ...) 5.1 Arguments

Dongle MessagesEdit

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".

DongleObject:RegisterMessage(message, func)Edit

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.

ArgumentsEdit

• 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.

Callback SignatureEdit

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

BehaviorEdit

• 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.

DongleObject:UnregisterMessage(message)Edit

Unregisters the given message for this object, if registered.

ArgumentsEdit

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

DongleObject:UnregisterAllMessages()Edit

Unregisters all messages for this object.

DongleObject:TriggerMessage(message, ...)Edit

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.

ArgumentsEdit

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