LibRockComm-1.0

From WowAce Wiki

Contents 1 API Documentation 1.1 :AddAddonVersionReceptor(callback) 1.1.1 Arguments 1.1.2 Notes 1.1.3 Example 1.2 :AddCommListener("prefix" , "distribution" [, callback]) 1.2.1 Arguments 1.2.2 Notes 1.2.3 Example 1.3 :AddMemoizations(...) 1.3.1 Arguments 1.3.2 Notes 1.3.3 Example 1.4 :AddTalentReceptor(callback) 1.4.1 Arguments 1.4.2 Notes 1.4.3 Example 1.5 :HasCommListener("prefix" [, distribution]) 1.5.1 Arguments 1.5.2 Returns 1.5.3 Example 1.6 :QueryAddonVersion("addon" , "distribution" [, player]) 1.6.1 Arguments 1.6.2 Notes 1.6.3 Example 1.7 :QueryTalents("distribution" [, player]) 1.7.1 Arguments 1.7.2 Notes 1.7.3 Example 1.8 :RemoveAllCommListeners() 1.8.1 Notes 1.8.2 Example 1.9 :RemoveCommListener("prefix" [, distribution]) 1.9.1 Arguments 1.9.2 Notes 1.9.3 Example 1.10 :SendCommMessage("distribution" , "person" , ...) 1.10.1 Arguments 1.10.2 Notes 1.10.3 Returns 1.10.4 Example 1.11 :SendPrioritizedCommMessage("priority" , "distribution" , "person" , ...) 1.11.1 Arguments 1.11.2 Notes 1.11.3 Example 1.12 :SetCommPrefix("prefix") 1.12.1 Arguments 1.12.2 Notes 1.12.3 Example 1.13 :SetDefaultCommPriority("priority") 1.13.1 Arguments 1.13.2 Notes 1.13.3 Example

API Documentation

Note: This documentation is auto-generated. Please note that direct modifications may be overwritten on next autogenerate.

:AddAddonVersionReceptor(callback)

Arguments

callback

function - function to call on reception

Notes

• This is not exported as a mixin.
• Registers a receptor function that will be called when a player's addon version is sent.
• 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

Rock("LibRockComm-1.0"):AddAddonVersionReceptor(function(player, addon, version)
    if version then
        if version == true then
            print("Player %s has %s", player, addon)
        else
            print("Player %s has %s version %s", player, addon, version)
        end
    else
        print("Player %s does not have %s", player, addon)
    end
end)

string or function or table

:AddCommListener("prefix" , "distribution" [, callback])

Arguments

"prefix"

string - prefix identifier of the addon which controls the stream.

"distribution"

string - distribution type that is used. One of "WHISPER", "GUILD", or "GROUP".

callback

string or function or table - the function to call, or table to handle. Default: "OnCommReceive"

Notes

• Listen to a communication stream
• The callback provided takes on the arguments ("prefix", "distribution", "sender", ...)
• Also, you can use a table of methods, if you want, that will react to different commands specifically.
• Callbacks will only receive messages set with the prefix you register for here.

Example

MyAddon.OnCommReceieve = function(self, prefix, distribution, sender, message)
    print("message from", sender, "-", message)
end
-- then in OnEnable
MyAddon:AddCommListener("MAd", "GUILD")
-- alternatively
MyAddon.OnCommReceive = {}
MyAddon.OnCommReceive.Command1 = function(self, prefix, distribution, sender, message)
    print("Command1 from", sender, "-", message)
end
MyAddon.OnCommReceive.Command2 = function(self, prefix, distribution, sender, otherMessage)
    print("Command2 from", sender, "-", otherMessage)
end
-- then in OnEnable
MyAddon:AddCommListener("MAd", "GUILD")
MyAddon:SendCommMessage("GUILD", "Command1", ...)
MyAddon:SendCommMessage("GUILD", "Command2", ...)

:AddMemoizations(...)

Arguments

...

tuple or table - list of strings to be memoized.

Notes

• Registers a list of strings to be memoized.
• This is useful because it can turn a longer string into a shorter string and as long as both sides have the proper memoizations registered, it will show up properly.
• Sending a normal string has a cost of 2 + length. Sending a memoized string has a cost of 4.
• If you register a tablized comm handler, the commands specified are automatically memoized.

Example

MyAddon:RegisterMemoizations("Register", "Version", "WARRIOR", "ROGUE", "Monkey")
-- or
MyAddon:RegisterMemoizations { "Register", "Version", "WARRIOR", "ROGUE", "Monkey" }
-- now if I ever choose to send through one of these words, it will be properly memoized.

:AddTalentReceptor(callback)

Arguments

callback

function - function to call on reception

Notes

• This is not exported as a mixin.
• Registers a receptor function that will be called when a player's talents are sent.
• The reception function takes the API of func("player", {

class = "CLASS", -- e.g. "PRIEST", "ROGUE", etc. level = 10, -- some integer [1, 70] [1] = { -- for tree 1 [1] = rankOfTalent1, [2] = rankOfTalent2, ... [n] = rankOfTalentN, }, [2] = { -- for tree 2 [1] = rankOfTalent1, [2] = rankOfTalent2, ... [n] = rankOfTalentN, }, [3] = { -- for tree 3 [1] = rankOfTalent1, [2] = rankOfTalent2, ... [n] = rankOfTalentN, }, })

