WebHID API

WebIDL[SecureContext] partial interface Navigator {
    [SameObject] readonly attribute HID hid;
};

WebIDL[Exposed=(DedicatedWorker,ServiceWorker), SecureContext]
partial interface WorkerNavigator {
    [SameObject] readonly attribute HID hid;
};

WebIDL[Exposed=(DedicatedWorker,ServiceWorker,Window), SecureContext]
interface HID : EventTarget {
    attribute EventHandler onconnect;
    attribute EventHandler ondisconnect;
    Promise<sequence<HIDDevice>> getDevices();
    [Exposed=Window] Promise<sequence<HIDDevice>> requestDevice(
        HIDDeviceRequestOptions options);
};

HID 인스턴스는 다음 표에 설명된 내부 슬롯과 함께 생성됩니다:

onconnect 속성

onconnect는 이벤트 핸들러 IDL 속성으로, connect 이벤트 유형에 해당합니다.

ondisconnect 속성

ondisconnect는 이벤트 핸들러 IDL 속성으로, disconnect 이벤트 유형에 해당합니다.

시스템에서 HID 인터페이스가 사용 가능해지면 다음 단계를 수행합니다:

1. device를 HIDDevice로 둔다.
2. device.[[vendorId]]를 해당 인터페이스를 노출한 장치의 vendor ID로 설정한다.
3. device.[[productId]]를 해당 인터페이스를 노출한 장치의 product ID로 설정한다.
4. device.[[productName]]을 해당 인터페이스를 노출한 장치의 product name으로 설정한다.
5. device.[[collections]]을 리포트 서술자 파싱의 결과로 설정한다.
6. hid를 다음과 같이 정한다. 만약 device의 관련 전역 객체가 Window 객체라면 그 객체의 hid getter를 호출한 결과로 하고, 그렇지 않으면 WorkerNavigator 객체의 hid getter를 호출한 결과로 한다.
7. 추가한다: device를 hid.[[devices]]에.
8. 이전에 requestDevice() 호출 결과로 사용자가 사이트가 device에 접근하는 것을 허용했다면, 관련 전역 객체 상에서 HID device task source를 사용해 글로벌 태스크를 큐잉하고, 이벤트를 발행한다. 이벤트 이름은 connect이며 대상은 hid이다. 이때 HIDConnectionEvent를 사용하고, 그 device 속성은 device로 초기화한다.

리포트 서술자를 파싱하려면 다음 단계를 수행한다:

