RegisterCallback() [v1.0.47+]

创建机器码地址，当它被调用时会重定向到脚本中的函数。

Address := RegisterCallback("FunctionName" [, Options = "", ParamCount = FormalCount, EventInfo = Address])

参数

Address

成功时，RegisterCallback() 返回一个数值地址，它可以被 DllCall() 或其他能调用机器码函数的东西调用。失败时, 它返回空字符串. 当 FunctionName 出现下列情况时会引起失败：1) 不存在；2) 接收到比 ParamCount 过多或过少的参数；或 3) 接收到任何一个 ByRef 参数。

FunctionName

函数 名, 如果是原义的字符串, 则必须包围在双引号中. 每当调用 Address 时会自动调用此函数. 此函数同时会接收到传递给 Address 的参数.

[v1.1.06+]: 可以传递 函数引用 来代替函数名.

选项

指定零个或多个下列单词. 在选项间使用空格分隔（例如C Fast）。

Fast 或 F: 避免每次调用 FunctionName 时都启动新 线程. 尽管这样执行的更好, 但必须避免调用 Address 的线程发生变化 (例如当回调函数被传入的消息触发时). 这是因为 FunctionName 能改变在它被调用时刚好在运行的线程的全局设置 (例如 ErrorLevel, A_LastError 和 上次找到的窗口). 想了解更多细节, 请参阅 备注.

CDecl 或 C：让 Address 遵循“C”调用约定。此选项通常省略, 因为在回调函数中标准调用约定更常用.

ParamCount

Address 的调用者会传递给它的参数数目. 如果完全省略, 则它默认为 FunctionName 的 定义 中强制参数的数目. 在这两种情况中, 必须确保调用者准确传递此数目的参数.

EventInfo

每当通过此 Address 调用 FunctionName 时, 它将在 A_EventInfo 中看到这个整数. 这可用于一个 FunctionName 同时被多个 Address 调用时. 如果省略, 则它默认为 Address. 注: 与其他全局设置不同, 当前线程 的 A_EventInfo 不会受到 快速模式 的干扰.

如果运行当前脚本的主程序为 32 位, 那么此参数必须介于 0 和 4294967295 之间. 如果主程序为 64 位, 那么此参数可以为 64 位整数. 尽管 A_EventInfo 通常返回无符号整数, 但由于 AutoHotkey 不完全支持 64 位无符号整数, 因此对这个值进行某些操作可能让它溢出从而进入有符号整数的范围.

回调函数的参数

分配了回调地址的 函数 可以接受多达 31 个参数. 允许有 可选参数, 这可用于函数被多个调用者调用时.

32 位: 所有传入参数都是 32 位无符号整数. 如果某个传入参数应该为有符号整数, 则可以参照下面的其中一个例子得到负数:

; 方法 #1
if wParam > 0x7FFFFFFF
    wParam := -(~wParam) - 1

; 方法 #2: 依赖于 AutoHotkey 原生使用 64 位有符号整数的事实.
wParam := wParam << 32 >> 32

64 位: 所有传入参数都是 64 位有符号整数. AutoHotkey 没有对 64 位无符号整数的原生支持.

如果某个传入参数应该为字符串, 那么它实际接收的是这个字符串的地址. 要获取这样的字符串, 请使用 StrGet:

MyString := StrGet(MyParameter)  ; AHK_L 46+

如果某个传入参数为结构的地址, 则可以参照 DllCall 结构 中描述的步骤提取其中的各个成员.

[AHK_L 60+]: 如果函数声明为 可变参数的, 那么它的最后一个参数被赋值为首个没有赋值给脚本参数的回调参数 地址. 例如：

callback := RegisterCallback("Func", "F", 1)  ; 不必指定参数数目.
Func("Func was called directly.")  ; 直接调用 Func.
DllCall(callback, float, 10.5)  ; 通过回调调用 Func.
Func(params*) {
    if IsObject(params)
        MsgBox % params[1]
    else
        MsgBox % NumGet(params+0, 0, "float")
}

大部分回调使用 stdcall 调用约定, 这种方式需要固定的参数数目. 在大多数情况中, 在创建回调时必须指定 ParamCount. 在 64 位版本或 32 位版本的 Cdecl 回调中, ParamCount 可以省略, 此时所有可选参数接收它们的默认值且在计算保存在 params 中的地址时被忽略.

函数应该 返回 什么

如果函数使用不带任何参数的 Return, 或指定空值如 "" (甚至从不使用 Return), 则返回 0 给 Address 的调用者. 否则, 函数应该返回一个介于 -2147483648 和 4294967295 之间的整数, 它会被返回给 Address 的调用者.

快速与慢速

