Interface Protocol

João Cardoso edited this page Oct 17, 2017 · 14 revisions

If your addon stores character or guild item data, it can share it through LibItemCache. This is done by declaring an interface, which is a LibStub library that implements a couple of methods. The advantage of this approach is that your addon won't need to include LibItemCache nor to be aware of it.

Here is a simple example of an interface:

local interface = LibStub:NewLibrary('MyItemCacheInterface', 1)
interface.IsItemCache = true

function interface:GetGuildItem(realm, guild, tab, slot)
    return {id = 6948} -- always return an hearthstone
end 

:bulb: An interface does not need to implement all of the protocol methods. LibItemCache will seamlessly use any number of methods you declare, and look for other implementations in other interfaces of the ones you do not.

:warning: The field IsItemCache needs to be set to true. This will inform LibItemCache to search this library for the protocol methods.

Protocol Methods

The following is a list of the methods that LibItemCache will use if found in an interface.

Players

:GetPlayer(realm, player)

Takes in a realm name and the name of a character. Must return an owner data structure or nil. The structure does not need to declare all the fields as LibItemCache will complete fields, such as cached or isguild, as best as it can.

:GetBag(realm, player, bagID)

Takes in a realm name, the name of a character and a bag slot ID. Must return a bag data structure or nil. In the case of customizable container slots, the field link can be nil, an incomplete hyperlink or even an incomplete item string. LibItemCache will then use either the link or id fields to reconstruct information about the container item.

:GetItem(realm, player, bag, slot)

Takes in a realm name, the name of a character, a bag slot ID and the item slot number. Must return an item data structure or nil. Just as above, information can be reconstructed from an incomplete link.

:GetEquipment(realm, player, slot)

Just as :GetItem, but expects item data regarding a character's equipment slot.

:GetVoidItem(realm, player, slot)

Just as :GetItem, but expects item data regarding a character's void storage.

:GetPlayers(realm)

Takes in a realm name. Must return a stateless iterator over the playable characters in that realm or nil.

Guilds

The protocol for guilds mirrors very closely the one for players described above.

:GetGuild(realm, name)

Same as :GetPlayer, but takes in a guild name instead one of a player.

:GetGuildTab(realm, guild, tabID)

Same as :GetBag, but takes in a guild name and a guild tab ID instead of of a character name and a bag ID. Expects bag data regarding the guild bank tab.

:GetGuildItem(realm, guild, tab, slot)

Same as :GetItem, but takes in a guild name and a guild tab ID instead of of a character name and a bag ID. Expects item data regarding the guild bank item slot.

:GetGuilds(realm)

Takes in a realm name. Must return a stateless iterator over the known guilds in that realm or nil.

LibItemCache :floppy_disk:

Using the Library
API
Data Specification
Advanced Uses

Exposing your Cache
Interface Protocol

Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.