WebHID

현행 표준 — 최종 갱신:

참여:
GitHub whatwg/hid (새 이슈, 열린 이슈)
Matrix에서 대화하기
커밋:
GitHub whatwg/hid/commits
이 커밋 시점의 스냅숏
테스트:
web-platform-tests hid/ (진행 중인 작업)
번역 (비규범적):
简体中文
日本語
한국어

초록

이 문서는 인간 인터페이스 장치(Human Interface Device, HID) 프로토콜을 지원하는 장치에 대한 접근을 제공하는 API를 설명한다.

1. 소개

이 절은 비규범적이다.

HID(Human Interface Device, 인간 인터페이스 장치)는 사람에게서 입력을 받거나 사람에게 출력을 제공하는 장치의 한 유형이다. HID는 호스트와 장치 간의 양방향 통신을 위한 표준인 HID 프로토콜을 가리키기도 한다. 이 프로토콜은 설치 절차를 간소화하도록 설계되었다. HID 프로토콜은 원래 USB 장치용으로 개발되었지만 이후 Bluetooth를 포함한 여러 다른 프로토콜에서도 구현되었다.

웹 플랫폼은 이미 많은 HID 장치의 입력을 지원한다. 키보드, 포인팅 장치, 게임패드는 보통 HID 프로토콜로 구현된다. 그러나 이 지원은 HID 입력을 고수준 입력 API로 변환하는 운영체제의 HID 드라이버에 의존한다. 호스트의 HID 드라이버가 충분히 지원하지 않는 장치는 웹페이지에서 접근할 수 없는 경우가 많다. 마찬가지로 호스트의 HID 드라이버가 지원하지 않는 대부분의 장치 출력에도 접근할 수 없다.

관련 해설 문서도 참고한다.

2. 도입 동기가 되는 응용 사례

이 절은 비규범적이다.

2.1. 특수 용도 장치

가장 일반적인 HID 입력 장치 유형은 기존 고수준 입력 API를 통해 웹 플랫폼에서 이미 충분히 지원된다. 예를 들어 마우스 입력은 PointerEvent을 통해, 키보드 입력은 KeyboardEvent을 통해 접근할 수 있다. 이러한 장치의 입력은 호스트의 기본 HID 드라이버로 처리하며, 올바른 동작을 위해 보통 장치별 드라이버나 설정이 필요하지 않다. WebHID는 이처럼 고수준 입력 API로 이미 충분히 지원되는 장치를 위한 것이 아니다.

일부 HID 장치 유형에 대해서는 웹 플랫폼이 특정 기능은 지원하면서 다른 기능의 접근은 제한한다. 예를 들어 [GAMEPAD]는 대부분의 게임 컨트롤러의 입력 기능은 지원하지만 LED 표시등이나 오디오처럼 덜 일반적인 기능은 지원하지 않는다. 이러한 기능은 호스트 API가 충분히 지원하지 않는 경우가 많고, 사용자 에이전트에 지원을 추가하면 상당한 복잡성을 초래할 수 있다. WebHID는 고수준 API가 제공하는 기능이 불완전할 때 응용 프로그램에 대안을 제공한다.

많은 HID 장치는 어떤 웹 플랫폼 API로도 지원되지 않는다. HID 명세는 가상현실 제어 장치, 비행 시뮬레이터, 의료 장비 등을 포함해 HID로 지원할 수 있는 다양한 장치를 설명한다. WebHID는 추가 드라이버나 사용자 에이전트의 수정 없이 이러한 장치를 사용할 수 있게 한다.

2.2. 시제품 제작, 취미 및 교육용 장치

HID는 장치를 사용할 각 호스트마다 별도의 드라이버를 요구하지 않고 호스트의 범용 HID 드라이버를 사용할 수 있어 시제품 제작과 취미용 응용에 매력적이다. 간소화된 설치 절차 덕분에 교육자도 각 호스트의 시스템 설정을 수정하지 않고 교실의 학생들에게 장치를 배포하기 쉽다. 웹 플랫폼을 통해 HID 장치 접근을 제공하면 설치 요구사항을 더욱 줄일 수 있다. 특히 현재 호스트별 전용 응용 프로그램으로만 지원되는 장치에 유용하다.

3. 보안 및 개인정보 보호 고려사항

이 절은 비규범적이다.

3.1. 장치 접근 권한의 악용

HID 주변 장치는 강력한 기능을 노출할 수 있으며, 사용자의 명시적 동의 없이 페이지가 이를 사용하도록 해서는 안 된다. 예를 들어 HID 주변 장치에는 주변 환경 정보를 수집하는 센서가 있을 수 있다. 장치에는 공개하거나 덮어쓰면 안 되는 개인정보가 저장되어 있을 수 있다. 많은 장치는 펌웨어를 업그레이드하는 기능을 노출한다. 운영체제는 보통 응용 프로그램의 HID 장치 접근을 제한하지 않으며, 때로는 이 접근이 장치를 손상시키거나 저장된 데이터를 훼손하는 데 악용될 수 있다.

어떤 경우에는 장치가 웹페이지에서 전혀 접근해서는 안 되는 기능을 노출할 수 있다. 특정 장치는 공급업체 ID와 제품 ID로 식별하고 열거 과정에서 숨겨 차단할 수 있다. 보고서 설명자를 통해 장치가 자체 기능을 설명할 수 있으므로, 공급업체 ID와 제품 ID를 미리 알 수 없어도 이 정보로 장치 유형을 차단할 수 있다. 이를 위해 HID 용도 값, 즉 보고서 설명자 내 컬렉션에 할당된 값을 검사한다. 예를 들어 최상위 컬렉션에 키보드용 HID 용도가 지정된 장치의 접근을 거부하여 키보드와 유사한 장치의 접근을 차단할 수 있다.

악용을 줄이기 위해 사용자가 명시적으로 접근을 허용하기 전에는 페이지에 장치를 제공하지 않는다. 페이지가 먼저 접근을 요청해야 하며, 사용 가능한 모든 장치를 표시하는 선택기에서 사용자가 장치를 선택하면 권한이 부여된다. 페이지에 접근 권한이 부여되면 장치가 사용 중임을 나타내는 표시기를 보여 준다.

3.2. 장치 공격

HID 프로토콜은 매우 유연하며, 그 유연성을 활용하는 다양한 장치가 설계되어 왔다. 따라서 악성 페이지가 장치에 접근하여 장치 자체를 손상시키는 방식도 다양할 수 있다. HID 주변 장치가 사용자 정의 HID 보고서로 펌웨어 업데이트를 받도록 하는 것은 비교적 흔하다. 장치 제조업체는 펌웨어 바이너리의 진위를 검증하도록 펌웨어 업그레이드 절차를 신중하게 설계해야 하며, 장치의 보안을 약화할 수 있는 다운그레이드도 방지하는 것이 좋다. 신뢰할 수 없는 업그레이드는 장치에 새로운 기능을 추가하거나 완전히 다른 유형의 장치로 위장시키는 데 사용될 수 있다.

예상 범위를 벗어난 입력이 제공되면 손상되는 장치도 있다. 예를 들어 페이지가 잘못된 진동 명령을 보내면 게임패드의 진동 기능이 손상될 수 있다.

일반적으로 이러한 공격은 장치에 종속적이며 API 수준에서 완화할 수 없다.

3.3. 호스트 공격

악성 페이지가 장치 접근 권한을 얻으면 경우에 따라 이를 호스트 공격에 사용할 수 있다. 주요 우려 사항은 장치가 신뢰할 수 있는 입력 이벤트를 생성하는 데 사용될 수 있는지 여부이다. 이러한 이벤트는 사용자 의사를 대신 나타내며 더 강력한 웹 플랫폼 기능에 접근하는 데 사용될 수 있다.

마우스와 키보드는 보통 HID 주변 장치로 구현되며 신뢰할 수 있는 입력도 생성할 수 있다. HID 키보드나 마우스에는 입력 시퀀스를 저장했다가 나중에 재생할 수 있는 프로그래밍 가능한 매크로와 같은 고급 기능이 있을 수 있다. 장치 제조업체는 악성 앱이 예상치 못한 입력 시퀀스로 장치를 재프로그래밍하지 못하도록 이러한 기능을 신중히 설계해야 한다. 또한 사용자의 명시적 동의 없이 매크로 재생이 시작되지 않도록 보호해야 한다.

3.4. 완화 대책

보안 및 개인정보 보호 위험을 줄이기 위해 사용자 에이전트는 장치 접근 요청에 선택기 기반 흐름을 구현할 것을 권장한다. 페이지가 HID 장치 접근을 요청하면 사용자 에이전트는 페이지가 장치에 접근하려 한다는 사실을 알리는 대화 상자를 표시하는 것이 좋다. 대화 상자에는 연결된 HID 장치의 목록을 표시하고 페이지에 노출할 장치를 선택하도록 요청하는 것이 좋다. 실수로 클릭할 가능성을 줄이기 위해 대화 상자는 두 번의 별도 상호작용을 요구하는 것이 좋다. 첫 번째는 목록에서 장치를 선택하는 동작이고, 두 번째는 선택을 확인하고 대화 상자를 닫는 동작이다.

