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 sends addon-channel messages of any length, splitting and reassembling them automatically. All sends are routed through the bundled ChatThrottleLib to prevent server disconnects.

Usage

Sending messages to other clients

Send data with :SendCommMessage. Provide a prefix tag, the text to send, 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

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 messages on the given prefix. The prefix is also registered via C_ChatInfo.RegisterAddonMessagePrefix so the game delivers CHAT_MSG_ADDON events for it. Multipart messages are reassembled before the callback fires.

Parameters

Parameter	Type	Default	Description
prefix	string		A string of printable characters (\032–\255) identifying the message type, typically the addon or event name. Max 16 characters.
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 an addon channel.

Messages up to 255 bytes are sent as a single addon message; longer text is split into tagged chunks and reassembled on the receiving end. A leading control byte (\001–\009) in the text is transparently escaped. prefix, text, and distribution are required; wrong types or an invalid prio raise a usage error.

Parameters

Parameter	Type	Default	Description
prefix	string		A string of printable characters (\032–\255) identifying the message type, typically the addon or event name.
text	string		Text to send. NUL bytes (\000) are not allowed.
distribution	string		Addon channel, e.g. "RAID", "GUILD", etc; see C_ChatInfo.SendAddonMessage API.
target (optional)	string number		Destination for some distributions (e.g. the recipient name for "WHISPER").
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 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.