1. items를 리포트 서술자 바이트 시퀀스를 리스트로 변환한 결과로 둔다. 이 리스트에는 메인 아이템, 글로벌 아이템, 로컬 아이템이 포함된다.
2. collections를 HIDCollectionInfo의 빈 sequence로 초기화한다.
3. ancestors를 빈 리스트로 초기화한다.
4. localState를 빈 ordered map으로 초기화한다.
5. usages를 unsigned long의 빈 sequence로 초기화한다.
6. stringIndices를 빈 리스트로 초기화한다.
7. globalStack을 빈 스택으로 초기화한다.
8. initialGlobalState를 빈 ordered map으로 초기화한다.
9. reportId를 0으로 초기화한다.
10. initialGlobalState["unitSystem"]을 "none"으로 설정한다.
11. initialGlobalState["unitExponent"]을 0으로 설정한다.
12. initialGlobalState["unitFactorLengthExponent"]을 0으로 설정한다.
13. initialGlobalState["unitFactorMassExponent"]을 0으로 설정한다.
14. initialGlobalState["unitFactorTimeExponent"]을 0으로 설정한다.
15. initialGlobalState["unitFactorTemperatureExponent"]을 0으로 설정한다.
16. initialGlobalState["unitFactorCurrentExponent"]을 0으로 설정한다.
17. initialGlobalState["unitFactorLuminousIntensityExponent"]을 0으로 설정한다.
18. initialGlobalState["logicalMinimum"]을 0으로 설정한다.
19. initialGlobalState["logicalMaximum"]을 0으로 설정한다.
20. initialGlobalState["physicalMinimum"]을 0으로 설정한다.
21. initialGlobalState["physicalMaximum"]을 0으로 설정한다.
22. 푸시한다: initialGlobalState를 globalStack에.
23. 각각에 대해: items의 item마다:
    참고

    메인 아이템은 [USBIF-HID-CLASS] 6.2.2.4~6.2.2.6 절에 설명되어 있습니다. Input tag, Output tag, Feature tag가 있는 아이템은 입력/출력/피처 리포트 내의 필드를 정의합니다. 메인 아이템의 item data field는 Input tag, Output tag, Feature tag 중 하나인 경우, 데이터 필드를 설명하는 여러 불리언 파라미터를 담은 비트 필드입니다. Collection tag가 있는 아이템은 현재 컬렉션 내부에 새 컬렉션을 정의하거나, 현재 컬렉션이 없을 때는 새 최상위 컬렉션을 정의합니다. 메인 아이템의 Collection tag의 item data field에는 컬렉션 타입이 들어 있습니다. End Collection tag가 있는 아이템은 현재 컬렉션을 닫습니다.

    • item이 메인 아이템인 경우:
      1. item에 Input tag, Output tag, Feature tag가 있는 경우:
         1. globalState를 globalStack의 마지막 아이템으로 둔다.
         2. reportId를 globalState["reportId"]로 둔다.
         3. reportItem을 HID 리포트 아이템 생성의 결과로 둔다. 인자는 item, localState, globalState, usages, strings이다.
         4. 각각에 대해: ancestors의 collection마다
            1. reports를 다음과 같이 둔다:
               • collection["inputReports"] — item에 Input tag가 있는 경우
               • collection["outputReports"] — item에 Output tag가 있는 경우
               • collection["featureReports"] — item에 Feature tag가 있는 경우

            2. reports에 그 reportId 속성이 reportId와 같은 아이템이 있으면, report를 그 아이템으로 둔다.

               그렇지 않으면:

               1. report를 새로운 HIDReportInfo 딕셔너리로 둔다.
               2. report["reportId"]를 reportId로 설정한다.
               3. report["items"]를 HIDReportItem의 빈 sequence로 설정한다.
               4. 추가한다: report를 reports에.
            3. 추가한다: item을 report["items"]에.
      2. item에 Collection tag가 있는 경우:
         1. collection을 새로운 HIDCollectionInfo 딕셔너리로 둔다.
         2. usage를 usages의 첫 번째 아이템으로 둔다.
         3. usages의 크기가 1보다 크면, usages의 첫 번째 아이템을 제거한다.
         4. collection["usagePage"]를 globalState["usagePage"]로 설정한다.
         5. collection["usage"]를 usage로 설정한다.
         6. collection["type"]을 컬렉션의 타입을 나타내는 값으로 설정한다.
         7. collection["children"]을 빈 sequence의 HIDCollectionInfo로 설정한다.
         8. collection["inputReports"]을 HIDReportInfo의 빈 sequence로 설정한다.
         9. collection["outputReports"]을 HIDReportInfo의 빈 sequence로 설정한다.
         10. collection["featureReports"]을 HIDReportInfo의 빈 sequence로 설정한다.

         11. ancestors가 비어 있으면 추가한다: collection을 collections에.

             그렇지 않으면:

             1. parent를 ancestors의 마지막 아이템으로 둔다.
             2. 추가한다: collection을 parent["children"]에.
         12. 추가한다: collection을 ancestors에.
      3. item에 End Collection tag가 있으면, 제거한다: ancestors의 마지막 아이템을.
      4. localState를 빈 ordered map으로 설정한다.
      5. usages를 unsigned long의 빈 sequence로 설정한다.
         참고

         글로벌 아이템은 6.2.2.7 절에 설명되어 있습니다. Usage Page tag, Logical Minimum tag, Logical Maximum tag, Physical Minimum tag, Physical Maximum tag, Unit Exponent tag, Unit tag, Report Size tag, Report ID tag, Report Count tag는 글로벌 아이템 상태 테이블의 해당 필드를 수정합니다. Push tag가 있는 아이템은 현재 글로벌 아이템 상태 테이블의 복사본을 아이템 상태 스택에 푸시합니다. Pop tag가 있는 아이템은 아이템 상태 스택의 맨 위 항목으로 글로벌 아이템 상태 테이블을 대체합니다. 아이템 상태 스택을 조작할 때 글로벌 Report ID 값은 영향을 받지 않습니다.

      6. item이 글로벌 아이템인 경우:
         1. globalState를 globalStack의 마지막 아이템으로 둔다.
         2. value를 item data field를 unsigned long으로 해석한 값으로 둔다.
         3. item에 Usage Page tag가 있으면 globalState["usagePage"]를 value로 설정한다.
         4. item에 Logical Minimum tag가 있으면 globalState["logicalMinimum"]를 value로 설정한다.
         5. item에 Logical Maximum tag가 있으면 globalState["logicalMaximum"]를 value로 설정한다.
         6. item에 Physical Minimum tag가 있으면 globalState["physicalMinimum"]를 value로 설정한다.
         7. item에 Physical Maximum tag가 있으면 globalState["physicalMaximum"]를 value로 설정한다.
         8. item에 Report Size tag가 있으면 globalState["reportSize"]를 value로 설정한다.
         9. item에 Report ID tag가 있으면 globalState["reportId"]를 value로 설정한다.
         10. item에 Report Count tag가 있으면 globalState["reportCount"]를 value로 설정한다.
         11. item에 Unit tag가 있으면:
             1. nibbles를 value를 낮은 비트부터 시작하여 8개의 4비트 부호 있는 2의 보수 정수의 sequence로 해석한 결과로 둔다.
             2. nibbles[0]이 다음과 같으면:
                • 0 — globalState["unitSystem"]을 "none"으로 설정
                • 1 — globalState["unitSystem"]을 "si-linear"로 설정
                • 2 — globalState["unitSystem"]을 "si-rotation"으로 설정
                • 3 — globalState["unitSystem"]을 "english-linear"로 설정
                • 4 — globalState["unitSystem"]을 "english-rotation"으로 설정
                • -1 — globalState["unitSystem"]을 "vendor-defined"로 설정
                • 그 외 — globalState["unitSystem"]을 "reserved"로 설정
             3. globalState["unitFactorLengthExponent"]를 nibbles[1]로 설정한다.
             4. globalState["unitFactorMassExponent"]를 nibbles[2]로 설정한다.
             5. globalState["unitFactorTimeExponent"]를 nibbles[3]으로 설정한다.
             6. globalState["unitFactorTemperatureExponent"]를 nibbles[4]로 설정한다.
             7. globalState["unitFactorCurrentExponent"]를 nibbles[5]로 설정한다.
             8. globalState["unitFactorLuminousIntensityExponent"]를 nibbles[6]으로 설정한다.
         12. item에 Unit Exponent tag가 있으면, globalState["unitExponent"]를 item data field의 최하위 4비트를 부호 있는 2의 보수 정수로 해석한 결과로 설정한다.
         13. item에 Push tag가 있으면, 푸시한다: globalState의 복사본을 globalStack에.
         14. item에 Pop tag가 있으면, 팝한다: globalStack에서.
      참고

      로컬 아이템은 6.2.2.8 절에 설명되어 있습니다. Usage tag, Usage Minimum tag, Usage Maximum tag, String Index tag, String Minimum tag, String Maximum tag가 있는 아이템은 로컬 아이템 상태 테이블의 해당 필드를 수정합니다. 로컬 아이템 상태는 각 메인 아이템 이후에 초기화됩니다.

    • item이 로컬 아이템인 경우:
      1. value를 item data field를 unsigned long으로 해석한 값으로 둔다.
      2. item에 Usage tag가 있으면:
         1. item의 bSize field가 1 또는 2인 경우:
            1. usageId를 value의 하위 16비트를 담는 unsigned short로 둔다.
            2. globalState를 globalStack의 마지막 아이템으로 둔다.
            3. value를 HID usage로 구성된 값으로 설정한다. 이 값은 상위 비트에 globalState["usagePage"]를, 하위 비트에 usageId를 갖는다.
         2. 추가한다: value를 usages에.
      3. item에 Usage Minimum tag가 있으면 localState["usageMinimum"]을 value로 설정한다.
      4. item에 Usage Maximum tag가 있으면 localState["usageMaximum"]을 value로 설정한다.
      5. item에 String Index tag가 있으면 추가한다: value를 stringIndices에.
      6. item에 String Minimum tag가 있으면 localState["stringMinimum"]을 value로 설정한다.
      7. item에 String Maximum tag가 있으면 localState["stringMaximum"]을 value로 설정한다.

