 |
Welcome to A!Die Software Studio |
WinDbg: 扩展命令的参数解析
日期: Nov,2016
原文作者: microsoft
原文标题: Parsing Extension Arguments
原文地址: mk:@MSITStore:debugger.chm::/hh/Debugger/EngExtCpp_DG_ee0ab1ba-1ede-4981-9200-ac2b0dbc6c03.xml.htm
EngExtCpp 扩展框架提供了帮助解析命令参数的方法. 要使用这些方法, 扩展命令必须使用 EXT_COMMAND 宏进行定义.
注: EXT_COMMAND 用于定义使用 EXT_COMMAND_METHOD 声明的扩展命令．EXT_COMMAND_METHOD 的语法为
EXT_COMMAND_METHOD(CommandName);EXT_COMMAND 的语法为
EXT_COMMAND(CommandName, CommandDesc, CommandArgs);
要绕过框架的参数解析, 由扩展直接处理参数的话, 可以将 CommandArgs 设置为 "{{custom}}" 然后使用 GetRawArgStr 获取参数字符串来解析.
CommandArgs 中的字符串在作为帮助显示的时候会自动调整来适应窗口的显示. 不过你可以嵌入 '\n' 来强制换行. CommandArgs 可以为 NULL 或空字符串，此时代表该扩展命令不需要任何参数.
CommandArgs 由两部分组成: 指令和参数. CommandArgs 可以选择包含每种指令一个, 以及最多 64 个参数.
指令
指令用于指出参数怎么解析. 他们由 2 个大括号括起来('{{' 和 '}}'). 每种指令可以出现 0 或 1 次．下面是可用的指令:
关闭框架解析, 由扩展自己解析.
l:字符串覆盖默认的参数完整说明, 框架将使用指定的字符串来作为参数的完整描述.
s:字符串覆盖默认的参数简短说明, 框架将使用指定的字符串来作为参数的简短描述.
opt:字符串覆盖默认的命令参数的前缀. 默认值为 "/-", 表示允许使用 '/' 或 '-' 来作为命名参数的前缀.
指令示例:
1. 下面这串指令表示有扩展自己解析参数, 并提供了 !help 命令显示的参数完整描述和简短描述:
{{custom}}{{s:<arg1> <arg2>}}{{l:arg1 - Argument 1\narg2 - Argument 2}}
2. 下面的指令改变参数的默认前缀 '/' 和 '-'. 使用这条指令后, 参数将使用 '+arg' 和 ':arg' 来代替 '/arg' 和 '-arg':
{{opt:+:}}
参数
参数包含两种类型: 命名的和匿名的. 匿名参数通过位置读取. 使用 help 命令的时候, 两种参数都需要有一个显示的名字.
参数使用单个大括号括起来('{' 和 '}').
每一个参数使用下面的语法:
{[optname];[type[,flags]];[argname];[argdesc]}
{选项名;类型,选项;参数名;参数描述}
里面的各项的含义为:
optname:参数的名字, 这个名字用于在命令和方法中获取参数. 这个名字是可选的. 如果提供了, 这个参数就是命名参数, 它可以出现在命令行的任何地方, 并且可以通过这个名字进行引用. 如果不提供, 这个参数就是匿名参数, 通过相对于其它匿名参数的位置来进行引用, 参数的位置就显得非常重要了.
type:参数的类型, 它决定了怎么解析和获取参数. 类型可以使下面这些值中的一个:
布尔类型, 这个参数可提供可不提供. 命名的布尔参数可以通过 HasArg 获取.
e[d][s][bits]:表达式类型. 这种参数有一个数值的值. 命名的表达式参数可以通过 GetArgU64 获取, 匿名的表达式参数可以通过 GetUnnamedArgU64 获取. 其中:
d: 表达式解析到空格就结束. 不提供的话会一直解析到检测的表达式结束为止.
s: 表达式的值是有符号的. 不提供表示是无符号的.
bits 参数值的 bit 数, 最大为 64.
s:字符串类型. 到空格为止. 命名参数可以通过 GetArgStr 获取. 匿名参数可以通过 GetUnnamedArgStr 获取.
x:字符串类型. 使用命令行中所有剩下的字符串. 和 s 类型一样, 使用 GetArgStr 或 GetUnnamedArgStr 来获取值.
参数的标记, 它指导解析器如何处理参数. 可以是如下的值之一:
参数的默认值. 如果命令行中没有提供该参数, 这个参数的值被设置为 expr. 默认值的字符串会根据参数的类型进行解析.
ds:使用 help 命令时不显示默认值.
o:该参数是可选的. 对命名参数来说, 默认就是可选的.
r:该参数是必须的. 对匿名参数来说, 默认就是必须的.
参数的显示名. 这个名字将被用于 !help 扩展命令, 用 /? 或 -? 参数调用命令, 以及显示命令摘要的时候.
argdesc:参数的描述. 这个说明将被用于 !help 扩展命令以及用 /? 或 -? 参数调用命令的时候.
示例:
1. 下面的表达式定义了一个可选的表达式参数. 这个参数是 32 位的. 如果命令行中没有提供该参数, 会使用默认值 0x100:
{;e32,o,d=0x100;flags;Flags to control command}
2. 下面的表达式定义了一个可选的布尔参数 "/v" 以及一个必须的匿名字符串参数:
{v;b;;Verbose mode}{;s;name;Name of object}
3. 下面的表达式定义了一个可选的命名表达式参数 /oname expr 以及可选的命名字符串参数 /eol str. 如果提供了 /eol, 它的值会设置为命令行中剩余的部分, 后面将不会再进行参数解析了:
{oname;e;expr;Address of object}{eol;x;str;Commands to use}
命令行
内部方法
在参数的解析过程中使用的几个用于设置参数的函数.
SetUnnamedArg 用于改变一个匿名参数的值. 为了简便, SetUnnamedArgStr 和 SetUnnamedArgU64 用于设置匿名字符串和匿名表达式参数的值.
类似的, SetArg 用来改变任意的命名参数的值, SetArgStr 和 SetArgU64 用来改变命名字符串和命名表达式的值.
