HidP_TranslateUsagesToI8042ScanCodes函式 (hidpi.h)

發行項
02/26/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 (零) 。

如需修飾詞狀態結構如何搭配翻譯使用例程的詳細資訊，請參閱一節。

[in] InsertCodesProcedure

呼叫端提供的PHIDP_INSERT_SCANCODES型別回呼例程指標，轉譯使用例程用來將對應的掃描碼傳回至轉譯使用例程的呼叫端。

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

Context

轉譯使用例程之呼叫端內容的指標。翻譯使用例程會將 InsertCodesContext 指標傳遞至 InsertCodesProcedure 例程。

NewScanCodes

掃描程序代碼的第一個字節指標，轉譯使用例程會傳迴轉譯使用例程的呼叫端。

長度

指定掃描碼的長度，以位元組為單位。掃描碼不能超過四個字節。

[in, optional] InsertCodesContext

轉譯使用例程傳遞給 InsertCodesProcedure 例程之呼叫端定義內容的指標。

傳回值

HidP_TranslateUsagesToI8042ScanCodes 會傳回下列其中一個狀態值：

傳回碼	Description
HIDP_STATUS_SUCCESS	翻譯使用例程已成功對應已變更使用量清單中的所有有效使用量。
HIDP_STATUS_I8042_TRANS_UNKNOWN	對應至無效鍵盤掃描程式碼之已變更使用方式清單中的使用量。

備註

HidP_TranslateUsagesToI8042ScanCodes 會依變更的使用方式清單順序，循序對應變更的使用方式清單中的鍵盤按鈕使用方式，從 ChangedUsageList 的值開始。轉譯使用例程成功對應使用方式之後，它會使用呼叫端的 InsertCodesProcedure 例程，將對應的掃描程式代碼傳回給呼叫端。轉譯使用例程會繼續對應清單中的使用量，直到發生下列其中一項為止：清單中的使用量值為零;它會對應 UsageListLength 所指定的使用量數目;使用方式會對應至無效的鍵盤掃描程序代碼。

HidP_TranslateUsagesToI8042ScanCodes 主要設計成用於處理迴圈中，以重複判斷目前使用量清單 (目前設定為 ON) 的使用方式、將它們與先前的使用清單比較 (使用量清單， (先前設定為 ON) 的使用方式，並對應目前和先前的使用清單之間的差異，以建立掃描碼和中斷掃描碼。下列作業說明如何使用翻譯使用例程。

在開始處理迴圈之前，處理程式碼通常會配置並初始化下列數據：

先前的使用清單、目前的使用量清單、中斷使用量清單，以及使用方式清單。
每個清單都是使用方式的零初始化陣列。為了確保處理程式代碼會對應連續 HID 輸入報表之間可變更的所有使用方式，處理程式代碼必須將每個清單中的元素數目設定為 HidP_GetUsages 可針對HID_USAGE_PAGE_KEYBOARD使用量頁面傳回的最大使用量數目。這個數位是使用 HidP_MaxUsageListLength 取得。
零初始化_HIDP_KEYBOARD_MODIFIER_STATE結構，供轉譯使用例程使用。
在處理迴圈中，程式代碼必須維護此結構，以供翻譯使用例程使用。處理程式代碼可以讀取修飾詞索引鍵的狀態，但程式代碼不得修改結構。翻譯使用例程會使用此結構來維護修飾詞索引鍵狀態的內部資訊。

初始化所需的結構之後，處理迴圈的每個反覆專案通常會包含下列作業順序：

呼叫 HidP_GetUsages ，以取得目前設定為 ON 的使用方式清單。將 get usages 例程的 UsagePage 輸入參數設定為 HID_USAGE_PAGE_KEYBOARD。
呼叫 HidP_UsageListDifference ，將目前的使用量清單與先前的使用量清單進行比較。使用量清單差異例程會傳回中斷的使用方式清單和建立使用清單。
呼叫翻譯使用例程、將 ChangedUsageList 設定為中斷使用方式清單、 KeyAction 以HidP_KeyboardBreak，並將 ModifierState 設定為轉譯使用例程所維護之處理程式代碼的結構。 translate usages 例程會使用 InsertCodesProcedure的回呼例程，將中斷掃描代碼傳回至處理迴圈。
呼叫 translate usage 例程，將 ChangedUsageList 設定為 make usage list、 KeyAction 以HidP_KeyboardMake，並將 ModifierState 設定為轉譯使用例程所維護之處理程式代碼的結構。 translate usages 例程會使用 InsertCodesProcedure的回呼例程，將進行掃描代碼傳回至處理迴圈。
將先前的使用量清單更新為目前的使用量清單。

如需 HID 使用方式與 PS/2 鍵盤掃描代碼之間的對應資訊，請參閱密鑰支援和掃描代碼網站。

規格需求

需求	值
最低支援的用戶端	適用於 Windows 2000 和更新版本的 Windows。
目標平台	Universal
標頭	hidpi.h (包含 Hidpi.h)
程式庫	Hidparse.lib
IRQL	<= DISPATCH_LEVEL

另請參閱

HidP_GetUsages

HidP_MaxUsageListLength

HidP_UsageListDifference

共用方式為