item, localState, globalState, usages, stringIndices로 HID 리포트 아이템을 생성하려면 다음 단계를 수행한다:

1. reportItem을 새로운 HIDReportItem 딕셔너리로 둔다.
2. value를 item data field를 unsigned long으로 해석한 값으로 둔다.
3. bitfield를 value의 각 비트를 낮은 비트부터 나타내는 boolean 값들의 리스트로 둔다.
4. reportItem["isConstant"]를 bitfield[0]으로 설정한다.
5. reportItem["isArray"]를 !bitfield[1]로 설정한다.
6. reportItem["isAbsolute"]를 !bitfield[2]로 설정한다.
7. reportItem["wrap"]을 bitfield[3]으로 설정한다.
8. reportItem["isLinear"]를 !bitfield[4]로 설정한다.
9. reportItem["hasPreferredState"]를 bitfield[5]로 설정한다.
10. reportItem["hasNull"]을 bitfield[6]으로 설정한다.
11. reportItem["isVolatile"]을 bitfield[7]로 설정한다.
12. reportItem["isBufferedBytes"]를 bitfield[8]로 설정한다.
13. reportItem["usages"]를 usages로 설정한다.
14. reportItem["reportSize"]를 globalState["reportSize"]로 설정한다.
15. reportItem["reportCount"]를 globalState["reportCount"]로 설정한다.
16. reportItem["unitExponent"]를 globalState["unitExponent"]로 설정한다.
17. reportItem["unitSystem"]을 globalState["unitSystem"]로 설정한다.
18. reportItem["unitFactorLengthExponent"]을 globalState["unitFactorLengthExponent"]로 설정한다.
19. reportItem["unitFactorMassExponent"]를 globalState["unitFactorMassExponent"]로 설정한다.
20. reportItem["unitFactorTimeExponent"]를 globalState["unitFactorTimeExponent"]로 설정한다.
21. reportItem["unitFactorTemperatureExponent"]를 globalState["unitFactorTemperatureExponent"]로 설정한다.
22. reportItem["unitFactorCurrentExponent"]를 globalState["unitFactorCurrentExponent"]로 설정한다.
23. reportItem["unitFactorLuminousIntensityExponent"]를 globalState["unitFactorLuminousIntensityExponent"]로 설정한다.
24. reportItem["logicalMinimum"]을 globalState["logicalMinimum"]로 설정한다.
25. reportItem["logicalMaximum"]을 globalState["logicalMaximum"]로 설정한다.