4. 확장 대상: Navigator 인터페이스

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

4.1. hid 속성

hid 속성을 가져올 때는 언제나 HID 객체의 동일한 인스턴스를 반환한다.

5. 확장 대상: WorkerNavigator 인터페이스

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

5.1. hid 속성

hid 속성을 가져올 때는 언제나 HID 객체의 동일한 인스턴스를 반환한다.

6. HID 인터페이스

[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 속성(소유 객체: Navigator)이며, 관련 전역 객체(소유 객체: Navigator)가 ServiceWorkerGlobalScope인 경우에 해당한다. 예를 들어 브라우저 확장 컨텍스트가 이에 해당하며, [browserext]에서 설명한다.

HID의 인스턴스는 다음 표에서 설명하는 내부 슬롯을 갖도록 생성한다:

내부 슬롯 초깃값 설명(비규범적)
[[devices]] 비어 있는 순서 있는 집합 하나의 순서 있는 집합 구성 요소: HIDDevice 인스턴스. 다음을 나타낸다: HID 인터페이스 현재 시스템에서 사용할 수 있는 인터페이스이다.
onconnect 속성, 자료형: EventHandler
onconnect 해당 속성은 이벤트 처리기 IDL 속성 이며 다음의 connect 이벤트 유형에 대응한다.
ondisconnect 속성, 자료형: EventHandler
ondisconnect 해당 속성은 이벤트 처리기 IDL 속성 이며 다음의 disconnect 이벤트 유형에 대응한다.
다음의 HID 인터페이스 를 시스템에서 사용할 수 있게 되면 다음 단계를 실행한다:
하나의 HID 인터페이스 는 HID 프로토콜로 장치와 통신하기 위한 논리적 인터페이스이다. 각 HID 인터페이스 에는 정확히 하나의 보고서 설명자 가 있으며, 이는 해당 인터페이스가 지원하는 보고서 집합을 설명한다. 하나의 물리적 장치는 노출할 수 있다 : 둘 이상의 HID 인터페이스. 장치에 여러 개의 HID 인터페이스 가 있으면 각 인터페이스에 대해 이 단계들을 한 번씩 실행한다.

예를 들어 USB 장치는 인터페이스의 집합으로 구현되며 각 인터페이스는 인터페이스 클래스를 지정할 수 있다. 장치에 HID 클래스를 사용하는 USB 인터페이스가 여러 개 있으면 각 인터페이스는 별개의 HID 인터페이스로 열거된다.

  1. device을(를) HIDDevice(으)로 둔다.

  2. device.[[vendorId]]의 값을 해당 인터페이스를 노출하는 장치의 공급업체 ID로 설정한다.

  3. device.[[productId]]의 값을 해당 인터페이스를 노출하는 장치의 제품 ID로 설정한다.

  4. device.[[productName]]의 값을 해당 인터페이스를 노출하는 장치의 제품 이름으로 설정한다.

  5. device.[[collections]]의 값을 보고서 설명자 파싱의 결과로 설정한다.

  6. hid을(를) 다음 호출의 결과로 둔다: device의 관련 전역 객체의 Navigator 객체의 hid 게터. 이는 device의 관련 전역 객체가 Window 객체일 때 해당한다. 그렇지 않으면 device의 관련 전역 객체의 WorkerNavigator 객체의 hid 게터를 호출한 결과로 둔다.

  7. 추가한다: device을(를) hid.[[devices]]에 추가한다.

  8. 사용자가 사이트의 device 접근을 이전의 requestDevice() 호출 결과로 허용했다면 전역 태스크를 큐에 넣는다. 대상 관련 전역 객체의 소유자는 hid이며 HID 장치 태스크 소스를 사용한다. 이 태스크는 이벤트를 발생시킨다. 이름은 connect, 대상은 hid, 사용 인터페이스는 HIDConnectionEvent이며, device 속성을 device(으)로 초기화한다.

다음을 수행하려면: 보고서 설명자 파싱다음 단계를 실행한다:
시스템은 일반적으로 다음을 읽는다: 보고서 설명자 바이트 시퀀스 그 대상은 각각의 HID 인터페이스 이다. 장치가 처음 연결될 때 이를 읽고 값을 시스템 레지스트리에 캐시한다. 만약 보고서 설명자 를 사용할 수 없지만 시스템이 각 보고서의 배치를 재구성하는 데 사용할 수 있는 정보를 제공한다면 사용자 에이전트는 할 수 있다 : 다음을 파싱하는 대신 다른 알고리즘을 사용할 수 있다. 파싱 대상은 보고서 설명자.

보고서 설명자 형식은 [USBIF-HID-CLASS]의 6.2.2절에서 설명한다. 아래 알고리즘은 해당 절에 기술된 것과 동일한 파싱 알고리즘을 구현하기 위한 것이다.

보고서 설명자에는 세 종류의 항목이 들어 있다. 주 항목은 데이터 필드를 정의하고 묶는 데 사용한다. 전역 항목과 지역 항목은 데이터 필드를 설명한다. 지역 항목은 바로 다음 주 항목에만 적용되는 특성을 정의하는 반면, 전역 항목은 이후에 정의되는 모든 주 항목에 영향을 주는 특성을 정의한다.

각 항목에는 항목 데이터 필드가 있으며, 항목과 관련된 0, 1, 2 또는 4바이트의 데이터를 담는다. 또한 bSize 필드가 있어 항목 데이터 필드를 저장하는 데 사용하는 바이트 수를 설명한다. 각 항목에는 유형을 식별하는 태그도 있다.

  1. items을(를) 보고서 설명자의 바이트 시퀀스를 리스트로 변환한 결과로 둔다. 이 리스트는 주 항목, 전역 항목 및 지역 항목으로 구성된다.

  2. collections을(를) 비어 있는 시퀀스(원소 유형: HIDCollectionInfo)로 초기화한다.

  3. ancestors을(를) 비어 있는 리스트로 초기화한다.

  4. localState을(를) 비어 있는 순서 있는 맵으로 초기화한다.

  5. usages을(를) 비어 있는 시퀀스(원소 유형: unsigned long)로 초기화한다.

  6. stringIndices을(를) 비어 있는 리스트로 초기화한다.

  7. globalStack을(를) 비어 있는 스택으로 초기화한다.

  8. initialGlobalState을(를) 비어 있는 순서 있는 맵으로 초기화한다.

  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. 각각에 대해, 즉 item(대상: items)마다:

    참고: 주 항목은 [USBIF-HID-CLASS]의 6.2.2.4절부터 6.2.2.6절까지에서 설명한다. Input 태그, Output 태그 또는 Feature 태그가 있는 항목은 입력, 출력 또는 기능 보고서의 필드를 정의한다. 항목 데이터 필드는, 주 항목에 Input 태그, Output 태그 또는 Feature 태그가 있는 경우, 데이터 필드를 설명하는 여러 불리언 매개변수를 담은 비트 필드이다. Collection 태그가 있는 항목은 현재 컬렉션 안에 중첩된 새 컬렉션을 정의하며, 현재 컬렉션이 없으면 새 최상위 컬렉션을 정의한다. 항목 데이터 필드는, 주 항목에 Collection 태그가 있는 경우, 컬렉션 유형을 담는다. End Collection 태그가 있는 항목은 현재 컬렉션을 닫는다.

다음을 수행하려면: HID 보고서 항목 생성 입력: item, localState, globalState, usages및 stringIndices다음 단계를 실행한다:

  1. reportItem을(를) 새 HIDReportItem 딕셔너리로 둔다.

  2. value을(를) 항목 데이터 필드를 unsigned long(으)로 해석한 값으로 둔다.

  3. bitfield을(를) 리스트로 둔다. 원소는 boolean 값이며, value의 각 비트를 하위 비트부터 나타낸다.

  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. reportItem["physicalMinimum"]의 값을 globalState["physicalMinimum"]로 설정한다.

  27. reportItem["physicalMaximum"]의 값을 globalState["physicalMaximum"]로 설정한다.

  28. "usageMinimum"과 "usageMaximum"이 모두 localState에 있고 localState["usageMinimum"]의 값이 localState["usageMaximum"]의 값보다 작거나 같으면 reportItem["isRange"]의 값을 true로 설정하고, 그렇지 않으면 false로 설정한다.

  29. reportItem["isRange"]의 값이 true이면 reportItem["usageMinimum"]의 값을 localState["usageMinimum"]로 설정한다.

  30. reportItem["isRange"]의 값이 true이면 reportItem["usageMaximum"]의 값을 localState["usageMaximum"]로 설정한다.

  31. "stringMinimum"이(가) localState에 있고 "stringMaximum"이(가) localState에 있으면:

    1. 추가한다: 다음 항목들을 추가한다. 범위는 localState["stringMinimum"]부터 localState["stringMaximum"]까지이며, 추가 대상은 stringIndices이다.

  32. 각각에 대해, 즉 stringIndex(대상: stringIndices)마다:

    1. string을(를) 인덱스 stringIndex의 문자열 설명자를 읽은 결과로 둔다.

    2. 추가한다: string을(를) reportItem["strings"]에 추가한다.

  33. reportItem을(를) 반환한다.

다음의 HID 인터페이스 를 시스템에서 더 이상 사용할 수 없게 되면 다음 단계를 실행한다:

  1. device을(를) HIDDevice로 둔다. 이는 hid.[[devices]]에 있으며 해당 인터페이스를 나타낸다.

  2. hid을(를) 다음 호출의 결과로 둔다: device의 관련 전역 객체의 Navigator 객체의 hid 게터. 이는 device의 관련 전역 객체가 Window 객체일 때 해당한다. 그렇지 않으면 device의 관련 전역 객체의 WorkerNavigator 객체의 hid 게터를 호출한 결과로 둔다.

  3. 제거한다: device을(를) hid.[[devices]]에서 제거한다.

  4. 사용자가 사이트의 device 접근을 이전의 requestDevice() 호출 결과로 허용했다면 전역 태스크를 큐에 넣는다. 대상 관련 전역 객체의 소유자는 hid이며 HID 장치 태스크 소스를 사용한다. 이 태스크는 이벤트를 발생시킨다. 이름은 disconnect, 대상은 hid, 사용 인터페이스는 HIDConnectionEvent이며, device 속성을 device(으)로 초기화한다.

6.1. getDevices() 메서드

다음의 getDevices() 메서드 단계는 다음과 같다:

  1. promise을(를) 새 프로미스로 둔다.

  2. document을(를) null(으)로 둔다.

  3. this의 관련 전역 객체가 DedicatedWorkerGlobalScope 또는 window 객체이면 document을(를) this의 관련 전역 객체의 연결된 Document로 설정한다.

  4. this의 관련 전역 객체가 ServiceWorkerGlobalScope 객체이고 연결된 서비스 워커 클라이언트가 윈도 클라이언트이면 document을(를) 연결된 Document로 설정한다. 이는 연결된 서비스 워커 클라이언트의 전역 객체에 연결된 문서이다.

  5. document이(가) null이거나, document에 사용이 허용되지 않은 정책 제어 기능의 이름이 "hid"이면 거부한다. 즉, promise을(를) "SecurityError" DOMException(으)로 거부하고 promise을(를) 반환한다.

  6. 다음 단계를 병렬로 실행한다:

    1. devices을(를) 비어 있는 시퀀스(원소 유형: HIDDevice)로 둔다.

    2. 각각에 대해, 즉 device(대상: this.[[devices]])마다:

      1. 사용자가 사이트의 device 접근을 이전의 requestDevice() 호출 결과로 허용했고 device.[[state]]이(가) "forgotten"이 아니면 추가한다. 즉, device을(를) devices에 추가한다.

    3. 전역 태스크를 큐에 넣는다. 대상 관련 전역 객체의 소유자는 this이며, HID 장치 태스크 소스를 사용한다. 이 태스크는 이행한다. 즉, promise을(를) devices 값으로 이행한다.

  7. promise을(를) 반환한다.

6.2. requestDevice() 메서드

다음의 requestDevice() 권한 대화 상자는 연결된 장치의 목록을 표시하고 사용자에게 하나를 선택하도록 요청한다.

장치에 여러 HID 인터페이스가 있으면 대화 상자는 하나의 항목만 표시할 수 있다. 그 항목은 모든 인터페이스를 나타낸다. 사용자가 여러 HID 인터페이스를 나타내는 항목을 선택하면 사용자 에이전트는 접근을 허용해야 한다. 허용 대상은 장치가 노출하는 모든 HID 인터페이스이다.

다음의 requestDevice() 메서드 단계는 다음과 같다:

  1. promise을(를) 새 프로미스로 둔다.

  2. this의 관련 전역 객체의 연결된 Document에 사용이 허용되지 않은 정책 제어 기능의 이름이 "hid"이면 거부한다. 즉, promise을(를) "SecurityError" DOMException(으)로 거부하고 promise을(를) 반환한다.

  3. 관련 전역 객체(소유 객체: this)가 window가 아니면 거부한다. 즉, promise을(를) "NotSupportedError" DOMException(으)로 거부하고 promise을(를) 반환한다.

  4. 관련 전역 객체(소유 객체: this)에 일시적 활성화가 없으면 거부한다. 즉, promise을(를) "SecurityError" DOMException(으)로 거부하고 promise을(를) 반환한다.

  5. options["filters"]이(가) 있으면 다음 단계를 각각에 대해 실행한다. 즉, filter(대상: options["filters"])마다 실행한다:

    1. filter이(가) 유효한 필터가 아니면 거부한다. 즉, promise을(를) TypeError(으)로 거부하고 promise을(를) 반환한다.

  6. options["exclusionFilters"]이(가) 있으면 다음 단계를 실행한다:

    1. options["exclusionFilters"]이(가) 비어 있으면 거부한다. 즉, promise을(를) TypeError(으)로 거부하고 promise을(를) 반환한다.

    2. 각각에 대해, 즉 exclusionFilter(대상: options["exclusionFilters"])마다:

      1. exclusionFilter이(가) 유효한 필터가 아니면 거부한다. 즉, promise을(를) TypeError(으)로 거부하고 promise을(를) 반환한다.

  7. 다음 단계를 병렬로 실행한다:

    1. availableDevices을(를) 비어 있는 리스트로 초기화한다.

    2. 각각에 대해, 즉 device(대상: this.[[devices]])마다:

      1. device이(가) 하나 이상의 필터와 일치하고(필터 목록: options["filters"]), device이(가) 어떤 필터와도 일치하지 않으면(필터 목록: options["exclusionFilters"]), 추가한다. 즉, device을(를) availableDevices에 추가한다.

    3. availableDevices의 장치 목록을 표시하여 사용자에게 이 사이트가 HID 장치에 접근하도록 허용할 것을 요청한다.

      참고: 사용자 에이전트는 사용자에게 표시하기 전에 장치 목록을 수정할 수 있다. 예를 들어 여러 HID 인터페이스를 가진 장치는 하나의 항목으로 나타내는 것이 좋다. 이 항목을 선택하면 장치가 노출하는 모든 인터페이스에 접근할 수 있도록 한다. 장치가 단일 인터페이스로 구현되었는지 인터페이스 집합으로 구현되었는지는 사용자가 알지 못할 수 있는 구현 세부사항이며, 장치 접근 권한과 관련된 것으로 보지 않는 것이 좋다.

    4. devices을(를) 비어 있는 시퀀스(원소 유형: HIDDevice)로 둔다.

    5. 사용자가 장치를 선택하지 않으면 전역 태스크를 큐에 넣는다. 대상 관련 전역 객체의 소유자는 this이며, HID 장치 태스크 소스를 사용한다. 이 태스크는 이행한다. 즉, promise을(를) devices 값으로 이행한다. 그런 다음 이 단계를 중단한다.

    6. 각각에 대해, 즉 device(대상: this.[[devices]])마다:

      1. device이(가) 선택한 장치가 노출하는 HID 인터페이스를 나타내면 device.[[state]]의 값을 "closed"(으)로 설정하고 추가한다. 즉, device을(를) devices에 추가한다.

    7. 전역 태스크를 큐에 넣는다. 대상 관련 전역 객체의 소유자는 device이며, HID 장치 태스크 소스를 사용한다. 이 태스크는 이행한다. 즉, promise을(를) devices 값으로 이행한다.

  8. promise을(를) 반환한다.

6.2.1. HIDDeviceRequestOptions 딕셔너리

dictionary HIDDeviceRequestOptions {
    required sequence<HIDDeviceFilter> filters;
    sequence<HIDDeviceFilter> exclusionFilters;
};
filters 멤버, 시퀀스 자료형:<HIDDeviceFilter>
HID 장치용 필터.
exclusionFilters 멤버, 시퀀스 자료형:<HIDDeviceFilter>
HID 장치용 제외 필터.

6.2.2. HIDDeviceFilter 딕셔너리

dictionary HIDDeviceFilter {
    unsigned short vendorId;
    unsigned short productId;
    unsigned short usagePage;
    unsigned short usage;
};
vendorId 멤버, 자료형: unsigned short
다음의 공급업체 ID 와 일치시킨다.
productId 멤버, 자료형: unsigned short
다음의 제품 ID 와 일치시킨다. 다음의 vendorId 멤버가 없으면 productId 는 무시한다.
usagePage 멤버, 자료형: unsigned short
다음의 최상위 컬렉션 용도 페이지 와 일치시킨다.
usage 멤버, 자료형: unsigned short
다음의 최상위 컬렉션 용도 ID 와 일치시킨다. 다음의 usagePage 멤버가 없으면 usage 는 무시한다.
장치 필터는 다음이 만든 선택기 대화 상자에서 사용자에게 표시할 장치 목록을 좁히는 데 사용한다: requestDevice(). 필터가 없으면 어느 제외 필터에도 일치하지 않는 모든 연결된 장치를 포함한다. 필터가 하나 이상 있으면 필터 하나 이상에 일치하고 어느 제외 필터에도 일치하지 않는 장치를 포함한다.

모든 HIDDeviceFilter 멤버는 선택 사항이다. 각 멤버는 규칙 하나를 지정한다. HIDDeviceFilter에 일치하려면 모든 규칙을 만족해야 한다. 비어 있는 HIDDeviceFilter는 어떤 장치에나 일치한다.

장치 ID 규칙은 공급업체 ID와 제품 ID를 기준으로 장치를 선택하는 데 사용한다. 이는 응용 프로그램이 특정 장치에서만 작동하도록 설계되었거나 공급업체 고유 기능에 의존할 때 유용하다. vendorId 규칙을 포함하면 필터는 지정된 공급업체 ID를 갖는 장치에만 일치한다. productId 규칙도 포함하면 필터는 지정된 공급업체 ID와 제품 ID를 갖는 장치에만 일치한다. productId는 vendorId 규칙 없이 지정되면 무시한다.

용도 규칙은 HID 용도, 즉 장치의 최상위 컬렉션에 할당된 값을 기준으로 장치를 선택하는 데 사용한다. 이는 응용 프로그램이 표준 장치 유형과 작동하도록 설계되었을 때 유용하다. 장치에 일치하려면 장치의 컬렉션 중 적어도 하나는 모든 용도 규칙에 일치해야 한다. usagePage 규칙을 포함하면 필터는 장치에 지정된 용도 페이지를 갖는 컬렉션이 있을 때만 일치한다. usage 규칙도 포함하면 필터는 지정된 용도 페이지와 용도 ID를 갖는 장치에만 일치한다. usage는 usagePage 규칙 없이 지정되면 무시한다.

장치 ID 규칙과 용도 규칙은 결합할 수 있다. 예를 들어 응용 프로그램은 특정 공급업체의 장치 중에서도 특정 장치 클래스를 구현한 장치에만 일치시키려 할 수 있다.

exclusionFilters 옵션을 통해 응용 프로그램은 requestDevice()이(가) 만든 선택기 대화 상자에 표시되는 일부 장치를 제외할 수 있다. 이 장치들은 예를 들어 특정 장치 클래스를 구현하더라도 예상대로 작동하지 않는 것으로 알려져 있다.

다음의 HIDDeviceFilter filter 은(는) 다음에 해당한다: 유효한 필터 단, 다음 단계가 반환하는 값이 다음과 같아야 한다: true:

  1. filter이(가) 비어 있으면 false을(를) 반환한다.

  2. filter["productId"]이(가) 있고 filter["vendorId"]이(가) 없으면 false을(를) 반환한다.

  3. filter["usage"]이(가) 있고 filter["usagePage"]이(가) 없으면 false을(를) 반환한다.

  4. true을(를) 반환한다.

다음의 HIDDevice device 어느 필터에든 일치한다 그 대상은 다음이다: 시퀀스 filters 구성 요소: HIDDeviceFilter 단, 다음 단계가 반환하는 값이 다음과 같아야 한다: true:

  1. filters이(가) 비어 있으면 true을(를) 반환한다.

  2. 각각에 대해, 즉 filter(대상: filters)마다:

    1. filter이(가) 장치 ID와 일치하고(장치: device), filter이(가) 하나 이상의 컬렉션과 일치하면(컬렉션을 가진 장치: device), true을(를) 반환한다.

  3. false을(를) 반환한다.

다음의 HIDDeviceFilter filter 장치 ID에 일치한다 구성 요소: device 단, 다음 단계가 반환하는 값이 다음과 같아야 한다: true:

  1. "vendorId"이(가) filter에 있으면:

    1. filter["vendorId"]이(가) device.vendorId와 같지 않으면 false을(를) 반환한다.

    2. "productId"이(가) filter에 있고 filter["productId"]이(가) device.productId와 같지 않으면 false을(를) 반환한다.

  2. true을(를) 반환한다.

다음의 HIDDeviceFilter filter 어느 컬렉션에든 일치한다 구성 요소: device 단, 다음 단계가 반환하는 값이 다음과 같아야 한다: true:

  1. 각각에 대해, 즉 collection(대상: device.collections)마다:

    1. filter이(가) 컬렉션에 일치하고 그 컬렉션이 collection이면 true을(를) 반환한다.

  2. false을(를) 반환한다.

다음의 HIDDeviceFilter filter 컬렉션에 일치한다 collection 단, 다음 단계가 반환하는 값이 다음과 같아야 한다: true:

  1. "usagePage"이(가) filter에 있으면:

    1. filter["usagePage"]이(가) collection.usagePage와 같지 않으면 false을(를) 반환한다.

    2. "usage"이(가) filter에 있고 filter["usage"]이(가) collection.usage와 같지 않으면 false을(를) 반환한다.

  2. true을(를) 반환한다.

7. HIDDevice 인터페이스

[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 장치 태스크 소스에 작업을 큐에 넣는다.

HIDDevice의 인스턴스는 다음 표에서 설명하는 내부 슬롯을 갖도록 생성한다:

내부 슬롯 초깃값 설명(비규범적)
[[state]] "closed" 다음의 활성 상태를 추적한다: HIDDevice
[[vendorId]] 0 다음의 공급업체 ID 장치의 값이다.
[[productId]] 0 다음의 제품 ID 장치의 값이다.
[[productName]] "" 다음의 제품 이름 장치의 값이다.
[[collections]] 비어 있는 시퀀스 구성 요소: HIDCollectionInfo 다음의 최상위 컬렉션 생성 방법: 보고서 설명자 파싱
[[pendingSendReportPromises]] 비어 있는 리스트 대기 중인 sendReport() Promise들
[[pendingSendFeatureReportPromises]] 비어 있는 리스트 대기 중인 sendFeatureReport() Promise들
[[pendingReceiveFeatureReportPromises]] 비어 있는 리스트 대기 중인 receiveFeatureReport() Promise들
oninputreport 속성, 자료형: EventHandler
oninputreport 해당 속성은 이벤트 처리기 IDL 속성 이며 다음의 inputreport 이벤트 유형에 대응한다.
opened 속성, 자료형: boolean, 읽기 전용
다음의 상태를 나타내는 플래그: HIDDevice 데이터를 전송할 준비가 되었는지를 나타낸다.
다음의 opened 게터의 단계는 다음과 같다:

  1. this.[[state]]이(가) opened이면 true을(를) 반환한다.

  2. false을(를) 반환한다.

vendorId 속성, 자료형: unsigned short, 읽기 전용
다음의 공급업체 ID 해당 속성은 unsigned short 값. 공급업체 ID 발급 기관이 할당하며 장치 제조업체를 식별한다.

vendorId 속성은 장치의 공급업체 ID이다. 장치에 공급업체 ID가 없거나 공급업체 ID에 접근할 수 없으면 이 속성은 0이어야 한다.

다음의 vendorId 게터의 단계는 다음과 같다:

  1. this.[[vendorId]]을(를) 반환한다.

productId 속성, 자료형: unsigned short, 읽기 전용
다음의 제품 ID 해당 속성은 unsigned short 값. 장치 제조업체가 할당하며 제품을 식별한다.

productId 속성은 장치의 제품 ID이다. 장치에 제품 ID가 없거나 제품 ID에 접근할 수 없으면 이 속성은 0이어야 한다.

다음의 productId 게터의 단계는 다음과 같다:

  1. this.[[productId]]을(를) 반환한다.

productName 속성, 자료형: DOMString, 읽기 전용
제품을 식별하는 문자열.

USB HID 장치의 경우 제품 이름에는 장치 설명자에 지정된 인덱스 iProduct의 문자열 설명자 값을 포함하는 것이 좋다. Bluetooth HID 장치의 경우 제품 이름에는 Device Name 특성 값을 포함하는 것이 좋다. 장치에 제품 이름이 없거나 제품 이름이 비어 있거나 접근할 수 없으면 이 속성은 빈 문자열을 반환해야 한다.

productName 문자열에는 일련번호나 Bluetooth 장치 주소처럼 장치를 고유하게 식별하는 데 사용할 수 있는 식별자를 포함하지 않는 것이 좋다.

다음의 productName 게터의 단계는 다음과 같다:

  1. this.[[productName]]을(를) 반환한다.

collections 속성, 자료형: FrozenArray<HIDCollectionInfo>, 읽기 전용
다음의 시퀀스 구성 요소: HIDCollectionInfo 다음을 나타낸다: 최상위 컬렉션 포함 위치: 보고서 설명자.
다음의 collections 게터의 단계는 다음과 같다:

  1. this.[[collections]]을(를) 반환한다.

참고: 최상위 컬렉션은 장치 내에서 비슷한 목적을 갖는 항목을 묶는다. 응용 프로그램은 HID 용도가 최상위 컬렉션에 어떻게 적용되었는지 살펴 장치를 식별한다. 응용 프로그램이 장치를 인식하지 못할 수도 있다. 이는 장치가 해당 유형의 관례를 따르지 않을 때 발생한다. 표준 HID 장치의 관례적인 동작은 [USBIF-HID-USAGE]를 참고한다.

입력 보고서를 수신한 경우, 그 출처는 다음과 같다: device다음 단계를 실행한다:

  1. 입력 보고서가 차단된 보고서이면 이 단계를 중단한다.

  2. reportId을(를) 이 보고서의 보고서 ID로 둔다. 단, HID 인터페이스가 보고서 ID를 사용하지 않으면 0으로 둔다.

  3. data을(를) DataView로 둔다. 이는 입력 보고서를 나타내는 바이트 시퀀스를 기반으로 생성한다. HID 인터페이스가 보고서 ID를 사용하면 이 바이트 시퀀스에는 보고서 ID 바이트를 포함해서는 안 된다.

  4. 전역 태스크를 큐에 넣는다. 대상 관련 전역 객체의 소유자는 this이며, HID 장치 태스크 소스를 사용한다. 이 태스크는 이벤트를 발생시킨다. 이름은 inputreport, 대상은 device, 사용 인터페이스는 HIDInputReportEvent이며, device 속성은 device, reportId 속성은 reportId, data 속성은 data(으)로 초기화한다.

7.1. open() 메서드

다음의 open() 메서드 단계는 다음과 같다:

  1. promise을(를) 새 프로미스로 둔다.

  2. this.[[state]]이(가) "closed"이 아니면 거부한다. 즉, promise을(를) "InvalidStateError" DOMException(으)로 거부하고 promise을(를) 반환한다.

  3. this.[[state]]의 값을 "opening"(으)로 설정한다.

  4. 다음 단계를 병렬로 수행한다:

    1. 운영체제를 호출하여 HID 장치를 연다.

    2. 어떤 이유로든 실패하면 전역 태스크를 큐에 넣는다. 대상 관련 전역 객체의 소유자는 this이며, HID 장치 태스크 소스를 사용한다. 이 태스크는 거부한다. 즉, promise을(를) "NetworkError" DOMException(으)로 거부한다. 그런 다음 이 단계를 중단한다.

    3. this.[[state]]의 값을 "opened"(으)로 설정한다.

    4. 전역 태스크를 큐에 넣는다. 대상 관련 전역 객체의 소유자는 this이며, HID 장치 태스크 소스를 사용한다. 이 태스크는 이행한다. 즉, promise을(를) undefined 값으로 이행한다.

  5. promise을(를) 반환한다.

7.2. close() 메서드

다음의 close() 메서드 단계는 다음과 같다:

  1. promise을(를) 새 프로미스로 둔다.

  2. this.[[state]]이(가) "forgotten", "forgetting", "opening" 또는 "closing" 중 하나이면 거부한다. 즉, promise을(를) "InvalidStateError" DOMException(으)로 거부하고 promise을(를) 반환한다.

  3. this.[[state]]의 값을 "closing"(으)로 설정한다.

  4. 각각에 대해, 즉 pendingPromise(대상: this.[[pendingSendReportPromises]])마다:

    1. 거부한다: pendingPromise을(를) "AbortError" DOMException(으)로 거부한다.

  5. 비운다: this.[[pendingSendReportPromises]]을(를) 비운다.

  6. 각각에 대해, 즉 pendingPromise(대상: this.[[pendingSendFeatureReportPromises]])마다:

    1. 거부한다: pendingPromise을(를) "AbortError" DOMException(으)로 거부한다.

  7. 비운다: this.[[pendingSendFeatureReportPromises]]을(를) 비운다.

  8. 각각에 대해, 즉 pendingPromise(대상: this.[[pendingReceiveFeatureReportPromises]])마다:

    1. 거부한다: pendingPromise을(를) "AbortError" DOMException(으)로 거부한다.

  9. 비운다: this.[[pendingReceiveFeatureReportPromises]]을(를) 비운다.

  10. 다음 단계를 병렬로 수행한다:

    1. 운영체제를 호출하여 HID 장치를 닫고 관련된 모든 자원을 해제한다.

    2. this.[[state]]의 값을 "closed"(으)로 설정한다.

    3. 전역 태스크를 큐에 넣는다. 대상 관련 전역 객체의 소유자는 this이며, HID 장치 태스크 소스를 사용한다. 이 태스크는 이행한다. 즉, promise을(를) undefined 값으로 이행한다.

  11. promise을(를) 반환한다.

7.3. forget() 메서드

참고: 사용자 에이전트는 API 간의 권한을 통합하기로 결정할 수 있다. 예를 들어 WebHID와 WebUSB 장치 접근을 하나의 저수준 장치 접근 권한으로 추적할 수 있다. 따라서 이 메서드는 앞으로 다른 권한(아직 지정되지 않음)도 철회할 수 있다.

다음의 forget() 메서드 단계는 다음과 같다:

  1. promise을(를) 새 프로미스로 둔다.

  2. 다음 단계를 병렬로 수행한다:

    1. 각각에 대해, 즉 device(대상: this.[[devices]])마다:

      1. device이(가) HIDDevice와 장치 접근 권한을 공유하지 않으면 다음 장치로 넘어간다.

      2. device.[[state]]의 값을 "forgetting"(으)로 설정한다.

      3. 각각에 대해, 즉 pendingPromise(대상: device.[[pendingSendReportPromises]])마다:

        1. 거부한다: pendingPromise을(를) "AbortError" DOMException(으)로 거부한다.

      4. 비운다: device.[[pendingSendReportPromises]]을(를) 비운다.

      5. 각각에 대해, 즉 pendingPromise(대상: device.[[pendingSendFeatureReportPromises]])마다:

        1. 거부한다: pendingPromise을(를) "AbortError" DOMException(으)로 거부한다.

      6. 비운다: device.[[pendingSendFeatureReportPromises]]을(를) 비운다.

      7. 각각에 대해, 즉 pendingPromise(대상: device.[[pendingReceiveFeatureReportPromises]])마다:

        1. 거부한다: pendingPromise을(를) "AbortError" DOMException(으)로 거부한다.

      8. 비운다: device.[[pendingReceiveFeatureReportPromises]]을(를) 비운다.

      9. 사용자 에이전트를 호출하여 모든 HID 인터페이스에 대한 접근을 철회한다. 이 인터페이스들은 device이(가) 노출한다.

      10. device.[[state]]의 값을 "forgotten"(으)로 설정한다.

    2. 전역 태스크를 큐에 넣는다. 대상 관련 전역 객체의 소유자는 this이며, HID 장치 태스크 소스를 사용한다. 이 태스크는 이행한다. 즉, promise을(를) undefined 값으로 이행한다.

  3. promise을(를) 반환한다.

7.4. sendReport() 메서드

다음의 sendReport() 메서드는 지정된 다음 값으로 출력 보고서를 보내는 데 사용한다: reportId 및 data. 만약 HID 인터페이스 가 다음을 하지 않으면: 보고서 ID 사용, 보고서 ID 대신 0을 전달한다.

HID 인터페이스가 보고서 ID를 사용하면 보고서 ID 값 0은 예약되어 있으므로 사용하지 않는 것이 좋다.

sendReport() 메서드의 단계는 다음과 같다:

  1. promise을(를) 새 프로미스로 둔다.

  2. this.[[state]]이(가) "opened"이 아니면 거부한다. 즉, promise을(를) "InvalidStateError" DOMException(으)로 거부하고 promise을(를) 반환한다.

  3. reportId이(가) 0이고, HID 인터페이스(이를 나타내는 객체: this)가 보고서 ID를 사용하거나, reportId이(가) 0이 아닌데 인터페이스가 보고서 ID를 사용하지 않으면 거부한다. 즉, promise을(를) "TypeError" DOMException(으)로 거부하고 promise을(를) 반환한다.

  4. 추가한다: promise을(를) this.[[pendingSendReportPromises]]에 추가한다.

  5. 다음 단계를 병렬로 수행한다:

    1. 이 보고서가 차단된 보고서이면 전역 태스크를 큐에 넣는다. 대상 관련 전역 객체의 소유자는 this이며, HID 장치 태스크 소스를 사용한다. 이 태스크는 거부한다. 즉, promise을(를) "NotAllowedError" DOMException(으)로 거부한다. 그런 다음 이 단계를 중단한다.

    2. 운영체제를 호출하여 지정된 reportId 및 data 값으로 출력 보고서를 보낸다.

    3. 어떤 이유로든 실패하면 전역 태스크를 큐에 넣는다. 대상 관련 전역 객체의 소유자는 this이며, HID 장치 태스크 소스를 사용한다. 이 태스크는 거부한다. 즉, promise을(를) "NetworkError" DOMException(으)로 거부한다. 그런 다음 이 단계를 중단한다.

    4. 전역 태스크를 큐에 넣는다. 대상 관련 전역 객체의 소유자는 this이며, HID 장치 태스크 소스를 사용한다. 이 태스크는 이행한다. 즉, promise을(를) undefined 값으로 이행한다.

  6. promise을(를) 반환한다.

7.5. sendFeatureReport() 메서드

다음의 sendFeatureReport() 메서드는 지정된 다음 값으로 기능 보고서를 보내는 데 사용한다: reportId 및 data. 만약 HID 인터페이스 가 다음을 하지 않으면: 보고서 ID 사용, 보고서 ID 대신 0을 전달한다.

HID 인터페이스가 보고서 ID를 사용하면 보고서 ID 값 0은 예약되어 있으므로 사용하지 않는 것이 좋다.

sendFeatureReport() 메서드의 단계는 다음과 같다:

  1. promise을(를) 새 프로미스로 둔다.

  2. this.[[state]]이(가) "opened"이 아니면 거부한다. 즉, promise을(를) "InvalidStateError" DOMException(으)로 거부하고 promise을(를) 반환한다.

  3. reportId이(가) 0이고, HID 인터페이스(이를 나타내는 객체: this)가 보고서 ID를 사용하거나, reportId이(가) 0이 아닌데 인터페이스가 보고서 ID를 사용하지 않으면 거부한다. 즉, promise을(를) "TypeError" DOMException(으)로 거부하고 promise을(를) 반환한다.

  4. 추가한다: promise을(를) this.[[pendingSendFeatureReportPromises]]에 추가한다.

  5. 다음 단계를 병렬로 수행한다:

    1. 이 보고서가 차단된 보고서이면 전역 태스크를 큐에 넣는다. 대상 관련 전역 객체의 소유자는 this이며, HID 장치 태스크 소스를 사용한다. 이 태스크는 거부한다. 즉, promise을(를) "NotAllowedError" DOMException(으)로 거부한다. 그런 다음 이 단계를 중단한다.

    2. 운영체제를 호출하여 지정된 reportId 및 data 값으로 기능 보고서를 보낸다.

    3. 어떤 이유로든 실패하면 전역 태스크를 큐에 넣는다. 대상 관련 전역 객체의 소유자는 this이며, HID 장치 태스크 소스를 사용한다. 이 태스크는 거부한다. 즉, promise을(를) "NetworkError" DOMException(으)로 거부한다. 그런 다음 이 단계를 중단한다.

    4. 전역 태스크를 큐에 넣는다. 대상 관련 전역 객체의 소유자는 this이며, HID 장치 태스크 소스를 사용한다. 이 태스크는 이행한다. 즉, promise을(를) undefined 값으로 이행한다.

  6. promise을(를) 반환한다.

7.6. receiveFeatureReport() 메서드

다음의 receiveFeatureReport() 메서드는 다음에 지정된 값으로 기능 보고서를 요청하는 데 사용한다: reportId. 만약 HID 인터페이스 가 다음을 하지 않으면: 보고서 ID 사용, 보고서 ID 대신 0을 전달한다.

HID 인터페이스가 보고서 ID를 사용하면 보고서 ID 값 0은 예약되어 있으므로 사용하지 않는 것이 좋다.

receiveFeatureReport() 메서드의 단계는 다음과 같다:

  1. promise을(를) 새 프로미스로 둔다.

  2. this.[[state]]이(가) "opened"이 아니면 거부한다. 즉, promise을(를) "InvalidStateError" DOMException(으)로 거부하고 promise을(를) 반환한다.

  3. reportId이(가) 0이고, HID 인터페이스(이를 나타내는 객체: this)가 보고서 ID를 사용하거나, reportId이(가) 0이 아닌데 인터페이스가 보고서 ID를 사용하지 않으면 거부한다. 즉, promise을(를) "TypeError" DOMException(으)로 거부하고 promise을(를) 반환한다.

  4. 추가한다: promise을(를) this.[[pendingReceiveFeatureReportPromises]]에 추가한다.

  5. 다음 단계를 병렬로 수행한다:

    1. 이 보고서가 차단된 보고서이면 전역 태스크를 큐에 넣는다. 대상 관련 전역 객체의 소유자는 this이며, HID 장치 태스크 소스를 사용한다. 이 태스크는 거부한다. 즉, promise을(를) "NotAllowedError" DOMException(으)로 거부한다. 그런 다음 이 단계를 중단한다.

    2. data을(를) DataView로 둔다. 이는 바이트 시퀀스를 기반으로 생성하며, 그 시퀀스는 운영체제를 호출하여 지정된 reportId 값으로 기능 보고서를 읽은 결과를 나타낸다.

      참고: data에는 운영체제에서 받은 보고서 데이터가 그대로 들어간다. 장치가 보고서 ID를 사용하면 첫 바이트는 보고서 ID일 수 있다. 장치가 보고서 ID 대신 다른 데이터로 응답할 수 있으므로 이 바이트도 포함한다.

    3. 어떤 이유로든 기능 보고서 읽기에 실패하면 전역 태스크를 큐에 넣는다. 대상 관련 전역 객체의 소유자는 this이며, HID 장치 태스크 소스를 사용한다. 이 태스크는 거부한다. 즉, promise을(를) "NetworkError" DOMException(으)로 거부한다. 그런 다음 이 단계를 중단한다.

    4. 전역 태스크를 큐에 넣는다. 대상 관련 전역 객체의 소유자는 this이며, HID 장치 태스크 소스를 사용한다. 이 태스크는 이행한다. 즉, promise을(를) data 값으로 이행한다.

  6. promise을(를) 반환한다.

8. HIDConnectionEvent 인터페이스

[Exposed=(DedicatedWorker,ServiceWorker,Window), SecureContext]
interface HIDConnectionEvent : Event {
    constructor(DOMString type, HIDConnectionEventInit eventInitDict);
    [SameObject] readonly attribute HIDDevice device;
};
device 속성, 자료형: HIDDevice, 읽기 전용
다음의 HIDDevice 인스턴스이며, 연결되거나 연결 해제된 장치를 나타낸다.

8.1. HIDConnectionEventInit 딕셔너리

dictionary HIDConnectionEventInit : EventInit {
    required HIDDevice device;
};
device 멤버, 자료형: HIDDevice
이벤트와 관련된 장치.

9. HIDInputReportEvent 인터페이스

[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 속성, 자료형: HIDDevice, 읽기 전용
다음의 HIDDevice 인스턴스이며, 다음을 나타낸다: HID 인터페이스 입력 보고서를 보낸 인터페이스이다.
reportId 속성, 자료형: octet, 읽기 전용
이 보고서의 1바이트 식별 접두사. 단, 다음의 HID 인터페이스가 다음을 하지 않는 경우에는 0이다: 보고서 ID 사용.
data 속성, 자료형: DataView, 읽기 전용
다음의 DataView 입력 보고서의 데이터를 포함한다. 단, 다음의 reportId 바이트는 제외한다. 이는 다음의 HID 인터페이스 보고서 ID 사용 시에 해당한다.

9.1. HIDInputReportEventInit 딕셔너리

dictionary HIDInputReportEventInit : EventInit {
    required HIDDevice device;
    required octet reportId;
    required DataView data;
};
device 멤버, 자료형: HIDDevice
이벤트와 관련된 장치.
reportId 멤버, 자료형: octet
입력 보고서의 보고서 ID.
data 멤버, 자료형: DataView
입력 보고서의 데이터.

10. HIDCollectionInfo 딕셔너리

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

장치가 시스템에 처음 연결되면 시스템은 보고서 설명자를 장치가 노출하는 각 HID 인터페이스에서 가져와야 한다. 보고서 설명자는 바이트 시퀀스이며, 이를 장치가 지원하는 각 보고서의 배치를 설명하는 계층적 자료구조로 확장할 수 있다. 이 자료구조의 원소를 항목이라고 한다. 서로 관련된 항목의 그룹을 컬렉션이라고 한다.

HIDCollectionInfo 객체는 보고서 설명자 내의 단일 컬렉션을 나타낸다. 컬렉션에 중첩된 컬렉션이 있으면 이를 children의 원소로 포함한다.

inputReports, outputReports 및 featureReports 속성에는 시퀀스가 들어 있다. 그 원소인 HIDReportInfo는 이 컬렉션에 기술된 각 보고서의 정보를 제공한다. 최상위 컬렉션에서는 HIDReportInfo가 보고서를 구성하는 모든 항목의 평탄화된 뷰를 나타낸다. 평탄화된 뷰는 중첩 컬렉션의 항목을 최상위 컬렉션의 항목과 원래 순서대로 섞어 놓는다. 중첩 컬렉션에서는 HIDReportInfo에 그 컬렉션과 그 안의 중첩 컬렉션에 포함된 항목만 들어 있다.

usagePage 멤버, 자료형: unsigned short
다음의 용도 페이지 구성 요소. 해당 구성 요소가 속하는 것은 다음이다: HID 용도 이 컬렉션과 관련된 용도이다.

HID 용도는 응용 프로그램이 항목이나 컬렉션의 목적과 의미를 식별하도록 해석할 수 있는 상수이다. HID 용도는 unsigned long 값이며, 상위 비트의 unsigned short 자료형 용도 페이지와 하위 비트의 unsigned short 자료형 용도 ID로 구성된다. 표준 HID 용도 값은 [USBIF-HID-CLASS] 및 USB Implementers Forum에서 발행한 다른 문서에서 설명한다.

HID 용도(장치가 노출하는 최상위 컬렉션에 지정된 값)는 일반적인 장치 유형을 식별하는 데 사용한다.

usage 멤버, 자료형: unsigned short
다음의 용도 ID 구성 요소. 해당 구성 요소가 속하는 것은 다음이다: HID 용도 이 컬렉션과 관련된 용도이다.

용도 ID는 개별 HID 용도를 해당 용도 페이지에서 선택하는 데 사용한다. 관례적으로 용도 ID 0x01부터 0x1F까지는 최상위 컬렉션용으로 예약되어 있다.

type 멤버, 자료형: octet
다음을 나타내는 값: 컬렉션 유형.
컬렉션 유형 값
물리적 0x00
응용 0x01
논리적 0x02
보고서 0x03
명명된 배열 0x04
용도 전환 0x05
용도 수정 0x06
향후 사용을 위해 예약됨 0x07부터 0x7F까지
공급업체 정의 0x80부터 0xFF까지

각 컬렉션 유형은 묶인 항목 간의 서로 다른 관계 유형을 설명한다. 자세한 내용은 [USBIF-HID-CLASS]의 6.2.2.6절에서 컬렉션 유형을 참고한다.

children 멤버, 시퀀스 자료형:<HIDCollectionInfo>
다음의 시퀀스 구성 요소: HIDCollectionInfo 이 컬렉션 안에 중첩된 컬렉션을 나타낸다.
inputReports 멤버, 시퀀스 자료형:<HIDReportInfo>
다음의 시퀀스 구성 요소: HIDReportInfo 이 컬렉션에 기술된 입력 보고서를 나타낸다.
outputReports 멤버, 시퀀스 자료형:<HIDReportInfo>
다음의 시퀀스 구성 요소: HIDReportInfo 이 컬렉션에 기술된 출력 보고서를 나타낸다.
featureReports 멤버, 시퀀스 자료형:<HIDReportInfo>
다음의 시퀀스 구성 요소: HIDReportInfo 이 컬렉션에 기술된 기능 보고서를 나타낸다.

11. HIDReportInfo 딕셔너리

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

HIDReportInfo는 보고서 설명자 내의 입력, 출력 또는 기능 보고서 하나를 나타낸다.

reportId 멤버, 자료형: octet
다음의 HID 인터페이스 보고서 ID를 사용한다 각 보고서 전송에 1바이트 식별 접두사를 붙이는 경우에 해당한다. 다음의 reportId 멤버는 이 보고서의 접두사이다. 이는 인터페이스가 다음과 같을 때 해당한다: 보고서 ID를 사용한다, 그렇지 않으면 0이다.
items 멤버, 시퀀스 자료형:<HIDReportItem>
다음의 시퀀스 구성 요소: HIDReportItem 이 보고서의 필드를 나타낸다.

12. HIDReportItem 딕셔너리

dictionary 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 멤버, 자료형: boolean
true 데이터가 절댓값(고정된 원점 기준)이면 이 값이며, 또는 false 데이터가 상대값(이전 보고서 이후의 값 변화)이면 이 값이다.
isArray 멤버, 자료형: boolean
true 항목이 보고서에 배열 데이터 필드를 생성하고 각 필드에 눌린 버튼이나 키에 대응하는 인덱스가 들어 있으면 이 값이며, 또는 false 항목이 보고서에 변수 데이터 필드를 생성하고 각 필드에 값이 들어 있으면 이 값이다.
isBufferedBytes 멤버, 자료형: boolean
true 항목이 고정 크기의 바이트 스트림을 내보내면 이 값이며, 또는 false 항목이 수치량이면 이 값이다.
isConstant 멤버, 자료형: boolean
true 항목이 수정할 수 없는 정적 읽기 전용 필드이면 이 값이며, 또는 false 항목이 수정 가능한 장치 데이터를 포함하는 보고서 필드를 정의하면 이 값이다.
isLinear 멤버, 자료형: boolean
true 항목이 측정값과 보고값 사이의 선형 관계를 나타내면 이 값이며, 또는 false 데이터가 어떤 방식으로든 처리되었으면 이 값이다.
isRange 멤버, 자료형: boolean
true 항목이 다음에서 용도를 할당하면 이 값이다: HID 용도 범위. 이 범위는 다음으로 정의한다: usageMinimum 및 usageMaximum, 또는 false 항목에 다음이 있으면 이 값이다: 시퀀스 구성 요소: HID 용도 값. 포함 위치: usages.
isVolatile 멤버, 자료형: boolean
true 호스트 상호작용 없이 항목 값이 바뀔 수 있으면 이 값이며, 또는 false 호스트만 항목 값을 변경하는 것이 좋으면 이 값이다.

기능 항목과 출력 항목에만 사용한다.

hasNull 멤버, 자료형: boolean
true 항목에 의미 있는 데이터를 보내지 않는 널 상태가 있으면 이 값이며, 또는 false 널 상태가 없으면 이 값이다. 널 상태에서는 항목이 지정된 다음 범위를 벗어나는 값을 보고한다: logicalMinimum 및 logicalMaximum.
hasPreferredState 멤버, 자료형: boolean
true 사용자가 제어 장치를 물리적으로 조작하지 않을 때 돌아가는 기본 상태가 있으면 이 값이며, 또는 false 기본 상태가 없으면 이 값이다.
wrap 멤버, 자료형: boolean
true 항목 값이 상한이나 하한에 도달했을 때 반대편 끝으로 순환하면 이 값이며, 또는 false 항목 값이 순환하지 않으면 이 값이다.
usages 멤버, 자료형: sequence<unsigned long>
만약 isRange 이(가) true 이거나 이 항목과 관련된 다음의 HID 용도 값이 없으면 usages 는 undefined여야 한다.

isRange이(가) false이면 usages은(는) 시퀀스이며 이 항목과 관련된 HID 용도 값을 원소로 갖는다.

usageMinimum 멤버, 자료형: unsigned long
만약 isRange 이(가) true 이면 usageMinimum 에는 최소의 다음 값이 들어 있다: HID 용도 값. 이 항목과 관련된 용도 범위 내의 값이다.

isRange이(가) false이면 usageMinimum은(는) undefined여야 한다.

usageMaximum 멤버, 자료형: unsigned long
만약 isRange 이(가) true 이면 usageMaximum 에는 최대의 다음 값이 들어 있다: HID 용도 값. 이 항목과 관련된 용도 범위 내의 값이다.

isRange이(가) false이면 usageMaximum은(는) undefined여야 한다.

reportSize 멤버, 자료형: unsigned short
각 보고서 데이터 필드의 크기(비트 단위). 다음의 reportSize 는 0보다 커야 한다.
reportCount 멤버, 자료형: unsigned short
이 항목에 대해 보고서에 포함되는 필드 수. 다음의 reportCount 는 0보다 커야 한다.
unitExponent 멤버, 자료형: byte
단위 지수 값. 항목에 단위 정의가 없으면 0이다.
unitSystem 멤버, 자료형: HIDUnitSystem
다음의 HIDUnitSystem 열거형 값으로, 단위 정의에 사용할 단위계를 지정한다. 또는 "none" 항목에 단위 정의가 없으면 이 값이다.
unitFactorLengthExponent 멤버, 자료형: byte
단위 정의에 있는 길이 단위(센티미터, 라디안, 인치 또는 도)의 지수 값. 항목에 단위 정의가 없으면 0이다.
unitFactorMassExponent 멤버, 자료형: byte
단위 정의에 있는 질량 단위(그램 또는 슬러그)의 지수 값. 항목에 단위 정의가 없으면 0이다.
unitFactorTimeExponent 멤버, 자료형: byte
단위 정의에 있는 시간 단위(초)의 지수 값. 항목에 단위 정의가 없으면 0이다.
unitFactorTemperatureExponent 멤버, 자료형: byte
단위 정의에 있는 온도 단위(켈빈 또는 화씨도)의 지수 값. 항목에 단위 정의가 없으면 0이다.
unitFactorCurrentExponent 멤버, 자료형: byte
단위 정의에 있는 전류 단위(암페어)의 지수 값. 항목에 단위 정의가 없으면 0이다.
unitFactorLuminousIntensityExponent 멤버, 자료형: byte
단위 정의에 있는 광도 단위(칸델라)의 지수 값. 항목에 단위 정의가 없으면 0이다.
logicalMinimum 멤버, 자료형: long
논리 단위로 나타낸 이 항목의 최솟값. 변수 항목이나 배열 항목이 보고할 최솟값이다.
logicalMaximum 멤버, 자료형: long
논리 단위로 나타낸 이 항목의 최댓값. 변수 항목이나 배열 항목이 보고할 최댓값이다.
physicalMinimum 멤버, 자료형: long
이 항목의 물리적 범위의 최솟값. 이는 다음을 나타낸다: logicalMinimum 에 단위를 적용한 값이다.
physicalMaximum 멤버, 자료형: long
이 항목의 물리적 범위의 최댓값. 이는 다음을 나타낸다: logicalMaximum 에 단위를 적용한 값이다.
strings 멤버, 시퀀스 자료형:<DOMString>
이 항목과 관련된 문자열. 문자열이 없으면 비어 있는 시퀀스 를 사용한다.

13. HIDUnitSystem 열거형

[USBIF-HID-CLASS]의 6.2.2.7절은 SI 선형, SI 회전, 영국식 선형, 영국식 회전이라는 네 가지 표준 단위계를 정의한다. 각 항목은 이 네 단위계 중 하나나 공급업체 정의 단위계를 사용하거나, 단위계를 사용하지 않는다.

enum 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"
장치가 단위계에 예약된 값을 사용했음을 나타낸다.

14. 사용 예

페이지에서 접근할 수 있는 장치 목록을 가져온다. 기본적으로 페이지에는 어떤 장치의 접근 권한도 부여되지 않았으므로 접근 가능한 장치가 없다. 
document.addEventListener('DOMContentLoaded', async () => {
  let devices = await navigator.hid.getDevices();
  devices.forEach(device => {
    console.log(`HID: ${device.productName}`);
  });
});
HID 장치의 연결 및 연결 해제에 대한 이벤트 수신기를 등록한다. 
navigator.hid.addEventListener('connect', ({device}) => {
  console.log(`HID connected: ${device.productName}`);
});

navigator.hid.addEventListener('disconnect', ({device}) => {
  console.log(`HID disconnected: ${device.productName}`);
});
장치 접근 권한이 부여되기 전에는 장치에 대해 다음을 통한 접근이 불가능하다: getDevices() . 그때까지 연결 이벤트도 발생하지 않는다. 페이지는 할 수 있다 : 다음을 사용하여 권한을 요청할 수 있다: requestDevice(). 이 예에서 페이지는 다음 값을 가진 장치에 대한 접근을 요청한다: 공급업체 ID 0xABCD. 장치는 반드시 다음 값을 가진 컬렉션도 갖춰야 한다: 용도 페이지 소비자 (0x000C) 및 용도 ID 소비자 제어 (0x0001). 다음 값을 가진 장치는 제품 ID 0x1234 오작동하는 것으로 보고되었다. 
let requestButton = document.getElementById("request-hid-device");
requestButton.addEventListener("click", async () => {
  let device;
  try {
    const devices = await navigator.hid.requestDevice({
      filters: [
        {
          vendorId: 0xabcd,
          usagePage: 0x000c,
          usage: 0x0001,
        },
      ],
      exclusionFilters: [
        {
          vendorId: 0xabcd,
          productId: 0x1234,
        }
      ],
    });
    device = devices[0];
  } catch (error) {
    console.log("An error occurred.");
  }

  if (!device) {
    console.log("No device was selected.");
  } else {
    console.log(`HID: ${device.productName}`);
  }
});
입력 보고서 이벤트에 대한 이벤트 수신기를 등록한다. 
device.oninputreport = ({device, reportId, data}) => {
  console.log(`Input report ${reportId} from ${device.productName}:`,
              new Uint8Array(data.buffer));
};

if (!device.opened)
  await device.open();
출력 보고서를 보낸다. 
try {
  if (!device.opened)
    await device.open();

  const outputReportData = new Uint8Array([0x12, 0x34, 0x56, 0x78]);
  await device.sendReport(0x05, outputReportData);
  console.log("Output report sent");
} catch (error) {
  console.log("An error occurred.")
}
기능 보고서를 읽고 쓴다. 
try {
  if (!device.opened)
    await device.open();

  const oldFeatureData = await device.receiveFeatureReport(0x80);
  console.log("Feature report received:", new Uint8Array(oldFeatureData.buffer));

  const newFeatureData = new Uint8Array([0x12, 0x34, 0x56, 0x78]);
  await device.sendFeatureReport(0x80, newFeatureData);
  console.log("Feature report sent");
} catch (error) {
  console.log("An error occurred.")
}

15. HID 차단 목록

이 명세는 https://github.com/whatwg/hid 저장소의 차단 목록 파일을 사용하여 웹사이트가 접근할 수 있는 HID 장치의 집합을 제한한다.

다음 작업의 결과: 차단 목록 파싱 대상 URL: url 결과는 다음이다: 시퀀스 딕셔너리 객체를 원소로 갖는다. 이 객체들은 다음을 가져와서 생성한다: url . 그 내용을 JSON으로 파싱한다.

HID 차단 목록은 차단 목록 파싱의 결과이다. 파싱 대상은 https://github.com/whatwg/hid/blob/main/blocklist.txt이다.

보고서가 다음에 해당한다: 차단된 보고서 단, 다음 단계가 반환하는 값이 다음과 같아야 한다: true:

  1. 각각에 대해, 즉 rule(대상: HID 차단 목록)마다:

    1. 보고서가 차단 목록 규칙에 의해 차단되고 해당 규칙이 rule이면 true을(를) 반환한다.

  2. false을(를) 반환한다.

보고서는 다음에 해당한다: 차단 목록 규칙에 의해 차단됨 rule 단, 다음 단계가 반환하는 값이 다음과 같아야 한다: true:

  1. reportId을(를) 보고서의 보고서 ID로 둔다. 단, HID 인터페이스가 보고서 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을(를) 반환한다.

16. 통합

16.1. 권한 정책

이 명세는 hid 속성을 Navigator 객체에 노출할지 여부를 제어하는 기능을 정의한다.

이 기능의 이름은 "hid"이다.

이 기능의 기본 허용 목록은 'self'이다.

감사의 말

훌륭한 기여를 해 주신 Feras Aldahlawi, François Beaufort, Jack Hsieh, Jeffrey Yasskin, Jonas Due Vesterheden, Kagami Sascha Rosylight, Marcos Cáceres, Peter Høy Andersen, Reilly Grant, Rob Pitkin, Ted Mielczarek, Thomas Steiner, Tim Steiner 및 Vincent Scheib에게 감사한다.

이 표준의 작성자는 Matt Reynolds(Google, mattreynolds@google.com)이다.

지식재산권

저작권 © WHATWG(Apple, Google, Mozilla, Microsoft). 이 저작물에는 크리에이티브 커먼즈 저작자표시 4.0 국제 라이선스가 적용된다. 이 저작물의 일부가 소스 코드에 포함되는 경우, 해당 소스 코드 내 부분에는 대신 BSD 3-Clause 라이선스가 적용된다.

색인

이 명세에서 정의한 용어

참조 문서에서 정의한 용어

참고 문헌

규범적 참고 문헌

[DOM]
Anne van Kesteren. DOM Standard. 현행 표준. URL: https://dom.spec.whatwg.org/
[HTML]
Anne van Kesteren 외. HTML Standard. 현행 표준. URL: https://html.spec.whatwg.org/multipage/
[INFRA]
Anne van Kesteren; Domenic Denicola. Infra Standard. 현행 표준. URL: https://infra.spec.whatwg.org/
[PERMISSIONS-POLICY-1]
Ian Clelland; Ari Chivukula. 권한 정책. URL: https://w3c.github.io/webappsec-permissions-policy/
[POINTEREVENTS3]
Patrick Lauke; Robert Flack. Pointer Events. URL: https://w3c.github.io/pointerevents/
[SERVICE-WORKERS]
Monica CHINTALA; Yoshisato Yanagisawa. Service Workers Nightly. URL: https://w3c.github.io/ServiceWorker/
[UIEVENTS]
Xiaoqian Wu. UI Events. URL: https://w3c.github.io/uievents/
[USBIF-HID-CLASS]
Mike Bergman 외. Device Class Definition for Human Interface Devices (HID) version 1.11. 2001년 5월 27일. 명세. URL: https://www.usb.org/document-library/device-class-definition-hid-111
[WEBIDL]
Edgar Chen; Timothy Gu. Web IDL Standard. 현행 표준. URL: https://webidl.spec.whatwg.org/

비규범적 참고 문헌

[BROWSEREXT]
Mike Pietraszak. Browser Extensions. 2016년 10월. 커뮤니티 그룹 보고서 초안. URL: https://browserext.github.io/browserext/
[GAMEPAD]
Steve Agoston; Matthew Reynolds. Gamepad. URL: https://w3c.github.io/gamepad/
[USBIF-HID-USAGE]
David Abzarian 외. HID Usage Tables for Universal Serial Bus (USB) version 1.22. 2021년 4월 6일. 명세. URL: https://www.usb.org/document-library/hid-usage-tables-122

IDL 색인

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

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

[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);
};

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

dictionary HIDDeviceFilter {
    unsigned short vendorId;
    unsigned short productId;
    unsigned short usagePage;
    unsigned short usage;
};

[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);
};

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

dictionary HIDConnectionEventInit : EventInit {
    required HIDDevice device;
};

[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;
};

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

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

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

dictionary 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;
};

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