API.lua

--[[-----------------------------------------------------------------------

An API for guild chat bridging as a transport

--]]-----------------------------------------------------------------------

--
-- Global to expose API
--
GreenWallAPI = {
    version = 1,
}


--- Send a message to the guild confederation.
-- @param addon The addon name (the same one used for the name of the TOC
--  file).
-- @param message The message to send. Accepts 8-bit data.
function GreenWallAPI.SendMessage(addon, message)
    -- Validate addon id
    assert(addon == C_AddOns.GetAddOnInfo(addon))
    gw.config.channel.guild:send(GW_MTYPE_EXTERNAL, addon, message)
end


--- Insert a handler for addon messages from the guild confederation.
-- @param handler A callback function.
-- @param 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.
-- @param priority A signed integer indicating relative priority, lower value
--  is handled first.  The default is 0.
-- @return The ID that can be used to remove the handler.
function GreenWallAPI.AddMessageHandler(handler, addon, priority)
    local function generate_id(handler)
        local count = 0
        for _, e in ipairs(gw.api_table) do
            if handler == e[4] then
                count = count + 1
            end
        end
        return string.format('%s:%04X', tostring(handler), count)
    end

    -- Validate the arguments
    assert(priority % 1 == 0)
    if addon ~= '*' then
        assert(addon == C_AddOns.GetAddOnInfo(addon))
    end

    local id = generate_id(handler)
    gw.Debug(GW_LOG_INFO, 'add API handler; id=%s, addon=%s, priority=%d', id, addon, priority)

    table.insert(gw.api_table, { id, addon, priority, handler })
    table.sort(gw.api_table, function(a, b)
        return a[2] < b[2]
    end)

    return id
end


--- Remove an addon message handler.
-- @param id The ID of the callback function to remove.
-- @return True if a matching handler is found, false otherwise.
function GreenWallAPI.RemoveMessageHandler(id)
    for i, e in ipairs(gw.api_table) do
        if id == e[1] then
            gw.Debug(GW_LOG_INFO, 'remove API handler; id=%s, addon=%s, priority=%d', e[1], e[2], e[3])
            table.remove(gw.api_table, i)
            return true
        end
    end
    return false
end


--- Clear our portions or all of the dispatch table entries.
-- @param addon Optional identifier for the addon or '*'.  If nil,
--  all table entries will be removed.
--
-- Note: A '*' value passed as addon is not a wildcard in this context,
-- it will only match instances where the handler was installed with
-- '*' as the addon.
function GreenWallAPI.ClearMessageHandlers(addon)
    if addon == nil then
        gw.Debug(GW_LOG_INFO, 'remove all API handlers')
        gw.api_table = {}
    else
        if addon ~= '*' then
            assert(addon == C_AddOns.GetAddOnInfo(addon))
        end
        for i = #gw.api_table, 1, -1 do
            local e = gw.api_table[i]
            if addon == e[2] then
                gw.Debug(GW_LOG_INFO, 'remove API handler; id=%s, addon=%s, priority=%d', e[1], e[2], e[3])
                table.remove(gw.api_table, i)
            end
        end
    end
end


--- Query the hidden channels used by Greenwall.
-- @return An array of integer values for the channels in use.
function GreenWallAPI.GetChannelNumbers()
    local rv = {}
    if gw.config.channel.guild ~= nil then
        table.insert(rv, gw.config.channel.guild.number)
    end
    if gw.config.channel.officer ~= nil then
        table.insert(rv, gw.config.channel.officer.number)
    end
    return rv
end

--- The API handler dispatcher
-- @param addon The sending addon
-- @param sender The sending player
-- @param guild_id Originating co-guild
-- @param message The message contents
function gw.APIDispatcher(addon, sender, guild_id, message)
    local echo = sender == gw.player
    local guild = guild_id == gw.config.guild_id
    for _, e in ipairs(gw.api_table) do
        if addon == e[2] or addon == '*' then
            gw.Debug(GW_LOG_INFO, 'dispatch API handler; id=%s, addon=%s, priority=%d', e[1], e[2], e[3])
            e[4](addon, sender, message, echo, guild)
        end
    end
end