26. "usageMinimum"이 localState에 있으면 reportItem["usageMinimum"]을 localState["usageMinimum"]로 설정한다.

27. "usageMaximum"이 localState에 있으면 reportItem["usageMaximum"]을 localState["usageMaximum"]로 설정한다.

28. reportItem["isRange"]를 reportItem["usageMinimum"]이 reportItem["usageMaximum"]보다 작은 경우 true로, 그렇지 않으면 false로 설정한다.
29. "stringMinimum"과 "stringMaximum"이 localState에 모두 있으면:
    1. 추가한다: 범위 아이템들을, 즉 localState["stringMinimum"]부터 localState["stringMaximum"]까지를 stringIndices에.
30. 각각에 대해: stringIndices의 stringIndex마다
    1. string을 index stringIndex의 문자열 서술자를 읽은 결과로 둔다.
    2. 추가한다: string을 reportItem["strings"]에.
31. reportItem을 반환한다.

시스템에서 HID 인터페이스가 사용 불가능해지면 다음 단계를 수행한다:

1. device를 hid.[[devices]]에서 해당 인터페이스를 나타내는 HIDDevice로 둔다.
2. hid를 다음과 같이 둔다: device의 관련 전역 객체가 Window 객체라면 그 객체의 hid getter를 호출한 결과로 하고, 그렇지 않으면 WorkerNavigator 객체의 hid getter를 호출한 결과로 한다.
3. 제거한다: device를 hid.[[devices]]에서.
4. 이전에 requestDevice() 호출 결과로 사용자가 사이트가 device에 접근하는 것을 허용했다면, hid의 관련 전역 객체에서 HID device task source를 사용해 글로벌 태스크를 큐잉하고, 이벤트를 발행한다. 이벤트 이름은 disconnect이며 대상은 hid이다. 이때 HIDConnectionEvent를 사용하고, 그 device 속성은 device로 초기화한다.

WebIDLdictionary HIDDeviceRequestOptions {
    required sequence<HIDDeviceFilter> filters;
    sequence<HIDDeviceFilter> exclusionFilters;
};

WebIDLdictionary HIDDeviceFilter {
    unsigned long vendorId;
    unsigned short productId;
    unsigned short usagePage;
    unsigned short usage;
};

WebIDL[Exposed=(DedicatedWorker,ServiceWorker,Window), SecureContext]
interface HIDDevice : EventTarget {
    attribute EventHandler oninputreport;
    readonly attribute boolean opened;
    readonly attribute unsigned short vendorId;
    readonly attribute unsigned short productId;
    readonly attribute DOMString productName;
    readonly attribute FrozenArray<HIDCollectionInfo> collections;
    Promise<undefined> open();
    Promise<undefined> close();
    Promise<undefined> forget();
    Promise<undefined> sendReport([EnforceRange] octet reportId, BufferSource data);
    Promise<undefined> sendFeatureReport(
        [EnforceRange] octet reportId,
        BufferSource data);
    Promise<DataView> receiveFeatureReport([EnforceRange] octet reportId);
};

이 인터페이스의 메서드들은 일반적으로 비동기적으로 완료되며, HID device task source에 작업을 큐잉합니다.

HIDDevice의 인스턴스는 다음 표에 설명된 내부 슬롯과 함께 생성됩니다:

oninputreport 속성

oninputreport는 이벤트 핸들러 IDL 속성으로, inputreport 이벤트 유형에 해당합니다.

opened 속성

HIDDevice가 데이터 전송을 할 준비가 되었음을 나타내는 플래그입니다.

opened getter 단계는 다음과 같습니다:

1. this.[[state]]가 opened이면 true를 반환합니다.
2. false를 반환합니다.

vendorId 속성

vendor ID는 장치 제조사를 식별하기 위해 vendor ID source가 할당하는 unsigned short 값입니다.

vendorId 속성은 장치의 vendor ID입니다. 장치에 vendor ID가 없거나 vendor ID에 접근할 수 없으면, 이 속성은 MUST 0이어야 합니다.

