AceComm-2.0

From WowAce Wiki
Jump to: navigation, search


Contents

Links

Example

MyAddon = AceLibrary("AceAddon-2.0"):new("AceComm-2.0")

MyAddon.commPrefix = "MyAddon"

function MyAddon:OnEnable()
    self:RegisterComm(self.commPrefix, "GUILD", "OnCommReceive")
    -- receive guild messages sent from other players with this addon.
end

function MyAddon:OnCommReceive(prefix, sender, distribution, message)
    print(sender, "sent", message)
end

function MyAddon:DoSomething()
    self:SendCommMessage("GUILD", "Here is a message")
end

API Documentation

Distributions

There are 7 kinds of distributions:

"GLOBAL" 
Using the global "AceComm" channel, all addons join this, so it can get very spammy, so that should be avoided at all costs.
"ZONE" 
Using a per-zone "AceCommZone<checksum>" channel, addons join this if in the same zone. It can get spammy, but much less so than "GLOBAL". Consider using this instead of "GLOBAL". Automatically changes on zone change.
"CUSTOM" 
Using a custom channel "AceComm<name>", where <name> is defined by your addon. Though this is likely to get less traffic than the GLOBAL channel, it takes up one out of the ten available channel slots, so be wary about using it. Consider using "ZONE" instead of this.
"WHISPER" 
Simple whispering between players. Prefixed with "/", so you know it's an addon. If it is prefixed with "/", it should not show the message to the user.
"PARTY" 
Sends to members of your party
"RAID" 
Sends to members of your raid
"BATTLEGROUND" 
Sends to persons in the current battleground
"GROUP" 
Sends to "BATTLEGROUND" if in the battlegrounds, to "RAID" if you are in a raid, or to "PARTY" if you are in a party. In that order.
"GUILD" 
Sends to members of your guild.

It is recommended you use "GROUP" instead of "BATTLEGROUND", "RAID", or "PARTY".

Priorities

There are 3 kinds of priorities

"BULK" 
bulk messages that are by no means time-crucial. Example: roleplaying information.
"NORMAL" 
normal messages. This is the default.
"ALERT" 
alert messages that are very time-critical. Example: real-time raid information.

:RegisterComm("prefix", "distribution" [, "methodName" or func ]) or ("prefix", "CUSTOM", "channelName", [, "methodName" or func ])

Register for a communcation stream.


Args

"prefix" 
string - prefix identifier of the addon which controls the stream.
"distribution" 
string - distribution type that is used. One of "GLOBAL", "ZONE", "CUSTOM", "WHISPER", "PARTY", "RAID", "GUILD", "BATTLEGROUND", or "GROUP".
"channelName" 
string - custom-defined channel name. Must be provided if "distribution" is "CUSTOM".
["methodName" or func] 
string - name of the method handler (if not provided, method "OnCommReceive" is used)
function - function to call


Remarks

The method/function provided takes on the arguments ("prefix", "sender", "distribution", ...) unless it is a "CUSTOM" distribution, in which case it is ("prefix", "sender", "distribution", "channelName", ...)

Also, you can use a table of methods, if you want, that will react to different commands specifically.

Handlers will only receive messages set with the prefix you register for here.

This will automatically join channels if needed.


Example

function MyAddon:OnCommReceieve(prefix, sender, distribution, message)
    print("message from", sender, "-", message)
end
-- then in OnEnable
MyAddon:RegisterComm("MyAddon", "GUILD")

alternatively:


MyAddon.OnCommReceive = {}

function MyAddon.OnCommReceive:Command1(prefix, sender, distribution, message)
    print("Command1 from", sender, "-", message)
end

function MyAddon.OnCommReceive:Command2(prefix, sender, distribution, message)
    print("Command2 from", sender, "-", message)
end
-- then in OnEnable
MyAddon:RegisterComm("MyAddon", "GUILD")
MyAddon:SendCommMessage("GUILD", "Command1", ...)
MyAddon:SendCommMessage("GUILD", "Command2", ...)

:UnregisterComm("prefix" [, "distribution"]) or ("prefix", "CUSTOM" [, "channelName"])

Unregister from a communication stream.


Args

"prefix" 
string - prefix identifier of the addon which controls the stream.
["distribution"] 
string - distribution type that is used. One of "GLOBAL", "ZONE", "CUSTOM", "WHISPER", "PARTY", "RAID", "GUILD", "BATTLEGROUND", or "GROUP". (default: all)
["channelName"] 
string - custom-defined channel name. Only available if "distribution" is "CUSTOM". (default: all)

