How to find out API version

klaro00 · 10/19/14, 03:03 AM

Hi,

ist there a reliable, robust way to find out the API version under which an addon is running? This would be useful when changing addon code in order to support an upcoming ESO version on the PTS server if the addon should run on both the current and the future API version.

I couldn't find any function like GetAPIversion() or so. Is there any?

I was thinking of writing such a function by examining "typical properties" of a certain API version, such as the existence of a function or a global value, like this:

Lua Code:

function GetAPIVersion()
    if not functionWhichWasRemovedInVersion100010 then
        return 100010
    end
 
    return 100009
end

The shown approach is not very reliable since it checks for existence of a "magic" function which is no longer supported in a certain API version.

Maybe there is a better way? Any ideas?

// Klaro

merlight · 10/19/14, 06:23 AM

IIRC, at some point APIVersion on PTS wasn't even bumped immediately after the API changed, so even if there was GetAPIVersion() function, it wouldn't be 100% reliable.

I believe branching your code on some kind of GetAPIVersion (regardless of whether it's provided by the API or guessed from missing functions) is not the right way to support different APIs. If you need functionWhichWasRemovedInVersion100010, check for it's existence before you call it. Or alternatively, write a safety wrapper which will do the test and provide fallback functionality. Then your add-on will have a chance to function properly without being updated much longer.

The fact that APIVersion>=100010 doesn't mean functionWhichWasRemovedInVersion100010 doesn't exist. An compatibility add-on could provide it. Or the function may be revived in 100012. There is also the possibility of a function changing arguments (which has already happened, and the compatibility tool provided a wrapper that worked with add-ons using either) or returned values (which no compatibility tool can fix, because it can't tell what type of return you want; here you'd have to use your own wrapper that would catch unexpected returns after the call).

Garkin · 10/19/14, 08:49 AM

It's better to check if some new function exists instead:

Lua Code:

function GetAPIVersion()
    if GetLatency ~= nil then
        return 100010
    end
 
    return 100009
end

My Compatibility Tool tries to emulate removed functions, so you can get wrong results.

Warning: Spoiler

CompatibilityTool.lua (version 5A for Update 5):

Lua Code:

if GetBagInfo == nil then
   function GetBagInfo(bagId)
      return "/esoui/art/icons/icon_missing.dds", GetBagSize(bagId)
   end
end
 
if GetShortAllianceName == nil then
   function GetShortAllianceName(alliance)
      return GetAllianceName(alliance)
   end
end
 
KEYBIND_STRIP_FRAGMENT = KEYBIND_STRIP_FRAGMENT or KEYBIND_STRIP_FADE_FRAGMENT
 
local _GetItemArmorType = GetItemArmorType
function GetItemArmorType(arg, ...)
   if type(arg) == "string" then
      return GetItemLinkArmorType(arg, ...)
   else
      return _GetItemArmorType(arg, ...)
   end
end
 
local _GetItemWeaponType = GetItemWeaponType
function GetItemWeaponType(arg, ...)
   if type(arg) == "string" then
      return GetItemLinkWeaponType(arg, ...)
   else
      return _GetItemWeaponType(arg, ...)
   end
end
 
 
--Changed/removed functions in Update 4
local _GetAchievementItemLink = GetAchievementItemLink
function GetAchievementItemLink(arg1, arg2, arg3)
   return _GetAchievementItemLink(arg1, arg3 or arg2)
end
 
if GetAchievementRewardInfo == nil then
   function GetAchievementRewardInfo(achievementId, rewardIndex)
      local rewards = {}
 
      local points = GetAchievementRewardPoints(achievementId)
      table.insert(rewards, {ACHIEVEMENT_REWARD_TYPE_POINTS, points})
 
      local hasRewardItem, itemName, iconTextureName, quality = GetAchievementRewardItem(achievementId)
      if hasRewardItem then
         table.insert(rewards, {ACHIEVEMENT_REWARD_TYPE_ITEM, itemName, iconTextureName, quality})
      end
 
      local hasRewardTitle, titleName = GetAchievementRewardTitle(achievementId)
      if hasRewardTitle then
         table.insert(rewards, {ACHIEVEMENT_REWARD_TYPE_TITLE, titleName})
      end
 
      local hasRewardDye, dyeIndex = GetAchievementRewardDye(achievementId)
      if hasRewardDye then
         table.insert(rewards, {ACHIEVEMENT_REWARD_TYPE_DYE, dyeIndex})
      end
 
      return unpack(rewards[rewardIndex])
   end
end
 
local _IsSmithingStyleKnown = IsSmithingStyleKnown
function IsSmithingStyleKnown(styleItemIndex, patternIndex)
   return _IsSmithingStyleKnown(styleItemIndex, patternIndex or 1)
end
 
GetNumLastCraftingResultItems = GetNumLastCraftingResultItems or GetNumLastCraftingResultItemsAndPenalty
 
 
--Changed/removed functions in Update 5
if not GetNumHeraldryItems then
   GetNumHeraldryItems = GetNumGuildSpecificItems
end
if not GetHeraldryItemInfo then
   GetHeraldryItemInfo = GetGuildSpecificItemInfo
end
if not BuyHeraldryItem then
   BuyHeraldryItem = BuyGuildSpecificItem
end
if not GetHeraldryItemLink then
   GetHeraldryItemLink = GetGuildSpecificItemLink
end
 
local function AddDataTable(control)
   control.data = control.data or setmetatable({}, {__index = control})
end
ZO_PreHook("ZO_OptionsWindow_InitializeControl", AddDataTable)
ZO_PreHook("IsControlAnOption", AddDataTable)
ZO_PreHook("ZO_Options_UpdateOption", AddDataTable)
ZO_PreHook("ZO_Options_SetupSlider", AddDataTable)
ZO_PreHook("ZO_Options_SetupDropdown", AddDataTable)
ZO_PreHook("ZO_Options_SetupCheckBox", AddDataTable)
ZO_PreHook("ZO_Options_OnMouseEnter", function(control)
   AddDataTable(control)
   if (control.tooltipText and control.data.tooltipText == nil) then
      control.data.tooltipText = control.tooltipText
   end
end)
 
if not ZO_OptionsWindow_LoadDefaults then
   ZO_OptionsWindow_LoadDefaults = function()
      KEYBOARD_OPTIONS:LoadDefaults()
   end
end
if not ZO_OptionsWindow_UpdatePanelOptions then
   ZO_OptionsWindow_UpdatePanelOptions = function(panelIndex, saveOptions)
      KEYBOARD_OPTIONS:UpdatePanelOptions(panelIndex, saveOptions)
   end
end
if not ZO_OptionsWindow_UpdateAllPanelOptions then
   ZO_OptionsWindow_UpdateAllPanelOptions = function(saveOptions)
      KEYBOARD_OPTIONS:UpdateAllPanelOptions(saveOptions)
   end
end
if not ZO_OptionsWindow_ChangePanels then
   ZO_OptionsWindow_ChangePanels = function(panel, hooksCall)
      if hooksCall == true then return end
      KEYBOARD_OPTIONS:ChangePanels(panel)
   end
   ZO_PreHook(ZO_SharedOptions, "ChangePanels", function(self, panel) ZO_OptionsWindow_ChangePanels(panel, true) end) --call functions hooked to ZO_OptionsWindow_ChangePanels (works only for pre-hook, but it should be enough)
end
 
 
EVENT_MANAGER:RegisterForEvent("CompatibilityTool", EVENT_ADD_ON_LOADED, function(event, name)
   if (name):find("^ZO_") then return end
   EVENT_MANAGER:UnregisterForEvent("CompatibilityTool", event)
 
   local inventory_mt = {}
   function inventory_mt.__index(self, key)
      if key == "numSlots" then
         return GetBagSize(self.backingBag)
      elseif key == "numUsedSlots" then
         return GetNumBagUsedSlots(self.backingBag)
      end
   end
 
   for i, inventory in pairs(PLAYER_INVENTORY.inventories) do
      setmetatable(inventory, inventory_mt)
   end
end)

klaro00 · 10/19/14, 01:09 PM

Thanks,

so I was right that there is no direct way. I think I will test for new functions like GetLatency (in fact, I currently test for GetMaxLevel). Also thank you Garkin for the list of functions emulating older API functions; might be useful one day...

Cheers,
Klaro00

(Just in case you are interested in my current problem which led me to my questions, here are some details. It's not about missing functions, it's rather about access to the "settings menu" interface via ZO_OptionsWindow_InitializeControl(). ZO changed quite a lot behind the scenes, and kept this function for backward compatibility. But the data structure has been slightly changed by ZO as well, so I needed to do some fixes for 10010 which go beyond missing functions. This is solved, so I'm not asking for help with the settings menu; I'm also aware that there are approches like "LibAddonMenu" on the market... Because I don't want to fork my code to maintain two code versions, I was looking for a cheap way to support the current and the upcoming API version. That's it.)

Garkin · 10/19/14, 02:14 PM

Originally Posted by klaro00

...

(Just in case you are interested in my current problem which led me to my questions, here are some details. It's not about missing functions, it's rather about access to the "settings menu" interface via ZO_OptionsWindow_InitializeControl(). ZO changed quite a lot behind the scenes, and kept this function for backward compatibility. But the data structure has been slightly changed by ZO as well, so I needed to do some fixes for 10010 which go beyond missing functions. This is solved, so I'm not asking for help with the settings menu; I'm also aware that there are approches like "LibAddonMenu" on the market... Because I don't want to fork my code to maintain two code versions, I was looking for a cheap way to support the current and the upcoming API version. That's it.)

This is why my compatibility tool uses function AddDataTable.

For example this is part of the function which creates checkbox in LibAddonMenu-1.0 (works on live server):

Lua Code:

function lam:AddCheckbox(panelID, controlName, text, tooltip, getFunc, setFunc, warning, warningText)
    local isSubMenu = type(panelID) == "userdata"
    local checkbox = wm:CreateControlFromVirtual(controlName, isSubMenu and panelID or optionsWindow, "ZO_Options_Checkbox")
    checkbox:SetAnchor(TOPLEFT, lastAddedControl[panelID], BOTTOMLEFT, 0, 6)
    checkbox.controlType = OPTIONS_CHECKBOX
    checkbox.system = SETTING_TYPE_UI
    checkbox.settingId = _G[strformat("SETTING_%s", controlName)]
    checkbox.panel = isSubMenu and panelID.panel or panelID
    checkbox.text = text
    checkbox.tooltipText = tooltip

This is the same part of the function modified for Update 5 (keys are moved to the "data" table):

Lua Code:

function lam:AddCheckbox(panelID, controlName, text, tooltip, getFunc, setFunc, warning, warningText)
    local isSubMenu = type(panelID) == "userdata"
    local checkbox = wm:CreateControlFromVirtual(controlName, isSubMenu and panelID or optionsWindow, "ZO_Options_Checkbox")
    checkbox:SetAnchor(TOPLEFT, lastAddedControl[panelID], BOTTOMLEFT, 0, 6)
    checkbox.data = {
        controlType = OPTIONS_CHECKBOX,
        system = SETTING_TYPE_UI,
        settingId = _G[strformat("SETTING_%s", controlName)],
        panel = (isSubMenu and panelID.data.panel or panelID),
        text = text,
        tooltipText = tooltip,
    }

If you want it working for both live and PTS, use original function + metatable with __index metamethod:

Lua Code:

function lam:AddCheckbox(panelID, controlName, text, tooltip, getFunc, setFunc, warning, warningText)
    local isSubMenu = type(panelID) == "userdata"
    local checkbox = wm:CreateControlFromVirtual(controlName, isSubMenu and panelID or optionsWindow, "ZO_Options_Checkbox")
    checkbox:SetAnchor(TOPLEFT, lastAddedControl[panelID], BOTTOMLEFT, 0, 6)
    checkbox.controlType = OPTIONS_CHECKBOX
    checkbox.system = SETTING_TYPE_UI
    checkbox.settingId = _G[strformat("SETTING_%s", controlName)]
    checkbox.panel = isSubMenu and panelID.panel or panelID
    checkbox.text = text
    checkbox.tooltipText = tooltip
 
    checkbox.data = setmetatable({}, {__index = checkbox}) --this is what it makes compatible with Update 5

If key doesn't exist in the checkbox.data table, it will look for metamethod __index. If __index is a function, it will return value from the function. If __index is a table, it will return key from that table. I.e. calling d(checkbox.data.tooltipText) will give the same result as calling d(checkbox.tooltipText).
(A bit more about metatables: http://nova-fusion.com/2011/06/30/lu...bles-tutorial/)

ZOS_ChipHilseberg · 10/21/14, 09:12 AM

I quickly threw in a GetAPIVersion function to make this easier in the future.

Halja · 10/21/14, 10:11 AM

Originally Posted by ZOS_ChipHilseberg

I quickly threw in a GetAPIVersion function to make this easier in the future.

Thank you Chip! Will that make it to 1.5.x or a bit more down the road like 1.6?

klaro00 · 10/21/14, 12:11 PM

Originally Posted by ZOS_ChipHilseberg

I quickly threw in a GetAPIVersion function to make this easier in the future.

Great news!

ZOS_ChipHilseberg · 10/21/14, 04:04 PM

It's likely to be in 1.5.

katkat42 · 10/21/14, 07:07 PM

Originally Posted by ZOS_ChipHilseberg

It's likely to be in 1.5.

Wow, sweet! Thank you, Chip!

Fyrakin · 10/21/14, 11:31 PM

Good one