• 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

Rock("LibRockComm-1.0"):AddTalentReceptor(function(player, data)
	local talentsUsed = 0
	for i,v in ipairs(data) do
		for j,u in ipairs(v) do
			talentsUsed = talentsUsed + u
		end
	end
end)

string

:HasCommListener("prefix" [, distribution])

Arguments

"prefix"

string - prefix identifier of the addon which controls the stream.

distribution

string - distribution type that is used. One of "WHISPER", "GUILD", or "GROUP". (default: any)

Returns

boolean or string - whether this is registered with a comm with the specified prefix (and distribution), or the handler which it is registered to.

Example

local registered = MyAddon:HasCommListener("MAd", "GUILD")
-- or
local registered = MyAddon:HasCommListener("MAd") -- any distribution

string

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

Arguments

"addon"

string - name of the addon or library.

"distribution"

string - the distribution to send within. One of "WHISPER", "GROUP", or "GUILD".

player

string - name of the player, only works with "WHISPER".

Notes

• This is not exported as a mixin.
• Sends a message to another player or group of players requesting the version of a specified addon or library.
• This sends out the message, and the reply is sent back which is handled through :RegisterAddonVersionReceptor

Example

Rock("LibRockComm-1.0"):QueryAddonVersion("BigWigs", "WHISPER", "Monkeyman")

string

:QueryTalents("distribution" [, player])

Arguments

"distribution"

string - the distribution to send within. One of "WHISPER", "GROUP", or "GUILD".

player

string - name of the player, only works with "WHISPER".

Notes

• This is not exported as a mixin.
• Sends a message to another player or group of players requesting their talent spec.
• This sends out the message, and the reply is sent back which is handled through :RegisterTalentReceptor

Example

Rock("LibRockComm-1.0"):QueryTalents("WHISPER", "Monkeyman")

:RemoveAllCommListeners()

Notes

• Removes all comm listeners
• This is automatically done at :OnDisable.

Example

MyAddon:RemoveAllCommListeners()

string

:RemoveCommListener("prefix" [, distribution])

Arguments

"prefix"

string - prefix identifier of the addon which controls the stream.

distribution

string - distribution type that is used. One of "WHISPER", "GUILD", or "GROUP". (default: all)

Notes

Removes the listener from the comm stream.

Example

MyAddon:RemoveCommListener("MAd", "GUILD")
-- or
MyAddon:RemoveCommListener("MAd") -- all distributions

:SendCommMessage("distribution" , "person" , ...)

Arguments

"distribution"

string - distribution type that is used. One of "WHISPER", "GUILD", or "GROUP".

"person"

string - person to whisper to (only used with "WHISPER").

...

tuple - arguments to pass through.

Notes

• Sends a comm message to the appropriate stream determined by "distribution".
• The messages are properly encoded to handle special characters like |, \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.
• Messages are properly throttled so that not too much is sent across at once.
• This uses a NORMAL priority unless :SetDefaultCommPriority is called.
• 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, unless you whisper to yourself.

Returns

boolean - whether the message properly sends through.

Example

MyAddon:SendCommMessage("GUILD", "Message", 52, { alpha = "bravo" }) -- sends the values across the guild stream.
MyAddon:SendCommMessage("WHISPER", "Ckknight", "Here is my message") -- whispers a message to Ckknight.
MyAddon:SendCommMessage("GROUP", "Here is a monkey-related message", 42, "ROGUE") -- Sends to your party/raid/battleground, based on which one you are in.

:SendPrioritizedCommMessage("priority" , "distribution" , "person" , ...)

Arguments

"priority"

string - priority that is used. One of "BULK", "NORMAL", or "ALERT".

"distribution"

string - distribution type that is used. One of "WHISPER", "GUILD", or "GROUP".

"person"

string - person to whisper to (only used with "WHISPER").

...

tuple - arguments to pass through.

Notes

• Sends a comm message to the appropriate stream determined by "distribution".
• Priorities are useful for different tasks.

Example

; "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.
MyAddon:SendPrioritizedCommMessage("BULK", "GUILD", "Message", 52, { alpha = "bravo" }) -- sends the values across the guild stream.
MyAddon:SendPrioritizedCommMessage("NORMAL", "WHISPER", "Ckknight", "Here is my message") -- whispers a message to Ckknight.
MyAddon:SendPrioritizedCommMessage("ALERT", "GROUP", "Here is a monkey-related message", 42, "ROGUE") -- Sends to your party/raid/battleground, based on which one you are in.

:SetCommPrefix("prefix")

Arguments

"prefix"

string - Prefix of the addon if you are to send comm messages. Must be 3 bytes.

Notes

• Sets the prefix attached to this addon.
• 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.
• Prefixes must be 3 bytes and should be unique for your addon.

Example

MyAddon:SetCommPrefix("MAd")

:SetDefaultCommPriority("priority")

Arguments

"priority"

string - priority to be used. One of "BULK", "NORMAL", or "ALERT".

Notes

• Sets the default priority for using :SendCommMessage.
• "NORMAL" is the default priority
• Priorities are useful for different tasks.

Example

; "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.
MyAddon:SetDefaultCommPriority("BULK")