SecureHandlers

SecureHandlers is a new set of widget templates provided in Patch 3.0 to enhance addon functionality while in combat lockdown, replacing most variations of SecureStateHeader behavior in 2.0. The templates enable execution of a limited subset of addon code in a restricted but secure environment, allowing addons to perform actions that would normally be impossible.

SecureHandlers are implemented entirely in Lua/XML code, and code is publicly visible as part of FrameXML. The templates are defined in SecureHandlerTemplates.xml, supporting code is in SecureHandlers.lua, and the restricted environment/execution framework is provided by RestrictedExecution.lua, RestrictedFrames.lua, and RestrictedEnvironment.lua files.

Snippets
To add a snippet for a SecureHandler template to call, you should set it as an attribute on the widget inheriting from a SecureHandler template. For example: -- Assume widget is a frame inheriting from SecureHandlerClickTemplate. widget:SetAttribute("_onclick", [=[ -- self, button, down are considered "arguments" to the _onclick handler if button == "RightButton" then   self:Hide;  end ]=]); The  syntax allows you to specify long strings without escaping characters within them.

Snippets can access a limited subset of the World of Warcraft API; they are said to execute in a restricted environment. Limitations include inability to handle native Lua tables (instead resorting to restricted tables and frame references), and lack of direct access to functions (although some control methods can be used to emulate a call stack).

Methods
If widget inherits from a SecureHandler template, you can use the following methods:
 * widget : Execute("codeSnippet") : executes codeSnippet in the restricted environment owned by the widget.
 * widget : WrapScript(frame, "script", "preBody", "postBody") : wraps the specified script handler of an explicitly protected frame with the specified pre and post snippets. The snippets are executed within the widget's restricted environment.
 * widget : UnwrapScript(frame, "script") : returns the outermost wrapped handler for the frame's script handler.
 * widget : SetFrameRef("id", frame) : creates a frame reference that can be accessed inside the restricted environment.