vendorId getter 단계는 다음과 같습니다:

1. this.[[vendorId]]를 반환합니다.

productId 속성

product ID는 제조사가 제품을 식별하기 위해 할당하는 unsigned short 값입니다.

productId 속성은 장치의 product ID입니다. 장치에 product ID가 없거나 product ID에 접근할 수 없으면, 이 속성은 MUST 0이어야 합니다.

productId getter 단계는 다음과 같습니다:

1. this.[[productId]]를 반환합니다.

productName 속성

제품을 식별하는 문자열입니다.

USB HID 장치의 경우, product name에는 장치 서술자(Device Descriptor)에 지정된 인덱스 iProduct의 문자열 서술자 값이 SHOULD 포함되어야 합니다. Bluetooth HID 장치의 경우, product name에는 Device Name 특성의 값이 SHOULD 포함되어야 합니다. 장치에 product name이 없거나 product name이 비어 있거나 접근할 수 없으면, 이 속성은 MUST 빈 문자열을 반환해야 합니다.

productName 문자열에는 일련 번호나 Bluetooth 장치 주소와 같이 장치를 고유하게 식별할 수 있는 식별자가 SHOULD NOT 포함되어야 합니다.

productName getter 단계는 다음과 같습니다:

1. this.[[productName]]를 반환합니다.

collections 속성

sequence의 HIDCollectionInfo로, report descriptor의 top-level collections을 나타냅니다.

collections getter 단계는 다음과 같습니다:

1. this.[[collections]]를 반환합니다.

Note

Top-level collections는 장치 내에서 유사한 목적의 항목들을 그룹화합니다. 애플리케이션은 장치를 식별하기 위해 top-level collections에 적용된 HID usage를 확인합니다. 특정 유형의 장치에 대한 규약을 따르지 않으면 애플리케이션이 장치를 인식하지 못할 수 있습니다. 표준 HID 장치의 관례적 동작에 대한 자세한 내용은 [USBIF-HID-USAGE]를 참조하십시오.

device로부터 입력 리포트를 수신하면, 다음 단계를 수행합니다:

1. 입력 리포트가 blocked report이면, 이 단계를 중단합니다.
2. 이 리포트의 report ID를 reportId로 두고, HID interface가 use report IDs를 사용하지 않으면 0으로 둡니다.
3. 입력 리포트를 나타내는 byte sequence 위에 생성된 DataView를 data로 둡니다. HID interface가 uses report IDs를 사용하는 경우, 이 byte sequence에는 리포트 ID 바이트가 MUST NOT 포함되면 안 됩니다.
4. Queue a global task를 관련 글로벌 객체에서 this에 대해 HID device task source를 사용하여 큐잉하고, fire an event로 inputreport라는 이름의 이벤트를 device에서 발행합니다. 이때 HIDInputReportEvent를 사용하고, 그 device 속성은 device로, reportId 속성은 reportId로, data 속성은 data로 초기화합니다.

WebIDL[Exposed=(DedicatedWorker,ServiceWorker,Window), SecureContext]
interface HIDConnectionEvent : Event {
    constructor(DOMString type, HIDConnectionEventInit eventInitDict);
    [SameObject] readonly attribute HIDDevice device;
};

device 속성

연결되었거나 연결이 해제된 장치를 나타내는 HIDDevice 인스턴스입니다.

WebIDLdictionary HIDConnectionEventInit : EventInit {
    required HIDDevice device;
};

WebIDL[Exposed=(DedicatedWorker,ServiceWorker,Window), SecureContext]
interface HIDInputReportEvent : Event {
    constructor(DOMString type, HIDInputReportEventInit eventInitDict);
    [SameObject] readonly attribute HIDDevice device;
    readonly attribute octet reportId;
    readonly attribute DataView data;
};

device 속성

입력 리포트를 보낸 HID 인터페이스를 나타내는 HIDDevice 인스턴스입니다.

reportId 속성

이 리포트의 1바이트 식별 접두사이며, HID 인터페이스가 report ID를 사용하지 않으면 0입니다.

data 속성

입력 리포트에서 가져온 데이터를 포함하는 DataView입니다. HID 인터페이스가 report ID를 사용한다면 reportId 바이트는 제외됩니다.

WebIDLdictionary HIDInputReportEventInit : EventInit {
    required HIDDevice device;
    required octet reportId;
    required DataView data;
};

WebIDLdictionary HIDCollectionInfo {
    unsigned short usagePage;
    unsigned short usage;
    octet type;
    sequence<HIDCollectionInfo> children;
    sequence<HIDReportInfo> inputReports;
    sequence<HIDReportInfo> outputReports;
    sequence<HIDReportInfo> featureReports;
};