Remarks

This will automatically leave channels if possible.

Example

self:UnregisterComm("MyAddon", "GUILD")

:UnregisterAllComms()

Unregister from all communication streams.


Remarks

This will automatically leave channels if possible.

Note: This is automatically called when the addon is disabled.

Example

self:UnregisterAllComms()

:IsCommRegistered("prefix" [, "distribution"]) or ("prefix", "CUSTOM" [, "channelName"])

Returns whether this is registered with a comm with the specified prefix (and distribution).


Args

"prefix" 
string - prefix identifier of the addon which controls the stream.
["distribution"] 
string - distribution type that is used. One of "GLOBAL", "ZONE", "WHISPER", "PARTY", "RAID", "GUILD", "BATTLEGROUND", or "GROUP". (default: any)
["channelName"] 
string - custom-defined channel name. Only available if "distribution" is "CUSTOM" (default: any)

Returns

boolean - whether this is registered with a comm with the specified prefix (and distribution).

Example

local registered = self:IsCommRegistered("MyAddon", "GLOBAL")

:SendCommMessage("distribution", ...) or ("WHISPER", "person", ...) or ("CUSTOM", "channelName", ...)

Sends a comm message to the appropriate stream determined by "distribution".

Args

"distribution" 
string - distribution type that is used. One of "GLOBAL", "ZONE", "CUSTOM", "WHISPER", "PARTY", "RAID", "GUILD", "BATTLEGROUND", or "GROUP".
"person" 
string - person to whisper. (Must be defined if "distribution" is "WHISPER")
"channelName" 
string - custom-defined channel name. (Must be defined if "distribution" is "CUSTOM")
... 
values to send through the stream (up to 20). (These can be absolutely anything, no matter the type, content, or size)

Remarks

The messages are properly encoded to handle drunkenness, |, \000, and \n, then serialized so that any value can be sent through (not just strings), then properly split up if it is too large and datagrammed onto multiple messages. It is also properly throttled so that not too much is sent across at once.

This uses a NORMAL priority unless self.commPriority is set.

Do not be afraid to send more than one value, it is typically much cleaner to do so. e.g. sending "WARRIOR hits 42" is actually a lot less optimized than sending "WARRIOR", "hits", 42.

If you choose to use memoization (recommended), messages are transparently memoized an dememoized properly.

Messages sent over the stream won't trigger the OnCommReceive (or whatever you called it) function for the sender, even if you technically receive it.

Returns

boolean - whether the message successfully sent.

Example

self:SendCommMessage("GUILD", "Message", 52, { alpha = "bravo" }) -- sends the values across the guild stream.
self:SendCommMessage("WHISPER", "Ckknight", "Here is my message") -- whispers a message to Ckknight.
self:SendCommMessage("CUSTOM", "Monkey", "Here is a monkey-related message", 42, "ROGUE") -- sends a message to the custom Monkey channel.

:SendPrioritizedCommMessage("priority", "distribution", ...) or ("priority", "WHISPER", "person", ...) or ("priority", "CUSTOM", "channelName", ...)

Sends a comm message to the appropriate stream determined by "distribution".

Args

"priority" 
string - priority that is used. One of "BULK", "NORMAL", or "ALERT"
"distribution" 
string - distribution type that is used. One of "GLOBAL", "ZONE", "CUSTOM", "WHISPER", "PARTY", "RAID", "GUILD", "BATTLEGROUND", or "GROUP".
"person" 
string - person to whisper. (Must be defined if "distribution" is "WHISPER")
"channelName" 
string - custom-defined channel name. (Must be defined if "distribution" is "CUSTOM")
... 
values to send through the stream (up to 20). (These can be absolutely anything, no matter the type, content, or size)

Remarks

The messages are properly encoded to handle drunkenness, |, \000, and \n, then serialized so that any value can be sent through (not just strings), then properly split up if it is too large and datagrammed onto multiple messages. It is also properly throttled so that not too much is sent across at once.

Returns

boolean - whether the message successfully sent.

Example

self:SendCommMessage("BULK", "GUILD", "Message", 52, { alpha = "bravo" }) -- sends the values across the guild stream.
self:SendCommMessage("NORMAL", "WHISPER", "Ckknight", "Here is my message") -- whispers a message to Ckknight.
self:SendCommMessage("ALERT", "GROUP", "Here is an important message") -- sends a message to the group.

:SetCommPrefix("prefix")

Sets the prefix attached to this addon.

Args

"prefix" 
Prefix of the addon if you are to send comm messages.

Remarks