默认/慢速的模式会让函数以设置的默认值启动, 例如 SendMode 和 DetectHiddenWindows. 这些默认值可以在 自动执行段 改变.

与之相比, 快速模式 会继承在调用函数时刚好在运行的 线程 的全局设置. 而且, 函数对全局设置的任何修改 (包括 ErrorLevel 和 上次找到的窗口) 都会在 当前线程 生效. 因此, 快速模式应该只在确切知道函数会被哪个线程调用时才使用.

要避免被自己 (或其他任何线程) 中断, 回调函数可以在它的首行使用 Critical. 然而, 通过小于 0x312 消息达到的间接调用函数时, 这并不是完全有效的 (增加 Critical 的 间隔 也许有帮助). 而且, Critical 不会阻止执行一些可能导致间接调用它自己的动作, 例如调用 SendMessage 或 DllCall.

内存

每次使用 RegisterCallback() 都会分配少量的内存 (32 字节加上系统开销). 由于当脚本退出时操作系统会自动释放这些内存, 所以任何分配少量 固定 数目的回调的脚本不需要明确地释放内存. 与之相比, 调用 RegisterCallback() 不确定/无限制次数的脚本应明确对任何不使用的回调执行下列操作:

DllCall("GlobalFree", "Ptr", Address, "Ptr")

相关

DllCall(), OnMessage(), OnExit, OnClipboardChange, Sort 的回调, Critical, Post/SendMessage, 函数, Windows 消息列表, 线程

示例

; 示例: 下面是个可运行脚本, 它显示了所有顶层窗口的摘要.

; 考虑到性能和内存的保持, 只为指定的回调调用一次 RegisterCallback():
if not EnumAddress  ; 由于只能从这个线程调用, 所以可以使用快速模式:
    EnumAddress := RegisterCallback("EnumWindowsProc", "Fast")

DetectHiddenWindows On  ; 由于是快速模式, 所以此设置也会在回调中生效.

; 把控制传给 EnumWindows(), 它会重复调用回调:
DllCall("EnumWindows", Ptr, EnumAddress, Ptr, 0)
MsgBox %Output%  ; 显示由回调收集的信息.
    
EnumWindowsProc(hwnd, lParam)
{
    global Output
    WinGetTitle, title, ahk_id %hwnd%
    WinGetClass, class, ahk_id %hwnd%
    if title
        Output .= "HWND: " . hwnd . "`tTitle: " . title . "`tClass: " . class . "`n"
    return true  ; 告知 EnumWindows() 继续执行, 一直到枚举完所有的窗口.
}

; 示例: 下面是个可运行脚本, 它演示了如何在脚本中通过把 GUI 窗口的
; WindowProc 重定向到新的 WindowProc 来子类化窗口. 此时, 文本控件的
; 背景颜色被改变为自定义颜色.

TextBackgroundColor := 0xFFBBBB  ; BGR 格式的自定义颜色.
TextBackgroundBrush := DllCall("CreateSolidBrush", UInt, TextBackgroundColor)

Gui, Add, Text, HwndMyTextHwnd, Here is some text that is given`na custom background color.
Gui +LastFound
GuiHwnd := WinExist()

; 64 位脚本必须调用 SetWindowLongPtr 代替 SetWindowLong:
SetWindowLong := A_PtrSize=8 ? "SetWindowLongPtr" : "SetWindowLong"

WindowProcNew := RegisterCallback("WindowProc", ""  ; 指定 "" 来避免子类化中使用快速模式.
    , 4, MyTextHwnd)  ; 使用了 EventInfo 参数时必须明确指定 ParamCount.
WindowProcOld := DllCall(SetWindowLong, Ptr, GuiHwnd, Int, -4  ; -4 是 GWL_WNDPROC
    , Ptr, WindowProcNew, Ptr) ; 返回值必须设置为 Ptr 或 UPtr 而不是 Int.

Gui Show
return

WindowProc(hwnd, uMsg, wParam, lParam)
{
    Critical
    global TextBackgroundColor, TextBackgroundBrush, WindowProcOld
    if (uMsg = 0x138 && lParam = A_EventInfo)  ; 0x138 为 WM_CTLCOLORSTATIC.
    {
        DllCall("SetBkColor", Ptr, wParam, UInt, TextBackgroundColor)
        return TextBackgroundBrush  ; 返回 HBRUSH 来通知操作系统我们改变了 HDC.
    }
    ; 否则 (如果上面没有返回), 传递所有的未处理事件到原来的 WindowProc.
    return DllCall("CallWindowProc", Ptr, WindowProcOld, Ptr, hwnd, UInt, uMsg, Ptr, wParam, Ptr, lParam)
}

GuiClose:
ExitApp