장치가 시스템에 처음 연결되면, 시스템은 장치가 노출하는 각 HID 인터페이스에 대한 리포트 디스크립터를 MUST 가져와야 합니다. Report descriptor는 각 리포트의 레이아웃을 설명하는 계층적 데이터 구조로 확장될 수 있는 바이트 시퀀스입니다. 이 데이터 구조의 요소를 항목(items)이라 하며, 관계를 공유하는 항목들의 그룹을 컬렉션(collections)이라 합니다.

HIDCollectionInfo 객체는 리포트 디스크립터 내의 단일 컬렉션을 나타냅니다. 컬렉션이 중첩된 컬렉션을 포함하는 경우, 중첩된 컬렉션은 children의 요소로 포함됩니다.

inputReports, outputReports, featureReports 속성에는 이 컬렉션에 설명된 각 리포트에 대한 정보를 제공하는 시퀀스의 HIDReportInfo가 포함됩니다. 최상위(top-level) 컬렉션의 경우, HIDReportInfo는 리포트를 구성하는 모든 항목의 평탄화된 뷰를 나타냅니다. 평탄화된 뷰는 중첩된 컬렉션 내 항목과 최상위 컬렉션 내 항목을 교차 배치합니다. 중첩 컬렉션의 경우 HIDReportInfo에는 해당 컬렉션과 그 중첩 컬렉션에 포함된 항목만 포함됩니다.

usagePage 멤버

이 컬렉션과 연관된 HID usage의 usage page 구성요소입니다.

HID usages는 애플리케이션이 항목이나 컬렉션의 목적과 의미를 식별하는 데 사용할 수 있는 상수입니다. HID usage는 상위 비트의 unsigned short usage page와 하위 비트의 unsigned short usage ID로 구성된 unsigned long 값입니다. 표준 HID usage 값은 [USBIF-HID-CLASS] 및 USB Implementers Forum이 발행한 다른 문서에 설명되어 있습니다.

장치가 노출하는 최상위 컬렉션의 HID usage는 일반적인 장치 유형을 식별하는 데 사용됩니다.

usage 멤버

이 컬렉션과 연관된 HID usage의 usage ID 구성요소입니다.

usage ID는 usage page에서 개별 HID usage를 선택하는 데 사용됩니다. 관례적으로 usage ID 0x01~0x1F는 최상위 컬렉션을 위해 예약되어 있습니다.

type 멤버

컬렉션 타입을 나타내는 값입니다.

컬렉션 타입	값
물리(Physical)	0x00
애플리케이션(Application)	0x01
논리(Logical)	0x02
리포트(Report)	0x03
명명된 배열(Named Array)	0x04
사용 전환(Usage Switch)	0x05
사용 수정됨(Usage Modified)	0x06
향후 사용을 위해 예약(Reserved for future use)	0x07 to 0x7F
벤더 정의(Vendor-defined)	0x80 to 0xFF

각 컬렉션 타입은 그룹화된 항목 간의 서로 다른 관계를 설명합니다. USBIF-HID-CLASS의 6.2.2.6 절을 참고하여 컬렉션 타입에 대해 더 알아볼 수 있습니다.

children 멤버

이 컬렉션 내에 중첩된 컬렉션을 나타내는 시퀀스의 HIDCollectionInfo입니다.

inputReports 멤버

이 컬렉션에 설명된 입력 리포트를 나타내는 시퀀스의 HIDReportInfo입니다.

outputReports 멤버

이 컬렉션에 설명된 출력 리포트를 나타내는 시퀀스의 HIDReportInfo입니다.

featureReports 멤버

이 컬렉션에 설명된 기능(feature) 리포트를 나타내는 시퀀스의 HIDReportInfo입니다.

WebIDLdictionary HIDReportInfo {
    octet reportId;
    sequence<HIDReportItem> items;
};

HIDReportInfo는 리포트 디스크립터 내의 하나의 입력, 출력 또는 기능 리포트를 나타냅니다.

reportId 멤버

HID 인터페이스가 각 리포트 전송에 1바이트 식별 접두사를 앞에 붙이면 report ID를 사용합니다. 인터페이스가 report ID를 사용하는 경우 reportId 멤버는 이 리포트의 접두사이며, 그렇지 않으면 0입니다.

items 멤버

이 리포트의 필드를 나타내는 시퀀스의 HIDReportItem입니다.

WebIDLdictionary HIDReportItem {
    boolean isAbsolute;
    boolean isArray;
    boolean isBufferedBytes;
    boolean isConstant;
    boolean isLinear;
    boolean isRange;
    boolean isVolatile;
    boolean hasNull;
    boolean hasPreferredState;
    boolean wrap;
    sequence<unsigned long> usages;
    unsigned long usageMinimum;
    unsigned long usageMaximum;
    unsigned short reportSize;
    unsigned short reportCount;
    byte unitExponent;
    HIDUnitSystem unitSystem;
    byte unitFactorLengthExponent;
    byte unitFactorMassExponent;
    byte unitFactorTimeExponent;
    byte unitFactorTemperatureExponent;
    byte unitFactorCurrentExponent;
    byte unitFactorLuminousIntensityExponent;
    long logicalMinimum;
    long logicalMaximum;
    long physicalMinimum;
    long physicalMaximum;
    sequence<DOMString> strings;
};

