# RegisterCallback() [v1.0.47+]

创建一个机器码地址(machine-code address)。当它被调用时，会将调用重定向至脚本中的一个 函数 。

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

#### 参数

Address | 若成功，RegisterCallback() 返回一个数值地址(numeric address)，可以被 DllCall() 或任何有能力调用机器码函数的其他东西调用。若失败，会返回一个空字符串。失败的原因是当 FunctionName: 1) 不存在； 2) ParamCount 接受太多或太少的参数；或 3) 接受任何的 ByRef 参数.
FunctionName | 一个 函数 的名字，如果是一个原意的(literal)字符串，必须用引号引起来。只要 Address 被调用，这个函数就会被自动调用。函数还会接收到传给 Address 的参数。
Options | 指定下列中零个或更多个单词。用空格隔开每一个选项（例如 "C Fast"）。 Fast 或 F: 避免每次 FunctionName 被调用时创建新 线程 。 这会提升效率，但必须避免调用 Address 的线程发生变化 （例如：当回调函数被新来的消息触发）. 这是因为 FunctionName 被调用时可以为每一个即将运行的线程改变全局设置如 ErrorLevel, A_LastError，还有 上一次找到的窗口。要获得更多信息，参见 注意事项. CDecl 或 C ：让 Address 遵守 "C" 调用约定。此选项通常省略，因为标准调用约定更常用于回调函数。
ParamCount | Address 的调用者将传递的参数数量。如果全部省略，默认为 FunctionName 函数定义 中 强制参数(mandatory parameters) 的数量。无论如何都要确保调用者会确切地传递此数量的参数。
EventInfo | 一个 0 与 4294967295 之间的整数。只要 FunctionName 是通过这个 Address 被调用的， 它就可以在 A_EventInfo 中看到。当 FunctionName 是通过多个 Address 被调用时这是很有用的。如果省略，默认为 Address。注释：与其他全局设置不同，当前线程的 A_EventInfo 不会被 fast mode 打乱。

#### 回调函数的参数

一个分配了回调地址的 函数 最多可接受 31 个参数。允许有 可选参数 ，当函数被多个调用者调用时这是很有用的。

所有 传入参数(incoming parameters) 都必须是一个 0 到 4294967295 之间的整数。如果一个传入参数应该是有符号的，以下例子可以展现任何的负值：

    if wParam > 0x7FFFFFFF
        wParam := -(~wParam) - 1

如果一个传入参数应该是一个字符串，可以通过复制这个字符串来接收。例如：

    VarSetCapacity(MyString, DllCall("lstrlen", UInt, MyParameter))  ; 如果MyString已经足够大，则不必如此。
    DllCall("lstrcpy", Str, MyString, UInt, MyParameter)  ; 复制字符串到脚本的 MyString 变量。
    VarSetCapacity(MyString, -1)  ; 更新内部存储的变量长度以反映出新内容。

如果一个传入参数是结构体的地址，参照 DllCall 结构体 中的步骤可以展开其内部成员。

#### 函数应该 返回 什么

如果函数使用不带参数的 Return，或者指定了一个空值例如 "" （或者根本不使用 Return）， 0 将被返回给 Address 的调用者。否则，函数应该返回一个 -2147483648 与 4294967295 之间的整数，它将会被返回给 Address 的调用者。

#### 快速模式与慢速模式(Fast vs. Slow)

默认/慢速 模式(default/slow mode) 让函数全新地以设置（比如 SendMode 和 DetectHiddenWindows）的默认值启动。这些默认值可以在 自动执行部分 中被修改。

相比之下，快速模式(fast mode) 在函数被调用时会从任何即将运行的 线程 上继承全局设置。而且，函数对全局设置的任何修改（包括 ErrorLevel 和 上一次找到的窗口） 都将在 当前线程 中生效。因此，快速模式应该只在确切地知道函数会被哪个线程调用的情况下才去使用。

要避免被自己（或任何其他的线程）中断，一个回调函数可以在第一行使用 Critical。然而，当函数因小于 0x312 的消息的到来而被间接调用时，这并不是完全有效的 (增加 Critical 的 interval(时间间隔) 可能有帮助)。而且， Critical 不会阻止函数做一些可能引起调用它自己的事，如调用 SendMessage 或 DllCall。

#### 内存

每次使用 RegisterCallback() 会分配少量的内存 (32 个字节加上系统开销)。由于在脚本退出时操作系统会自动释放这段内存，任何分配数量少而固定的回调地址的脚本无须显式地释放内存。相比之下，一个调用 RegisterCallback() 次数 不确定/无限 的脚本应该显式地对任何不再需要的回调地址调用以下函数： DllCall("GlobalFree", UInt, Address)

#### 相关命令

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

#### 示例

    ; 示例：下面是一个可用脚本，显示所有顶层窗口的摘要。

    ; 为了提升性能和保护内存，只为一个回调地址调用一次 RegisterCallback() ：
    if not EnumAddress  ; 可以用快速模式，因为它只会被这个线程调用：
        EnumAddress := RegisterCallback("EnumWindowsProc", "Fast")

    DetectHiddenWindows On  ; 由于是快速模式，这个设置也会在回调函数中生效。

    ; 将控制权交给 EnumWindows()，它会反复调用回调函数：
    DllCall("EnumWindows", UInt, EnumAddress, UInt, 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() 在所有窗口被列举完之前继续。
    }

    ; 示例：下面是一个可用脚本，演示如何在脚本中通过
    ; 重定向一个窗口的 WindowProc(窗口过程函数) 到一个新的 WindowProc 来 subclass(子类化) 一个 GUI 窗口。
    ; 在这个例子中，文本控件的背景色会被更改成自定义的颜色。

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

    Gui, Add, Text, HwndMyTextHwnd, 这里有一些带自定义背景色的文字。
    Gui +LastFound
    GuiHwnd := WinExist()

    WindowProcNew := RegisterCallback("WindowProc", ""  ; 指定 "" 以避免为子类化使用快速模式。
        , 4, MyTextHwnd)  ; 当给出 EventInfo 参数时必须精确地指定 ParamCount。
    WindowProcOld := DllCall("SetWindowLong", UInt, GuiHwnd, Int, -4  ; -4 是 GWL_WNDPROC
        , Int, WindowProcNew, UInt)  ; 返回值必须指定为 UInt 而不是 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", UInt, wParam, UInt, TextBackgroundColor)
            return TextBackgroundBrush  ; 返回 HBRUSH 以通知操作系统我们改变了 HDC。
        }
        ; 否则（如果上面的代码不返回），将所有不需要处理的消息传递给原先的 WindowProc.
        return DllCall("CallWindowProcA", UInt, WindowProcOld, UInt, hwnd, UInt, uMsg, UInt, wParam, UInt, lParam)
    }

    GuiClose:
    ExitApp