Using the Inter-Guild Link API
The very easiest way to use the Inter-Guild Link API is via a bridging AddOn, which is an AddOn that sits between Inter-Guild Link and some other AddOn that should receive allied guild messages and events so that it can work seamlessly well in guild alliance scenarios. For the purposes of a brief example, a fictitious bridging AddOn named BridgingAddOn will be created to sit between Inter-Guild Link and another fictitious major AddOn named MajorAddOn. We will pretend that MajorAddOn is already fully functional in isolated guild scenarios (unaware of any guild alliances) and that it is a chat-based AddOn that keeps its own internal cache of the local guild roster (so that it can add character locations to chat messages if -- for example -- the player moves the mouse pointer over the chatter's name) and which displays guild messages in a unique way outside the standard chat frames.

In this scenario, the MajorAddOn will suffer two key problems in a guild alliance scenario:
  1. It will be unaware of guild and officer chat messages from allied guild members and -- in most cases -- will fail to display any allied guild messages to the user in its own way
  2. Its internal guild roster cache will be out of synch with allied guild roster changes and -- in most cases -- will only display local guild members because it will populate its cache only once and usually before Inter-Guild Link can establish any links

To fix these key issues, we will pretend to develop BridgingAddOn, which will fool MajorAddOn into presenting allied chat messages and event notices (like Achievements) as if they came from the local guild.


MajorAddOn Review
In reviewing the fictitious MajorAddOn source code, we find the functions that need to be "hooked" in order to push allied chat messages and event notices into its output:
  • It generates its internal cache of guild member names and locations using an internal, public function named ScanGuildRoster()
  • It prints guild chat messages using an internal, public function named PrintGuildChat(ChatMessage, SenderName)
  • It prints guild officer chat messages using an internal, public function named PrintOfficerChat(ChatMessage, SenderName)
  • It prints achievement notices to the default (General) chat frame using an internal, public function named PrintAchievement(AchievementMessage, EarnedByName)

We also notice that in all usages of these three key functions, they are used as class method calls in the form of MajorAddOn:FunctionName(...), so we will note that we must simulate these class method calls later by converting the syntax to its equivalent form MajorAddOn.FunctionName(MajorAddOn, ...).


BridgingAddOn Code
Our fictitious BridgingAddOn will be comprised of just two files:
  1. BridgingAddOn.toc (the Table of Contents file)
  2. BridgingAddOn.lua (the primary source code file)


BridgingAddOn.toc
We will use the simple TOC Dependency technique to access both the Inter-Guild Link API and the key functions of MajorAddOn. To this end, the TOC file contents will look similar to the following:
Code:
## Interface: 40000
## Title: Inter-Guild Link to MajorAddOn Bridge
## Author: John Q. Public
## Version: 0.0.1
## Notes: Enables MajorAddOn to receive allied guild messages and events from allied guilds through Inter-Guild Link.
## RequiredDeps: InterGuildLink, MajorAddOn
BridgingAddOn.lua

BridgingAddOn.lua -- Without Suppression
This contrived example can be solved with very simple code. The following code would work under this fictitious scenario, but it is written for brevity and is not "good" code. When you write your own such AddOn, please practice better error handling, structure, and style. The simplified code follows:
Code:
--[[ BridgingAddOn.lua ]]
-- Begin by obtaining handles to the key functions found in MajorAddOn (mao):
local maoScanGuildRoster=MajorAddOn.ScanGuildRoster;
local maoPrintGuildChat=MajorAddOn.PrintGuildChat;
local maoPrintOfficerChat=MajorAddOn.PrintOfficerChat;
local maoPrintAchievement=MajorAddOn.PrintAchievement;
-- Next, write a function that will receive all the types of chat message and
-- events from allied guild members via Inter-Guild Link that are supported
-- by MajorAddOn:
local function BridgeEvent(EventIdentifier, SourceGuild, ...)
	local showGuildName=IGLInterop.IsShowingGuildNamesInChat();
	if (EventIdentifier == IGLAPIConstants.WOW_EVENT_GUILD_ROSTER_UPDATE) then
		-- MajorAddOn only cares about names and locations, so we want all
		-- roster change types
		maoScanGuildRoster(MajorAddOn);
	elseif (EventIdentifier == IGLAPIConstants.WOW_EVENT_CHAT_MSG_GUILD) then
		local SenderName, ChatMessage=...; -- Extract expected values
		if (showGuildName) then
			ChatMessage=[" .. SourceGuild .. ] " .. ChatMessage;
		end;
		maoPrintGuildChat(MajorAddOn, ChatMessage, SenderName);
	elseif (EventIdentifier == IGLAPIConstants.WOW_EVENT_CHAT_MSG_OFFICER) then
		local SenderName, ChatMessage=...; -- Extract expected values
		if (showGuildName) then
			ChatMessage=[" .. SourceGuild .. ] " .. ChatMessage;
		end;
		maoPrintOfficerChat(MajorAddOn, ChatMessage, SenderName);
	elseif (EventIdentifier == IGLAPIConstants.WOW_EVENT_CHAT_MSG_GUILD_ACHIEVEMENT) then
		local SenderName, AchievementMessage=...; -- Extract expected values
		if (showGuildName) then
			AchievementMessage=AchievementMessage .. " from ";
		end;
		maoPrintAchievement(MajorAddOn, AchievementMessage, SenderName);
	end;
end;
-- Finally, register with the Inter-Guild Link API to receive the desired events
IGLInterop.RegisterAllyEventListener("BridgingAddOn"
	, {	IGLAPIConstants.WOW_EVENT_GUILD_ROSTER_UPDATE
		, IGLAPIConstants.WOW_EVENT_CHAT_MSG_GUILD
		, IGLAPIConstants.WOW_EVENT_CHAT_MSG_OFFICER
		, IGLAPIConstants.WOW_EVENT_CHAT_MSG_GUILD_ACHIEVEMENT
	}
	, BridgeEvent
);
That's it! Save the two files into a new .\Interface\AddOns\BridgingAddOn\ directory, restart the World of Warcraft client, and you're good to go. MajorAddOn will appear to be seamlessly accepting the registered allied guild messages and events.


BridgingAddOn.lua -- With Suppression
If you need to prevent Inter-Guild Link from also displaying the allied guild and officer chat messages (so that only MajorAddOn shows the chat messages), you would modify BridgingAddOn.lua as follows:
Code:
--[[ BridgingAddOn.lua ]]
-- Begin by obtaining handles to the key functions found in MajorAddOn (mao):
local maoScanGuildRoster=MajorAddOn.ScanGuildRoster;
local maoPrintGuildChat=MajorAddOn.PrintGuildChat;
local maoPrintOfficerChat=MajorAddOn.PrintOfficerChat;
local maoPrintAchievement=MajorAddOn.PrintAchievement;
-- Next, write a function that will receive the non-chat events from allied
-- guild members via Inter-Guild Link that are supported by MajorAddOn:
local function BridgeEvent(EventIdentifier, SourceGuild, ...)
	local showGuildName=IGLInterop.IsShowingGuildNamesInChat();
	if (EventIdentifier == IGLAPIConstants.WOW_EVENT_GUILD_ROSTER_UPDATE) then
		-- MajorAddOn only cares about names and locations, so we want all
		-- roster change types
		maoScanGuildRoster();
	elseif (EventIdentifier == IGLAPIConstants.WOW_EVENT_CHAT_MSG_GUILD_ACHIEVEMENT) then
		local SenderName, AchievementMessage=...; -- Extract expected values
		if (showGuildName) then
			AchievementMessage=AchievementMessage .. " from ";
		end;
		maoPrintAchievement(AchievementMessage, SenderName);
	end;
end;
-- Then, write a function that will recieve guild chat messages and suppress
-- Inter-Guild Link from also writing them to the screen
local function FilterAlliedChat(ChatType, SourceGuild, SenderName, ChatMessage, ...)
	if (IGLInterop.IsShowingGuildNamesInChat()) then
		ChatMessage=[" .. SourceGuild .. ] " .. ChatMessage;
	end;
	if (ChatType == IGLAPIConstants.WOW_CHATTYPE_OFFICER) then
		maoPrintOfficerChat(MajorAddOn, ChatMessage, SenderName);
	else
		maoPrintGuildChat(MajorAddOn, ChatMessage, SenderName);
	end;
	return (true);
end;
-- Finally, register with the Inter-Guild Link API to receive the desired events
IGLInterop.RegisterAllyEventListener("BridgingAddOn", IGLAPIConstants.WOW_EVENT_GUILD_ROSTER_UPDATE, BridgeEvent);
IGLInterop.RegisterAllyEventListener("BridgingAddOn", IGLAPIConstants.WOW_EVENT_CHAT_MSG_GUILD_ACHIEVEMENT, BridgeEvent);
IGLInterop.RegisterAllyChatMessageFilter("BridgingAddOn", IGLAPIConstants.WOW_CHATTYPE_GUILD, FilterAlliedChat);
IGLInterop.RegisterAllyChatMessageFilter("BridgingAddOn", IGLAPIConstants.WOW_CHATTYPE_OFFICER, FilterAlliedChat);
And that's it! With this modified version of the primary source code file, MajorAddOn will continue to appear to be seamlessly integrated with both local and allied chat and events, but allied guild chat and allied officer messages won't be appearing in two places on the screen at once.