isAbsolute 멤버

데이터가 고정 원점에 기반한 절대값이면 true, 마지막 리포트로부터의 값 변화를 나타내는 상대값이면 false입니다.

isArray 멤버

각 데이터 필드에 눌린 버튼이나 키에 해당하는 인덱스를 포함하는 배열 데이터 필드를 리포트에 생성하면 true, 각 데이터 필드가 값을 포함하는 변수 데이터 필드를 리포트에 생성하면 false입니다.

isBufferedBytes 멤버

항목이 고정 크기의 바이트 스트림을 내보내면 true, 항목이 수치형 값이면 false입니다.

isConstant 멤버

항목이 수정할 수 없는 정적 읽기 전용 필드이면 true, 수정 가능한 장치 데이터를 포함하는 리포트 필드를 정의하면 false입니다.

isLinear 멤버

항목이 측정값과 보고값 사이의 선형 관계를 나타내면 true, 데이터가 어떤 방식으로든 처리되었으면 false입니다.

isRange 멤버

항목이 HID usage 범위에서 usageMinimum과 usageMaximum으로 정의된 사용값을 할당하면 true, 항목에 시퀀스의 HID usage 값이 usages에 있으면 false입니다.

isVolatile 멤버

호스트의 상호작용 없이 항목 값이 변경될 수 있으면 true, 항목 값이 오직 호스트에 의해서만 변경되어야 하면 false입니다.

기능(Feature) 및 출력(Output) 항목에만 사용됩니다.

hasNull 멤버

항목에 의미 있는 데이터를 보내지 않는 널(null) 상태가 있으면 true, 없으면 false입니다. 널 상태에서는 항목이 지정된 logicalMinimum 및 logicalMaximum 범위를 벗어난 값을 보고합니다.

hasPreferredState 멤버

사용자가 컨트롤을 물리적으로 조작하지 않을 때 항목이 돌아갈 선호 상태가 있으면 true, 없으면 false입니다.

wrap 멤버

항목 값이 최대 또는 최소 극값에 도달했을 때 롤오버되면 true, 롤오버되지 않으면 false입니다.

usages 멤버

isRange가 true이거나 이 항목에 연관된 HID usage 값이 없다면, usages는 MUST 미정의(undefined)여야 합니다.

isRange가 false이면 usages는 이 항목과 연관된 HID usage 값의 시퀀스입니다.

usageMinimum 멤버

isRange가 true이면 usageMinimum에는 이 항목과 연관된 사용 범위의 최소 HID usage 값이 포함됩니다.

isRange가 false이면 usageMinimum은 MUST 미정의(undefined)여야 합니다.

usageMaximum 멤버

isRange가 true이면 usageMaximum에는 이 항목과 연관된 사용 범위의 최대 HID usage 값이 포함됩니다.

isRange가 false이면 usageMaximum은 MUST 미정의(undefined)여야 합니다.

reportSize 멤버

각 리포트 데이터 필드의 크기(비트)입니다. reportSize는 MUST 0보다 커야 합니다.

reportCount 멤버

이 항목에 대해 리포트에 포함되는 필드의 개수입니다. reportCount는 MUST 0보다 커야 합니다.

unitExponent 멤버

단위 지수 값입니다. 항목에 단위 정의가 없으면 0입니다.

unitSystem 멤버

단위 정의의 단위계를 지정하는 HIDUnitSystem 열거값이며, 항목에 단위 정의가 없으면 "none"입니다.

unitFactorLengthExponent 멤버

단위 정의에서 길이 단위(센티미터, 라디안, 인치, 도)의 지수 값이며, 항목에 단위 정의가 없으면 0입니다.

unitFactorMassExponent 멤버

단위 정의에서 질량 단위(그램 또는 슬러그)의 지수 값이며, 항목에 단위 정의가 없으면 0입니다.

unitFactorTimeExponent 멤버

단위 정의에서 시간 단위(초)의 지수 값이며, 항목에 단위 정의가 없으면 0입니다.

unitFactorTemperatureExponent 멤버

단위 정의에서 온도 단위(켈빈 또는 화씨)의 지수 값이며, 항목에 단위 정의가 없으면 0입니다.

unitFactorCurrentExponent 멤버

단위 정의에서 전류 단위(암페어)의 지수 값이며, 항목에 단위 정의가 없으면 0입니다.

unitFactorLuminousIntensityExponent 멤버

