HidP_TranslateUsagesToI8042ScanCodes 函数 (hidpi.h)

项目
02/29/2024

HidP_TranslateUsagesToI8042ScanCodes例程将HID_USAGE_PAGE_KEYBOARD使用情况页上的 HID 用法列表映射到各自的 PS/2 扫描代码 (扫描代码集 1) 。

语法

NTSTATUS HidP_TranslateUsagesToI8042ScanCodes(
  [in]           PUSAGE                        ChangedUsageList,
  [in]           ULONG                         UsageListLength,
  [in]           HIDP_KEYBOARD_DIRECTION       KeyAction,
  [in, out]      PHIDP_KEYBOARD_MODIFIER_STATE ModifierState,
  [in]           PHIDP_INSERT_SCANCODES        InsertCodesProcedure,
  [in, optional] PVOID                         InsertCodesContext
);

参数

[in] ChangedUsageList

指向键盘 (按钮) 用法列表的指针。 translate usages 例程将零解释为结束使用情况列表的分隔符。

[in] UsageListLength

指定更改的使用情况列表中的最大可能用法数。

[in] KeyAction

标识指定更改使用情况列表的关键方向。

typedef enum _HIDP_KEYBOARD_DIRECTION {
    HidP_Keyboard_Break,
    HidP_Keyboard_Make
} HIDP_KEYBOARD_DIRECTION;

HidP_Keyboard_Break

指定键向上) (中断方向。更改的使用情况列表包含设置为 OFF 的用法，这些用法以前设置为 ON (对应于以前关闭的键，但现在) 。

HidPKeyboard_Make

指定 (键向下键) 的生成方向。更改的使用情况列表包含设置为 ON 的用法，这些用法以前设置为 OFF (对应于以前启动的键，但现在已关闭) 。

[in, out] ModifierState

指向调用方维护供转换用法例程使用的_HIDP_KEYBOARD_MODIFIER_STATE结构的指针。修饰符状态结构标识键盘修饰键的状态。

typedef struct _HIDP_KEYBOARD_MODIFIER_STATE {
    union {
      struct {
        ULONG LeftControl: 1;
        ULONG LeftShift: 1;
        ULONG LeftAlt: 1;
        ULONG LeftGUI: 1;
        ULONG RightControl: 1;
        ULONG RightShift: 1;
        ULONG RightAlt: 1;
        ULONG RigthGUI: 1;
        ULONG CapsLock: 1;
        ULONG ScollLock: 1;
        ULONG NumLock: 1;
        ULONG Reserved: 21;
      };
      ULONG ul;
};

修饰符状态结构的每个成员标识是将相应的用法设置为 ON (1) 还是 OFF (零) 。

有关如何将修饰符状态结构与 translate 用法例程一起使用的详细信息，请参阅“备注”部分。

[in] InsertCodesProcedure

指向调用方提供的PHIDP_INSERT_SCANCODES类型回调例程的指针，转换用法例程使用该例程将映射的扫描代码返回给转换用法例程的调用方。

typedef BOOLEAN (*PHIDP_INSERT_SCANCODES)(
    IN PVOID  Context,
    IN PCHAR  NewScanCodes,
    IN ULONG  Length
    );

上下文

指向 translate 用法例程的调用方上下文的指针。 translate 用法例程将 InsertCodesContext 指针传递给 InsertCodesProcedure 例程。

NewScanCodes

指向扫描代码的第一个字节的指针，翻译用法例程将返回给 translate 用法例程的调用方。

Length

指定扫描代码的长度（以字节为单位）。扫描代码不能超过四个字节。

[in, optional] InsertCodesContext

指向调用方定义的上下文的指针，转换用法例程将传递给 InsertCodesProcedure 例程。

返回值

HidP_TranslateUsagesToI8042ScanCodes 返回以下状态值之一：

返回代码	说明
HIDP_STATUS_SUCCESS	转换用法例程已成功映射更改的使用情况列表中的所有有效用法。
HIDP_STATUS_I8042_TRANS_UNKNOWN	已更改的使用情况列表中的用法映射到无效的键盘扫描代码。

注解

HidP_TranslateUsagesToI8042ScanCodes 按更改的用法列表中的键盘按钮用法在列表中出现的顺序按顺序映射，从 ChangedUsageList 的值开始。转换用法例程成功映射使用情况后，它将使用调用方的 InsertCodesProcedure 例程将相应的扫描代码返回给调用方。转换用法例程继续映射列表中的用法，直到发生以下情况之一：列表中的用法值为零;它映射 UsageListLength 指定的使用情况数;用法映射到无效的键盘扫描代码。

HidP_TranslateUsagesToI8042ScanCodes 主要用于处理循环，该循环重复确定当前使用情况列表 (当前设置为 ON) 的用法，将它们与先前设置为 ON) 的使用情况列表 (用法进行比较，并映射当前和以前的使用情况列表之间的差异，以生成扫描代码和中断扫描代码。以下操作演示了如何使用翻译用法例程。

在开始处理循环之前，处理代码通常会分配和初始化以下数据：

以前的使用情况列表、当前使用情况列表、中断使用情况列表和 Make 使用情况列表。
每个列表都是零初始化的用法数组。若要确保处理代码映射在连续 HID 输入报表之间可能更改的所有用法，处理代码必须将每个列表中的元素数设置为 HidP_GetUsages 可为HID_USAGE_PAGE_KEYBOARD使用情况页返回的最大用法数。此数字是使用 HidP_MaxUsageListLength 获取的。
由零初始化_HIDP_KEYBOARD_MODIFIER_STATE结构，供转换用法例程使用。
在处理循环中，代码必须维护此结构，以供翻译用法例程使用。处理代码可以读取修饰键的状态，但代码不得修改结构。 translate 用法例程使用此结构来维护有关修改键状态的内部信息。

初始化所需的结构后，处理循环的每次迭代通常包括以下操作序列：

调用 HidP_GetUsages 以获取设置为 ON 的用法的当前使用列表。将 get usages 例程的 UsagePage 输入参数设置为HID_USAGE_PAGE_KEYBOARD。
调用 HidP_UsageListDifference ，将当前使用情况列表与以前的使用情况列表进行比较。使用情况列表差异例程返回中断使用情况列表和 make 使用情况列表。
调用 translate 用法例程，将 ChangedUsageList 设置为中断用法列表， 将 KeyAction 设置为HidP_KeyboardBreak，将 ModifierState 设置为处理代码为翻译用法例程维护的结构。 translate usages 例程使用 InsertCodesProcedure的回调例程将中断扫描代码返回到处理循环。
调用 translate 用法例程，将 ChangedUsageList 设置为 make usage list， 将 KeyAction 设置为 HidP_KeyboardMake，将 ModifierState 设置为处理代码为翻译用法例程维护的结构。 translate usages 例程使用 InsertCodesProcedure的回调例程将生成扫描代码返回到处理循环。
将以前的使用情况列表更新为当前使用情况列表。

有关 HID 用法与 PS/2 键盘扫描代码之间的映射的信息，请参阅密钥支持和扫描代码网站。

要求

要求	值
最低受支持的客户端	在 Windows 2000 和更高版本的 Windows 中可用。
目标平台	通用
标头	hidpi.h (包括 Hidpi.h)
Library	Hidparse.lib
IRQL	<= DISPATCH_LEVEL

另请参阅

HidP_GetUsages

HidP_MaxUsageListLength

HidP_UsageListDifference

通过