Do not worry about the length of the prefix, it will be properly memoized.

This can only be called once, and must be called before sending any messages.

Each addon must have its own prefix, they cannot be shared.

Example

self:SetCommPrefix("MyAddon")

:SetDefaultCommPriority("priority")

Sets the default priority for using :SendCommMessage.


Args

"priority" 
default priority of messages.

Remarks

This can only be called once. If it is not called, "NORMAL" is the default priority.

"priority" can only be "BULK", "NORMAL", or "ALERT"


Example

self:SetDefaultCommPriority("BULK")

:RegisterMemoizations(values)

Registers a list of strings to be memoized.

Args

values 
table - a table of strings.

Remarks

This is extremely useful in cutting down the size of your messages. Sending a string has a cost of 2 + length. Sending a memoized string has a cost of 4.

Example

self:RegisterMemoizations { "REGISTER", "VERSION", "WARRIOR", "ROGUE", "MONKEY" }
-- now if I ever choose to send through one of these words, it will be properly memoized.

:IsUserInChannel(["username"], "distribution") or ("username", "CUSTOM", "channelName")

Returns whether a user is in the specified channel.

Args

"username" 
string - name of the other user. (Case-sensitive)
nil - UnitName("player")
"distribution" 
string - "GLOBAL", "ZONE", or "CUSTOM"
"channelName" 
string - custom channel name, only needed when "distribution" is "CUSTOM"

Remarks

Since the user list is fetched after you join, you must wait a while for the list to come in before it is complete (depending on the amount of users). Thus, calling this right away will not give the correct results.

This can be called from either AceComm or your own addon without issue.

Returns

boolean - whether a user is in the specified channel.

Example

local inChannel = AceLibrary("AceComm-2.0"):IsUserInChannel("Ckknight", "GLOBAL")
local inOtherChannel = self:IsUserInChannel("Otherguy", "CUSTOM", "Monkey")

:QueryAddonVersion("addon", "distribution" [, "player"]) [not exported]

Sends a message to another player or group of players requesting the version of a specified addon or library

Args

"addon" 
string - name of the addon.
"distribution" 
string - "WHISPER", "GROUP", "RAID", "PARTY", "BATTLEGROUND", or "GUILD"
["player"] 
string - name of the player, only works when distribution is "WHISPER".

Remarks

This sends out the message, and the reply is sent back which is handled through :RegisterAddonVersionReceptor

Example

AceLibrary("AceComm-2.0"):QueryAddonVersion("BigWigs", "WHISPER", "Monkeyman")

:RegisterAddonVersionReceptor(obj, "method") or (func) [not exported]

Registers a receptor function that will be called when a player's addon version is sent.

Args

obj 
table - object which holds "method"
"method" 
string - method to call on reception.
func 
function - function to call on reception.

Remarks

The reception function takes the API of func("player", "addon", version)

version is false if it is not loaded, true if it is loaded but no version known, or a string which tells the specific version.

Example

AceLibrary("AceComm-2.0"):QueryAddonVersion(function(player, addon, version)
    if version then
        if version == true then
            AceLibrary("AceConsole-2.0"):Print("Player %s has %s", player, addon)
        else
            AceLibrary("AceConsole-2.0"):Print("Player %s has %s version %s", player, addon, version)
        end
    else
        AceLibrary("AceConsole-2.0"):Print("Player %s does not have %s", player, addon)
    end
end)

Event: AceComm_JoinedChannel - "distribution" or "CUSTOM", "channelName"

Fired when a channel is joined for the specified distribution.

Args

"distribution" 
"ZONE", "GLOBAL", or "CUSTOM"
"channelName" 
name of the channel

Remarks

"ZONE", "GLOBAL", and "CUSTOM" are the only distributions that apply, since the other ones ("WHISPER", "PARTY", etc.) are automatically available.

Example

function self:AceComm_JoinedChannel(distribution, channelName)
    if distribution == "ZONE" then
        -- zone change, send information.
    end
end
self:RegisterEvent("AceComm_JoinedChannel")

Event: AceComm_LeftChannel - "distribution"

Fired when a channel is left for the specified distribution.

Args

"distribution" 
"ZONE", "GLOBAL", or "CUSTOM"

Remarks

"ZONE", "GLOBAL", and "CUSTOM" are the only distributions that apply, since the other ones (WHISPER, PARTY, etc.) are automatically available.

Example

function self:AceComm_LeftChannel(distribution, channelName)
    if distribution == "ZONE" then
        -- zone change, stop sending.
    end
end
self:RegisterEvent("AceComm_LeftChannel")