단위 정의에서 광도 단위(칸델라)의 지수 값이며, 항목에 단위 정의가 없으면 0입니다.

logicalMinimum 멤버

논리 단위에서 이 항목의 최소 범위입니다. 변수 또는 배열 항목이 보고할 최소값입니다.

logicalMaximum 멤버

논리 단위에서 이 항목의 최대 범위입니다. 변수 또는 배열 항목이 보고할 최대값입니다.

physicalMinimum 멤버

이 항목의 물리적 범위에 대한 최소값입니다. 이는 단위를 적용한 logicalMinimum을 의미합니다.

physicalMaximum 멤버

이 항목의 물리적 범위에 대한 최대값입니다. 이는 단위를 적용한 logicalMaximum을 의미합니다.

strings 멤버

이 항목과 연관된 문자열이며, 연관된 문자열이 없으면 빈 시퀀스입니다.

[USBIF-HID-CLASS] 6.2.2.7 절은 네 가지 표준 단위계를 정의합니다: SI 선형, SI 회전, 영국식 선형, 영국식 회전. 각 항목은 이 네 가지 단위계 중 하나, 벤더 정의 단위계, 또는 단위계 없음 중 하나를 사용합니다.

WebIDLenum HIDUnitSystem {
    "none", "si-linear", "si-rotation", "english-linear",
    "english-rotation", "vendor-defined", "reserved"
};

"none"

단위계 없음. 항목에 단위 정의가 없음을 나타냅니다.

"si-linear"

SI 선형 단위계는 센티미터, 그램, 초, 켈빈, 암페어, 칸델라를 사용합니다.

"si-rotation"

SI 회전 단위계는 라디안, 그램, 초, 켈빈, 암페어, 칸델라를 사용합니다.

"english-linear"

영국식 선형 단위계는 인치, 슬러그, 초, 화씨 도, 암페어, 칸델라를 사용합니다.

"english-rotation"

영국식 회전 단위계는 도, 슬러그, 초, 화씨 도, 암페어, 칸델라를 사용합니다.

"vendor-defined"

벤더 정의 단위계입니다.

"reserved"

장치가 단위계에 대해 예약된 값을 사용했음을 나타냅니다.

이 명세는 웹사이트가 접근할 수 있는 HID 장치 집합을 제한하기 위해 https://github.com/WICG/webhid 리포지토리의 차단 목록 파일에 의존합니다.

url에서 차단 목록을 파싱한 결과는 시퀀스의 딕셔너리 객체로, url을 가져와서 그 내용을 JSON으로 파싱함으로써 생성됩니다.

HID 차단 목록은 차단 목록을 파싱한 결과이며, 위치는 https://github.com/WICG/webhid/blob/main/blocklist.txt 입니다.

다음 단계가 true를 반환하면, 리포트는 차단된 리포트입니다:

1. 각각의 HID 차단 목록의 rule에 대해:
   1. 리포트가 rule에 의해 차단 목록 규칙에 의해 차단된다면 true를 반환합니다.
2. false를 반환합니다.

다음 단계가 true를 반환하면, 리포트는 rule에 의해 차단 목록 규칙에 의해 차단됩니다:

1. 리포트의 리포트 ID를 reportId로 두고, HID 인터페이스가 report ID를 사용하지 않으면 0으로 둡니다.
2. 리포트가 입력 리포트이면 reportType을 "input"으로, 출력 리포트이면 "output"으로, 기능 리포트이면 "feature"로 둡니다.
3. 리포트를 포함하는 최상위 컬렉션을 collection으로 둡니다.
4. rule에 "vendor"가 포함되어 있고 rule["vendor"]가 device.vendorId와 다르면 false를 반환합니다.
5. rule에 "product"가 포함되어 있고 rule["product"]가 device.productId와 다르면 false를 반환합니다.
6. rule에 "reportId"가 포함되어 있고 rule["reportId"]가 reportId와 다르면 false를 반환합니다.
7. rule에 "reportType"가 포함되어 있고 rule["reportType"]가 reportType과 다르면 false를 반환합니다.
8. rule에 "usagePage"가 포함되어 있고 rule["usagePage"]가 collection["usagePage"]와 다르면 false를 반환합니다.
9. rule에 "usage"가 포함되어 있고 rule.["usage"]가 collection["usage"]와 다르면 false를 반환합니다.
10. true를 반환합니다.

비규범적(non-normative)으로 표시된 절뿐만 아니라, 이 명세의 모든 작성 지침, 다이어그램, 예제, 주석은 비규범적입니다. 그 외 이 명세의 모든 내용은 규범적입니다.

이 문서의 MAY, MUST, MUST NOT, SHOULD, SHOULD NOT 키워드는 BCP 14 [RFC2119] [RFC8174] 에서 설명된 대로, 그리고 오직 여기에서처럼 모두 대문자로 나타날 때에만 해석되어야 합니다.