Skip to content

Latest commit

 

History

History
159 lines (101 loc) · 3.52 KB

API.md

File metadata and controls

159 lines (101 loc) · 3.52 KB

GreenWall API Reference

Purpose

Initially, it was hoped that GreenWall could be extended to bridge standard add-on messages. However, the WoW API doesn't have a function similar to ChatFrame_MessageEventHandler that could be used for add-on messages.

So this simple messaging API is provided for third-party add-on developers who would like to be able to use the bridged communication on a guild confederation.

A simple example, which demonstrates the use of the API, is GWSonar.

Safety First

Before any API functions are called, there are tests that should be run to verify the environment.

Individual API checks

Check that GreenWall is loaded

if C_AddOns.IsAddOnLoaded('GreenWall') then
	...
end

Check that the API is supported

if GreenWallAPI ~= nil then
    ...
end

Check the API version

if GreenWallAPI >= 1 then
    ...
end

Unified API check

This combines all of the tests into one function.

function apiAvailable()
    function testAPI()
        -- Raises and exception of GreenWall is loaded or is pre-1.7.
        assert(C_AddOns.IsAddOnLoaded('GreenWall'))
        return GreenWallAPI.version
	end
    
	-- Catch any exceptions
	local found, version = pcall(testAPI)

	return found and version >= 1
end

Sending a Message

To send a message to other instances of the add-on, use the following function.

GreenWallAPI.SendMessage(addon, message)

Arguments:

  • addon - The addon name, should the one used for the name of the TOC file.
  • message - The message to send. Accepts 8-bit data.

Receiving a Message

The receiving of messages is handled with callbacks.

1. Create the callback

local function handler(addon, sender, message, echo, guild)

Arguments:

  • addon - The name of the addon sending the message.
  • sender - The player sending the message.
  • message - The text of the message.
  • echo - Set to true if the message was sent by the player.
  • guild - Set to true if the message originated in the player's co-guild.

2. Add the handler to the dispatch table

local id = GreenWallAPI.AddMessageHandler(handler, addon, priority)

Arguments:

  • handler - The callback function.
  • addon - The name of the addon that you want to receive messages from (the same one used for the name of the TOC file). If the value '*' is supplied, messages from all addons will be handled.
  • priority - A signed integer indicating relative priority, lower value is handled first. The default is 0.

Returns:

  • The ID that can be used to remove the handler.

Dispatch Table

In addition to the GreenWallAPI.AddMessageHandler function to add a handler, the following functions are available to manage the dispatch table.

Remove a handler

local found = GreenWallAPI.RemoveMessageHandler(id)

Arguments:

  • handler_id - The ID of the handler function.

Clear one or more handlers

GreenWallAPI.ClearMessageHandlers(addon)

Arguments:

  • addon - (Optional) A tag defining the name of the add-on messages will be received from. The * character can be used to match all add-ons. If this value is nil, all entries will be cleared.

Note: A * value passed as add-on is not a wildcard in this context, it will only matched instances where the handler was installed with * as the add-on.

Get channel information

Query the hidden channels used by Greenwall.

GreenWallAPI.GetChannelNumbers()

Returns:

  • An array of integer values for the channels in use.