WoW:API hooksecurefunc

Reference e
AddOns WoW API Widget API XML UI Event API WoW Lua Macro API CVars Battle.net HOWTOs Snippets UI tech Categories

→ WoW API

← WoW API < hooksecurefunc

Creates a secure 'post hook' for the named function. Your hook will be called with the same arguments, but will not be able to affect the outcome of the original call.

hooksecurefunc([table,] "functionName", hookfunc)

Parameters

Arguments

table

Optional Table - if you're hooking a function on an object, provide a reference to the object.

functionName

String - the name of the function being hooked.

hookfunc

Function - your hook function.

Example

local echoHook = function (...) 
 local msg = "";
 for k,v in pairs({...}) do msg = msg .. k .. "=[" .. tostring(v) .."] "; end;
 DEFAULT_CHAT_FRAME:AddMessage("[Echo] " .. msg);
end;
hooksecurefunc("CastSpellByName", echoHook); -- Hooks the global CastSpellByName
hooksecurefunc(GameTooltip, "SetUnitBuff", echoHook); -- Hooks GameTooltip.SetUnitBuff

Result

Hooks CastSpellByName and GameTooltip.SetUnitBuff without compromising their secure status. When those functions are called, prints their argument list into the default chat frame.

Notes

This is the only safe way to hook functions that execute protected functionality.

The hookfunc is invoked after the original function, and receives the same parameters; return values from hookfunc are discarded.

You can only hook a global function using this function.

If another addon, or the same addon, replaces functionName after you use this function to hook it, hookfunc will no longer fire.

hooksecurefunc("ToggleBackpack", function(...)
    print("ToggleBackpack called.")
end)
ToggleBackpack = function(...)
    -- Do something different
end
ToggleBackpack() -- "ToggleBackpack called." never prints.

After hooksecurefunc() is used on a function, setfenv() throws an error when attempted on that function

You cannot "unhook" a function that is hooked with this function except by a UI reload.

-- this doesn't work as expected

-- Make SetItemRef output the item to the chat frame
hooksecurefunc('SetItemRef', function(item)
    ChatFrame1:AddMessage(item)
)

-- unhook, maybe. I don't think do. It produces an error and SetItemRef() still prints to the chat frame.
-- Error: "hooksecurefunc('SetItemRef', nil)...":1: Usage: hooksecurefunc([table,] "function", hookfunc)
hooksecurefunc('SetItemRef', nil)

-- change the hook? Nope. No error, but SetItemRef() still prints to the chat frame and then the item is saved to MySavedVariable.
hooksecurefunc('SetItemRef', function(item)
    MySavedVariable = item
)