A!die Software Studio Welcome to A!Die Software Studio

WinDbg: 扩展命令的参数解析

翻译: adie
日期: 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 次.下面是可用的指令:

custom

关闭框架解析, 由扩展自己解析.

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:

参数的类型, 它决定了怎么解析和获取参数. 类型可以使下面这些值中的一个:

b:

布尔类型, 这个参数可提供可不提供. 命名的布尔参数可以通过 HasArg 获取.

e[d][s][bits]:

表达式类型. 这种参数有一个数值的值. 命名的表达式参数可以通过 GetArgU64 获取, 匿名的表达式参数可以通过 GetUnnamedArgU64 获取. 其中:

d: 表达式解析到空格就结束. 不提供的话会一直解析到检测的表达式结束为止.

s: 表达式的值是有符号的. 不提供表示是无符号的.

bits 参数值的 bit 数, 最大为 64.

s:

字符串类型. 到空格为止. 命名参数可以通过 GetArgStr 获取. 匿名参数可以通过 GetUnnamedArgStr 获取.

x:

字符串类型. 使用命令行中所有剩下的字符串. 和 s 类型一样, 使用 GetArgStr 或 GetUnnamedArgStr 来获取值.

flags:

参数的标记, 它指导解析器如何处理参数. 可以是如下的值之一:

d=expr:

参数的默认值. 如果命令行中没有提供该参数, 这个参数的值被设置为 expr. 默认值的字符串会根据参数的类型进行解析.

ds:

使用 help 命令时不显示默认值.

o:

该参数是可选的. 对命名参数来说, 默认就是可选的.

r:

该参数是必须的. 对匿名参数来说, 默认就是必须的.

argname:

参数的显示名. 这个名字将被用于 !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}

命令行

下面是在命令行中传递参数的方法:
  • 命名表达式或字符串的值紧跟在参数名的后面. 例如, /name expr 或 /name str
  • 命名布尔参数中, 如果命令行中出现了参数名, 则值为 true, 否则为 false
  • 多个单字符的布尔参数可以组合在一起. 例如, /a /b /c 可以写成简短的 /abc (除非已经有了一个 "abc" 名字的参数)
  • 如果参数中包含了 "?", 比如 "/?" 和 "-?", 将结束参数的解析, 打印出该扩展命令的帮助信息.
  • 内部方法

    在参数的解析过程中使用的几个用于设置参数的函数.

    SetUnnamedArg 用于改变一个匿名参数的值. 为了简便, SetUnnamedArgStr 和 SetUnnamedArgU64 用于设置匿名字符串和匿名表达式参数的值.

    类似的, SetArg 用来改变任意的命名参数的值, SetArgStr 和 SetArgU64 用来改变命名字符串和命名表达式的值.

    ▲评论

    X 正在回复:
    姓 名: 留下更多信息
    性 别:
    邮 件:
    主 页:
    Q Q:
    来 自:
    职 业:
    评 论:


    Valid HTML 4.01 Strict Valid CSS!
    Copyleft.A!die Software Studio.ADSS
    Power by webmaster@adintr.com