X64dbg-插件开发-字符编码-常用插件函数-回调结构

齐典

2023-12-01

1.字符编码

x64dbg 在任何接受字符串的地方都使用 UTF-8 编码。如果您将字符串传递给 x64dbg，请确保将其转换为 UTF-8 编码。这将有助于减少编码错误。

2.常用插件函数

2.1 _plugin_debugpause

此函数将调试器控制权返回给用户。当您编写需要 x64dbg 支持的解包程序时（例如在开发中），您将使用此函数。调用此函数会将调试状态设置为“暂停”，并且在用户使用run命令运行调试对象之前它不会返回。
参数：这个函数没有参数。返回值：此函数不返回值。

2.2 _plugin_debugskipexceptions

如果调试器应该跳过第一次机会异常，则此函数返回集合。这在创建运行调试对象的解包器或其他插件时很有用。

void  _plugin_debugskipexceptions ( 
bool  skip  //跳过 标志
);

参数：跳过：标记我们是否需要跳过第一次机会异常。返回值：此函数不返回值。

2.3 _plugin_logprintf

此函数向日志窗口打印一条消息。

void  _plugin_logprintf ( 
const  char *  format ,  //格式化 字符串
...  //附加 参数
);

参数：格式：与 printf 具有相同规格的格式字符串。…：附加参数（当格式字符串需要时）。
返回值：此函数不返回值。

2.4 _plugin_logputs

此函数在日志窗口中打印一行。

