IAgentCommands

[Microsoft 代理从 Windows 7 开始已弃用，可能在后续版本的 Windows 中不可用。]

Microsoft 代理服务器维护用户当前可用的命令列表。 此列表包括服务器为常规交互定义的命令，例如 Hide 和 Microsoft Agent Properties、可用 (但非输入活动) 客户端的列表，以及当前活动客户端定义的命令。 前两组命令是全局命令：也就是说，无论输入活动客户端如何，它们都随时可用。 客户端定义的命令仅在该客户端为输入-活动时才可用。

通过查询 IAgentCommands 的 IAgentCharacter 接口来检索 IAgentCommands 接口。 每个 Microsoft 代理客户端应用程序都可以定义一个名为 Commands 集合的命令 集合。 若要将 命令 添加到集合，请使用 Add 或 Insert 方法。 尽管可以使用 IAgentCommand 方法指定 Command 的属性，但为了获得最佳代码性能，请在最初设置新 Command 的属性时，在 IAgentCommands：：Add 或 IAgentCommands：：Insert 方法中指定命令的所有属性。 可以使用 IAgentCommand 方法来查询或更改属性设置。

对于 Commands 集合中的每个 命令 ，可以确定该命令是出现在角色的弹出菜单上、语音命令窗口中、在两者中，还是不显示在这两者中。 例如，如果希望命令显示在字符的弹出菜单上，请设置命令的 Caption 和 Visible 属性。 若要在 “语音命令”窗口中显示命令，请设置命令的 “标题” 和“ 语音 ”属性。

仅当客户端应用程序为输入活动并且字符可见时，用户才能访问 Commands 集合中的单个命令。 因此，通常需要为 Commands 集合对象以及集合中的命令设置 Caption、VoiceCaption 和 Voice 属性，因为这会将命令集合的条目放置在字符的弹出菜单上和“语音命令窗口”中。 当用户通过选择其 Commands 条目切换到客户端时，服务器会自动使客户端输入处于活动状态，使用 IAgentNotifySink：：ActivateInputState 通知客户端应用程序，并使集合中的 命令 可用。 服务器还会使用 IAgentNotifySink：：ActivateInputState 事件通知不再输入主动的客户端。 这使服务器能够仅显示并接受应用于当前输入活动客户端上下文的 命令 。 它还有助于避免客户端之间的 命令名称冲突。

客户端还可以使用 IAgentCharacter：：Activate 方法显式请求将自己设为输入-主动客户端。 此方法还支持将应用程序设置为不是输入-主动客户端。 在与其他应用程序共享字符时，可能需要使用此方法，将应用程序设置为在应用程序窗口获得焦点时为输入主动，在失去焦点时不输入主动。

同样，可以使用 IAgentCharacter：：Activate 将应用程序设置为 (或不) 字符的活动客户端。 活动客户端是当其字符为最顶层字符时接收输入的客户端。 当此状态更改时，服务器会使用 IAgentNotifySinkEx：：ActiveClientChange 事件通知应用程序。

显示字符的弹出菜单时，在用户重新显示菜单之前，不会显示对 Commands 集合的属性或集合中命令的更改。 但是，打开时，“语音命令窗口”在发生更改时会显示这些更改。

IAgentCommands 定义了一个接口，该接口允许应用程序添加、删除、设置和查询 Commands 集合的属性 。 这些函数也可从 IAgentCommandsEx 获取。

命令集合可以在弹出菜单和角色的“语音命令窗口”中显示为命令。 若要显示 Commands 集合，必须设置其 Caption 属性。 下表总结了 Commands 集合的属性如何影响其呈现。

Caption 属性	Voice-Caption 属性	Voice 属性	Visible 属性	显示在字符的弹出菜单中	显示在“语音命令”窗口中
是	是	是	True	是，使用 Caption	是，使用 VoiceCaption
是	是	否¹	True	是，使用 Caption	否
是	是	是	False	否	是，使用 VoiceCaption
是	是	否¹	False	否	否
否¹	是	是	True	否	是，使用 VoiceCaption
否¹	是	是	False	否	是，使用 VoiceCaption
否¹	是	否¹	True	否	否
否¹	是	否¹	False	否	否
是	否¹	是	True	是，使用 Caption	是，使用 Caption
是	否¹	否¹	True	是	否
是	否¹	是	False	否	是，使用 Caption
是	否¹	否¹	False	否	否
否¹	否¹	是	True	否	否²
否¹	否¹	是	False	否	否²
否¹	否¹	否¹	True	否	否
否¹	否¹	否¹	False	否	否

 

¹如果属性设置为 null。 在某些编程语言中，空字符串的解释可能与空字符串不同。

²命令仍可通过语音访问。

按 Vtable 顺序使用的方法

IAgentCommands 方法	说明
GetCommand	从 Commands 集合中检索 Command 对象。
GetCount	返回 Commands 集合中 Commands 数的值。
SetCaption	设置 Commands 集合的 Caption 属性的值。
GetCaption	返回 Commands 集合的 Caption 属性的值。
SetVoice	设置 Commands 集合的 Voice 属性的值。
GetVoice	返回 Commands 集合的 Voice 属性的值。
SetVisible	设置 Commands 集合的 Visible 属性的值。
GetVisible	返回 Commands 集合的 Visible 属性的值。
添加	将 Command 对象添加到 Commands 集合。
插入	在 Commands 集合中插入 Command 对象。
删除	删除 Commands 集合中的 Command 对象。
RemoveAll	从 Commands 集合中删除所有 Command 对象。