AceComm-3.0

embeddable This library can be embedded into your addon as a mixin; list it when you create the addon and its methods become available directly on your addon object (via self).
Creating an addon object →

AceComm-3.0 allows you to send messages of unlimited length over the addon communication channels. It automatically splits the messages into multiple parts and rebuilds them on the receiving end. ChatThrottleLib is of course being used to avoid being disconnected by the server.

Usage

Sending messages to other clients

Send data with :SendCommMessage: give it a prefix tag, the text to send (any length; it's split and reassembled for you), and a distribution channel:

MyAddon:SendCommMessage("MyPrefix", "the data to send", "RAID")
MyAddon:SendCommMessage("MyPrefix", "more data to send", "WHISPER", "charname")

TIP

The valid distributions ("PARTY", "RAID", "GUILD", "WHISPER", …) are defined by the game's C_ChatInfo.SendAddonMessage API and vary by client version.

Receiving messages

Register the prefix you want to listen for. The default handler is OnCommReceived:

MyAddon:RegisterComm("prefix")
MyAddon:RegisterComm("prefix2", "MySecondCommHandler")

function MyAddon:OnCommReceived(prefix, message, distribution, sender)
    -- process the incoming message
end

The handler receives prefix, message, distribution, and sender.

API Reference

Embed

method#

AceComm:Embed(target)

Copies AceComm's methods onto target so you can call them on it directly. See The :Embed method.

Parameters

Parameter	Type	Default	Description
target	table		The object to embed AceComm-3.0 into.

Returns

Type	Description
table	The target object, now embedded with the AceComm methods.

RegisterComm

method#

AceComm:RegisterComm(prefix, method?)

Register for Addon Traffic on a specified prefix. The prefix is also registered with the client's addon-message prefix system (C_ChatInfo.RegisterAddonMessagePrefix) so the game will deliver CHAT_MSG_ADDON events for it. Multipart messages are automatically reassembled before the callback fires.

Parameters

Parameter	Type	Default	Description
prefix	string		A printable character (\032-\255) classification of the message (typically AddonName or AddonNameEvent), max 16 characters. Registering a prefix longer than 16 characters raises an error.
method (optional)	function | string	"OnCommReceived"	Callback to call on message reception: function reference, or method name to call on self. The callback receives prefix, message, distribution, and sender.

Returns

Type	Description
table	The registration object returned by CallbackHandler (used internally to track the callback).

Example

self:RegisterComm("MyPrefix")

function MyAddon:OnCommReceived(prefix, message, distribution, sender)
    -- process the incoming message
end

SendCommMessage

method#

AceComm:SendCommMessage(prefix, text, distribution, target?, prio?, callbackFn?, callbackArg?)

Send a message over the Addon Channel.

Text of any length is supported: messages up to 255 bytes are sent in a single addon message, while longer text is automatically split into chunks (each tagged so the receiving side can reassemble it in order). A leading control character (\001-\009) in the text is transparently escaped. All sends go through ChatThrottleLib using the given priority to avoid being disconnected by the server. prefix, text, and distribution are required; passing arguments of the wrong type (or an invalid prio) raises a usage error.

Parameters

Parameter	Type	Default	Description
prefix	string		A printable character (\032-\255) classification of the message (typically AddonName or AddonNameEvent).
text	string		Data to send, nils (\000) not allowed. Any length.
distribution	string		Addon channel, e.g. "RAID", "GUILD", etc; see SendAddonMessage API.
target (optional)	string | number		Destination for some distributions (e.g. the recipient name for "WHISPER"); see SendAddonMessage API.
prio (optional)	string	"NORMAL"	ChatThrottleLib priority, "BULK", "NORMAL" or "ALERT". The same priority is used for every chunk of a multipart message to guarantee in-order delivery.
callbackFn (optional)	function		Callback function called as each chunk is sent. Receives 3 args: the user-supplied arg (see next), the number of bytes sent so far, and the number of bytes total to send.
callbackArg (optional)	any		First arg to the callback function. Nil will be passed if not specified.

UnregisterComm

method#

AceComm:UnregisterComm(prefix)

Unregister a comm callback previously registered with :RegisterComm for the given prefix. This method is generated by CallbackHandler.

Parameters

Parameter	Type	Default	Description
prefix	string		The prefix to stop listening for.

UnregisterAllComm

method#

AceComm:UnregisterAllComm()

Unregister all comm callbacks registered by this addon object (or custom self). This method is generated by CallbackHandler and is also called automatically when an embedded AceComm is disabled.