void  _plugin_logputs ( const  char *  text  //要打印的文本 );

参数：文本：要放入日志窗口的文本。此文本可以包含换行符。返回值：此函数不返回值。

2.5 _plugin_menuadd

此功能将一个新的子菜单添加到菜单中。

int _plugin_menuadd(
int hMenu, //menu handle to add the new child menu to
const char* title //child menu title
);

参数，hMenu：来自先前添加的子菜单或主插件菜单的菜单句柄。title ：菜单标题。返回值：返回子菜单句柄（唯一），失败时返回 -1。

2.6 _plugin_menuaddentry

此功能向菜单添加菜单项。

bool _plugin_menuaddentry(
int hMenu, //menu handle to add the new child menu to
int hEntry, //plugin-wide identifier for the menu entry
const char* title //menu entry title
);

参数
hMenu：来自先前添加的子菜单或主插件菜单的菜单句柄。
hEntry：菜单项的插件范围标识符。这是您将在PLUG_CB_MENUENTRY回调结构中获得的值。
hEntry：菜单项标题。
返回值：当条目添加没有问题时返回true，否则返回false。

2.7 _plugin_menuaddseparator

此功能将一个新的子菜单添加到菜单中。

bool _plugin_menuaddseparator(
int hMenu //menu handle to add the separator to
);

参数：hMenu ：来自先前添加的子菜单或主插件菜单的菜单句柄。
返回值：成功返回真。

2.8 _plugin_menuaddseparator

此功能从菜单中删除所有条目和子菜单。它不会删除菜单本身。

bool  _plugin_menuclear (
int hMenu //menu handle of the menu to clear
);

参数
hMenu ：来自先前添加的子菜单或主插件菜单的菜单句柄。
返回值: 成功返回真。

2.9 _plugin_menuentryseticon

此函数为菜单项设置一个图标。

void _plugin_menuentryseticon (
int pluginHandle, //plugin handle
int hEntry, //handle of the menu entry
const ICONDATA* icon //icon data
);

参数
pluginHandle：调用插件的句柄。hEntry：来自先前添加的子菜单或主插件菜单的菜单句柄。icon ：图标数据。有关定义，请参见bridgemain.h。
返回值：此函数不返回值。

2.10 _plugin_menuentrysetchecked

此函数设置菜单项的选中状态。请注意，此功能将菜单项设置为可检查的，因此它会在点击时默认切换。如果您想要不同的行为，请确保在每次点击时以您想要的状态调用此函数。

void _plugin_menuentrysetchecked (
int pluginHandle, //plugin handle
int hEntry, //handle of the menu entry
bool checked //new checked state
);

参数，pluginHandle：调用插件的句柄。hEntry：来自先前添加的子菜单或主插件菜单的菜单句柄。checked ：新的检查状态。返回值：此函数不返回值。

2.11 _plugin_menuseticon

此功能为菜单设置图标。

void _plugin_menuseticon (
int hMenu, //handle of the menu
const ICONDATA* icon //icon data
);

参数
hMenu：来自先前添加的子菜单或主插件菜单的菜单句柄。icon：图标数据。有关定义，请参见 bridgemain.h。
返回值：此函数不返回值。

2.12 _plugin_registercallback

此函数为插件注册事件回调。每个插件都可以为每个事件拥有自己的回调。同一个事件不可能有多个回调。

void  _plugin_registercallback ( 
int  pluginHandle ,  //插件 句柄
CBTYPE  cbType ,  //事件 类型
CBPLUGIN  cbPlugin  //回调 函数
);

参数
插件句柄：调用插件的句柄。
类型：事件类型。这可以是以下任何值：
CB_INITDEBUG： , //回调信息：PLUG_CB_INITDEBUG*
CB_STOPDEBUG： , //回调信息：PLUG_CB_STOPDEBUG*
CB_CREATEPROCESS： , //回调信息：PLUG_CB_CREATEPROCESS*
CB_EXITPROCESS： , //回调信息：PLUG_CB_EXITPROCESS*
CB_CREATETHREAD： , //回调信息：PLUG_CB_CREATETHREAD*
CB_EXITTHREAD： , //回调信息：PLUG_CB_EXITTHREAD*
CB_SYSTEMBREAKPOINT： , //回调信息：PLUG_CB_SYSTEMBREAKPOINT*
CB_LOADDLL： , //回调信息：PLUG_CB_LOADDLL*
CB_UNLOADDLL： , //回调信息：PLUG_CB_UNLOADDLL*
CB_OUTPUTDEBUGSTRING： , //回调信息：PLUG_CB_OUTPUTDEBUGSTRING*
CB_EXCEPTION: , //回调信息：PLUG_CB_EXCEPTION*
CB_BREAKPOINT： , //回调信息：PLUG_CB_BREAKPOINT*
CB_PAUSEDEBUG： , //回调信息：PLUG_CB_PAUSEDEBUG*
CB_RESUMEDEBUG： , //回调信息：PLUG_CB_RESUMEDEBUG*
CB_STEPPED： , //回调信息：PLUG_CB_STEPPED*
CB_ATTACH： , //回调信息：PLUG_CB_ATTACHED*
CB_DETACH： , //回调信息：PLUG_CB_DETACHED*
CB_DEBUGEVENT： , //回调信息：PLUG_CB_DEBUGEVENT*
CB_MENUENTRY： , //回调信息：PLUG_CB_MENUENTRY*
CB_WINEVENT： , //回调信息：PLUG_CB_WINEVENT*
CB_WINEVENTGLOBAL： , //回调信息：PLUG_CB_WINEVENTGLOBAL*
CB_LOADDB： , //回调信息：PLUG_CB_LOADSAVEDB*
CB_SAVEDB： , //回调信息：PLUG_CB_LOADSAVEDB*
CB_FILTERSYMBOL： , //回调信息：PLUG_CB_FILTERSYMBOL*
CB_TRACEEXECUTE： , //回调信息：PLUG_CB_TRACEEXECUTE*

2.13 _plugin_registercommand

此函数注册一个命令以供在脚本或命令栏内使用。

bool _plugin_registercommand(
int pluginHandle, //plugin handle
const char* command, //command name
CBPLUGINCOMMAND cbCommand, //function that is called when the command is executed
bool debugonly //restrict the command to debug-only
);

参数：pluginHandle：调用插件的句柄。command：命令名称。cbCommand：使用以下 typedef 回调：debugonly：设置后，当没有正在调试的目标时，该命令将永远不会执行。返回值：当命令成功注册时，此函数返回 true，请务必检查这一点，其他插件可能已经注册了相同的命令。

2.14 _plugin_unregistercallback

此插件取消注册先前设置的回调。只能删除之前使用 _plugin_registercallback 设置的回调。

bool _plugin_unregistercallback(
int pluginHandle, //plugin handle
CBTYPE cbType //callback type to remove
);

参数
pluginHandle：调用插件的句柄。cbType：事件类型。这可以是以下任何值：
CB_INITDEBUG, CB_STOPDEBUG，CB_CREATEPROCESS，CB_EXITPROCESS,CB_CREATETHREAD，CB_EXITTHREAD，CB_SYSTEMBREAKPOINT,CB_LOADDLL，CB_UNLOADDLL，CB_OUTPUTDEBUGSTRING，CB_EXCEPTION,CB_BREAKPOINT，CB_PAUSEDEBUG，CB_RESUMEDEBUG，CB_STEPPED,CB_ATTACH，CB_DETACH, CB_DEBUGEVENT, CB_MENUENTRY, CB_WINEVENT, CB_WINEVENTGLOBAL
返回值当回调被删除没有问题时，此函数返回 true。

2.15 _plugin_unregistercommand

此函数删除由插件设置的命令。只能删除您之前使用_plugin_registercommand注册的命令。

bool _plugin_unregistercommand(
int pluginHandle, //plugin handle
const char* command //command name
);

参数，插件句柄：调用插件的句柄。命令：命令名称。返回值，当回调被删除没有问题时，此函数返回 true。

2.16 _plugin_waituntilpaused

等到调试器暂停。

bool _plugin_waituntilpaused();

参数：这个函数没有任何参数。返回值：如果调试对象仍处于活动状态，则此命令返回 true，如果调试对象已停止运行，则返回 false。

2.17 _plugin_hash

这个函数允许你散列一些数据。x64dbg 在各个地方都使用它。

bool _plugin_hash(
const void* data, //data to hash
duint size //size (in bytes) of the data to hash
);

参数，数据：要散列的数据；尺寸：要散列的数据的大小（以字节为单位）。返回值：返回哈希值。

3.回调结构

本节介绍各种插件 SDK 回调结构。这些结构在事件回调中使用（使用 _plugin_registercallback 注册）。请注意，指针 ‘void* callbackInfo’ 从不为 NULL，但各种结构的成员可以为 NULL。还请记住，您不能在回调函数范围之外使用任何提供的指针。通常避免在回调中执行耗时的操作，在单独的线程中执行这些操作。您可以使用_plugin_registercallback函数注册回调。回调的类型定义是：

void CBPLUGIN(
CBTYPE bType //event type (useful when you use the same function for multiple events
void* callbackInfo //pointer to a structure of information (see below)
);

Contents:

PLUG_CB_INITDEBUG
PLUG_CB_STOPDEBUG
PLUG_CB_CREATEPROCESS
PLUG_CB_EXITPROCESS
PLUG_CB_CREATETHREAD
PLUG_CB_EXITTHREAD
PLUG_CB_SYSTEMBREAKPOINT
PLUG_CB_LOADDLL
PLUG_CB_UNLOADDLL
PLUG_CB_OUTPUTDEBUGSTRING
PLUG_CB_EXCEPTION
PLUG_CB_BREAKPOINT
PLUG_CB_PAUSEDEBUG
PLUG_CB_RESUMEDEBUG
PLUG_CB_STEPPED
PLUG_CB_ATTACH
PLUG_CB_DETACH
PLUG_CB_DEBUGEVENT
PLUG_CB_MENUENTRY
PLUG_CB_WINEVENT
PLUG_CB_WINEVENTGLOBAL
PLUG_CB_LOADSAVEDB
PLUG_CB_FILTERSYMBOL
PLUG_CB_TRACEEXECUTE

合理的脚本代码可以有效的提高工作效率，减少重复劳动。

3.作者答疑

如有疑问，敬请留言。