WebHID API ( 日本語訳 )

このドキュメントでは、HID(Human Interface Device) プロトコルをサポートするデバイスへのアクセスを提供するための API について説明します。

デバイスの列挙

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

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

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

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

次の手順で `match` が返される場合、 {{HIDDevice}} |device| は {{HIDDeviceFilter}} |filter| に 一致するデバイス となります:

1. |filter|.{{HIDDeviceFilter/vendorId}} が存在し、|device|.{{HIDDevice/vendorId}} が |filter|.{{HIDDevice/vendorId}} と等しくない場合、`mismatch` を返します。
2. |filter|.{{HIDDeviceFilter/productId}} が存在し、|device|.{{HIDDevice/productId}} が |filter|.{{HIDDevice/productId}} と等しくない場合、`mismatch` を返します。
3. |filter|.{{HIDDeviceFilter/usagePage}} が存在する場合は、|device|.{{HIDDevice/collections}} の {{HIDCollectionInfo}} コレクションに対して繰り返し処理します。 [=一致するコレクション=] がない場合は、`mismatch` を返します。
4. `match` を返します。

次の手順で match が返される場合、{{HIDCollectionInfo}} |collection| は {{HIDDeviceFilter}} |filter| に 一致するコレクション となります:

1. |filter|.{{HIDDeviceFilter/usagePage}} が存在し、|device|.{{HIDCollectionInfo/usagePage}} が |filter|.{{HIDDeviceFilter/usagePage}} と等しくない場合、mismatch を返します。
2. |filter|.{{HIDDeviceFilter/usage}} が存在し、|device|.{{HIDCollectionInfo/usage}} が |filter|.{{HIDDeviceFilter/usage}} と等しくない場合、mismatch を返します。
3. match を返します。

次の手順で有効が返された場合、{{HIDDeviceFilter}} |filter| は 有効 です:

1. |filter|.{{HIDDeviceFilter/productId}} が存在し、|filter|.{{HIDDeviceFilter/vendorId}} が存在しない場合は、 無効 を返します。
2. |filter|.{{HIDDeviceFilter/usage}} が存在し、|filter|.{{HIDDeviceFilter/usagePage}} が存在しない場合は、無効を返します。
3. 有効 を返します。

UA は、システムに接続されているすべてのデバイスを列挙 できる必要があります (MUST)。 アルゴリズムが列挙を要求するたびにこの作業を実行する必要はありません。 UA は、最初の列挙を実行した結果をキャッシュしてから、デバイスの接続および切断イベントの監視を開始し、接続されたデバイスをキャッシュされた列挙に追加し、切断されたデバイスを削除しても構いません (MAY)。 この方法は、オペレーティングシステムコールの数を減らすために推奨されます。

          dictionary HIDConnectionEventInit : EventInit {
              required HIDDevice device;
          };

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

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

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

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

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

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

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

デバイスの使用法

        [
            Exposed=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> sendReport([EnforceRange] octet reportId, BufferSource data);
            Promise<undefined> sendFeatureReport([EnforceRange] octet reportId, BufferSource data);
            Promise<DataView> receiveFeatureReport([EnforceRange] octet reportId);
        };
      

統合

非規範として標記されたセクションと同様に、この仕様のすべてのオーサリングガイドライン、図、例、および注記は非規範的です。 この仕様の他のすべては規範的です。

このドキュメントのキーワード MAY および MUST は、ここに示すように、すべて大文字で表示される場合にのみ、BCP 14 [RFC2119] [RFC8174]で説明されているように解釈されます。