chrome.usb

説明

chrome.usb API を使用して、接続された USB デバイスを操作します。この API を使用すると、アプリのコンテキストから USB 操作にアクセスできます。この API を使用すると、アプリはハードウェア デバイスのドライバとして機能します。この API によって生成されたエラーは、runtime.lastError を設定して関数の通常のコールバックを実行することで報告されます。この場合、コールバックの通常のパラメータは未定義になります。

権限

usb

型

ConfigDescriptor

プロパティ

  • アクティブであることを表します。

    boolean

    Chrome 47 以降

    これは有効な設定ですか？

  • configurationValue

    数値

    構成番号。

  • description

    string（省略可）

    構成の説明。

  • extra_data

    ArrayBuffer

    この構成に関連付けられた追加の記述子データ。

  • インターフェース

    InterfaceDescriptor[]

    使用可能なインターフェース。

  • maxPower

    数値

    このデバイスに必要な最大電力（ミリアンペア（mA）単位）。

  • remoteWakeup

    boolean

    デバイスはリモート ウェイクアップをサポートしている。

  • selfPowered

    boolean

    デバイスがセルフパワーになっている。

ConnectionHandle

プロパティ

  • handle

    数値

    USB デバイスに対するこの接続と、申請されているすべての関連インターフェースおよび保留中の転送を表す不透明ハンドル。デバイスを開くたびに新しいハンドルが作成されます。接続ハンドルは Device.device とは異なります。

  • productId

    数値

    商品 ID。

  • vendorId

    数値

    デバイスのベンダー ID。

ControlTransferInfo

プロパティ

  • data

    ArrayBuffer 省略可

    送信するデータ（出力転送でのみ必要）。

  • direction

    方向

    乗り換えの方向（"in" または "out"）。

  • 指数

    数値

    wIndex フィールド。同上をご覧ください。

  • length

    number（省略可）

    受信する最大バイト数（入力転送でのみ必要）。

  • 受取人

    受信者

    転送先。"interface" または "endpoint" の場合、index で指定されたターゲットを使用する必要があります。

  • request

    数値

    bRequest フィールド（Universal Serial Bus Specification Revision 1.1 § 9.3 をご覧ください）

  • requestType

    RequestType

    リクエストのタイプ。

  • タイムアウト

    number（省略可）

    Chrome 43 以降

    リクエストのタイムアウト（ミリ秒単位）。デフォルト値 0 はタイムアウトがないことを示します。

  • value

    数値

    wValue フィールド。同上をご覧ください。

Device

プロパティ

  • ね

    数値

    USB デバイスの不透明な ID。ステータスは、デバイスを電源から外すまで変化しません。

  • manufacturerName

    文字列

    Chrome 46 以降

    デバイスから読み取られた iManufacturer 文字列（利用可能な場合）。

  • productId

    数値

    商品 ID。

  • productName

    文字列

    Chrome 46 以降

    デバイスから読み取られた iProduct 文字列（利用可能な場合）。

  • serialNumber

    文字列

    Chrome 46 以降

    デバイスから読み取られた iSerialNumber 文字列（利用可能な場合）。

  • vendorId

    数値

    デバイスのベンダー ID。

  • バージョン

    数値

    Chrome 51 以降

    デバイスのバージョン（bcdDevice フィールド）。

DeviceFilter

プロパティ

  • interfaceClass

    number（省略可）

    USB インターフェース クラス。デバイスの任意のインターフェースと一致します。

  • interfaceProtocol

    number（省略可）

    USB インターフェース プロトコル。インターフェース サブクラスが一致する場合にのみチェックされます。

  • interfaceSubclass

    number（省略可）

    USB インターフェース サブクラス。インターフェース クラスが一致する場合にのみチェックされます。

  • productId

    number（省略可）

    デバイスの商品 ID。ベンダー ID が一致する場合にのみチェックされます。

  • vendorId

    number（省略可）

    デバイスのベンダー ID。

DevicePromptOptions

プロパティ

  • フィルタ

    DeviceFilter[] 省略可

    ユーザーに表示されるデバイスのリストをフィルタします。複数のフィルタを指定すると、いずれかのフィルタに一致するデバイスが表示されます。

  • 複数

    ブール値（省略可）

    ユーザーが複数のデバイスを選択できるようにします。

Direction

Direction、Recipient、RequestType、TransferType はすべて USB 仕様内でそれぞれの名前にマッピングされます。

Enum

"in"

"out"

EndpointDescriptor

プロパティ

  • address

    数値

    エンドポイント アドレス。

  • direction

    方向

    転送の指示。

  • extra_data

    ArrayBuffer

    このエンドポイントに関連付けられている追加の記述子データ。

  • maximumPacketSize

    数値

    最大パケットサイズ。

  • pollingInterval

    number（省略可）

    ポーリング間隔（割り込みとアイソクロナスのみ）。

  • 同期

    SynchronizationType 省略可

    転送同期モード（アイソクロナスのみ）。

  • タイプ

    TransferType

    転送タイプ。

  • usage

    UsageType 省略可

    エンドポイントの使用方法のヒント。

EnumerateDevicesAndRequestAccessOptions

プロパティ

  • interfaceId

    number（省略可）

    アクセスをリクエストするインターフェース ID。ChromeOS でのみご利用いただけます。他のプラットフォームには影響しません。

  • productId

    数値

    商品 ID。

  • vendorId

    数値

    デバイスのベンダー ID。

EnumerateDevicesOptions

プロパティ

  • フィルタ

    DeviceFilter[] 省略可

    指定したフィルタに一致するデバイスが返されます。空のフィルタリストでは、アプリが権限を持つすべてのデバイスが返されます。

  • productId

    number（省略可）

    非推奨

    DeviceFilter.productId の設定に相当します。

  • vendorId

    number（省略可）

    非推奨

    DeviceFilter.vendorId の設定に相当します。

GenericTransferInfo

プロパティ

  • data

    ArrayBuffer 省略可

    送信するデータ（出力転送でのみ必要）。

  • direction

    方向

    乗り換えの方向（"in" または "out"）。

  • エンドポイント

    数値

    ターゲット エンドポイント アドレス。このエンドポイントを含むインターフェースは、要求する必要があります。

  • length

    number（省略可）

    受信する最大バイト数（入力転送でのみ必要）。

  • タイムアウト

    number（省略可）

    Chrome 43 以降

    リクエストのタイムアウト（ミリ秒単位）。デフォルト値 0 はタイムアウトがないことを示します。

InterfaceDescriptor

プロパティ

  • alternateSetting

    数値

    インターフェースの代替設定番号（デフォルトは 0）

  • description

    string（省略可）

    インターフェースの説明。

  • エンドポイント

    EndpointDescriptor[]

    使用可能なエンドポイント。

  • extra_data

    ArrayBuffer

    このインターフェースに関連付けられている追加の記述子データ。

  • interfaceClass

    数値

    USB インターフェース クラス。

  • interfaceNumber

    数値

    インターフェース番号。

  • interfaceProtocol

    数値

    USB インターフェース プロトコル。

  • interfaceSubclass

    数値

    USB インターフェース サブクラス。

IsochronousTransferInfo

プロパティ

  • packetLength

    数値

    この転送における各パケットの長さ。

  • packets

    数値

    この転送のパケットの合計数。

  • transferInfo

    GenericTransferInfo

    転送パラメータ。このパラメータ ブロックで指定された転送長またはデータバッファは、packetLength の境界に沿って分割され、転送の個々のパケットを形成します。

Recipient

Enum

"interface"

RequestType

Enum

"standard"

SynchronizationType

割り込みモードとアイソクロナス モードの場合、SynchronizationType と UsageType は USB 仕様内でそれぞれの名前にマッピングされます。

Enum

"adaptive"

TransferResultInfo

プロパティ

  • data

    ArrayBuffer 省略可

    入力転送によって返されたデータ。undefined: 出力転送の場合。

  • resultCode

    number（省略可）

    値 0 は転送が成功したことを示します。その他の値は失敗を示します。

TransferType

Enum

"control"

"bulk"

UsageType

Enum

"feedback"

"periodic"

Methods

bulkTransfer()

Promise 
chrome.usb.bulkTransfer(
  handle: ConnectionHandle,
  transferInfo: GenericTransferInfo,
  callback?: function,
)

指定したデバイスで一括転送を実行します。

パラメータ

戻り値

  • Chrome 116 以降

    Promise は Manifest V3 以降でのみサポートされます。他のプラットフォームではコールバックを使用する必要があります。

claimInterface()

Promise 
chrome.usb.claimInterface(
  handle: ConnectionHandle,
  interfaceNumber: number,
  callback?: function,
)

USB デバイスのインターフェースを要求します。インターフェースまたは関連するエンドポイントにデータを転送するには、その前にインターフェースを申請する必要があります。インターフェースを申請できるのは、常に 1 つの接続ハンドルのみです。インターフェースがすでに申請されている場合、この呼び出しは失敗します。

インターフェースが不要になったら、releaseInterface を呼び出す必要があります。

パラメータ

  • デバイスへのオープン接続。

  • interfaceNumber

    数値

    申請するインターフェース。

  • callback

    関数（省略可）

    callback パラメータは次のようになります。 

    ()=>void

戻り値

  • Promise<void>

    Chrome 116 以降

    Promise は Manifest V3 以降でのみサポートされます。他のプラットフォームではコールバックを使用する必要があります。

closeDevice()

Promise 
chrome.usb.closeDevice(
  handle: ConnectionHandle,
  callback?: function,
)

接続ハンドルを閉じます。閉じられたハンドルに対するオペレーションの呼び出しは安全なオペレーションですが、アクションは実行されません。

パラメータ

戻り値

  • Promise<void>

    Chrome 116 以降

    Promise は Manifest V3 以降でのみサポートされます。他のプラットフォームではコールバックを使用する必要があります。

controlTransfer()

Promise 
chrome.usb.controlTransfer(
  handle: ConnectionHandle,
  transferInfo: ControlTransferInfo,
  callback?: function,
)

指定されたデバイスでコントロール転送を実行します。

コントロール転送とは、デバイス、インターフェース、エンドポイントのいずれかを指します。インターフェースまたはエンドポイントへの転送には、インターフェースを申請する必要があります。

パラメータ

戻り値

  • Chrome 116 以降

    Promise は Manifest V3 以降でのみサポートされます。他のプラットフォームではコールバックを使用する必要があります。

findDevices()

Promise 
chrome.usb.findDevices(
  options: EnumerateDevicesAndRequestAccessOptions,
  callback?: function,
)

ベンダー ID、製品 ID、インターフェース ID（オプション）で指定された USB デバイスを検索し、権限でそれらの ID が使用できるようになっているかどうかを確認します。

アクセス リクエストが拒否されたり、デバイスを開けなかったりした場合、接続ハンドルは作成されず、返されません。

このメソッドを呼び出すことは、デバイスごとに getDevices を呼び出した後に openDevice を呼び出すことと同等です。

パラメータ

戻り値

  • Promise<ConnectionHandle[]>

    Chrome 116 以降

    Promise は Manifest V3 以降でのみサポートされます。他のプラットフォームではコールバックを使用する必要があります。

getConfiguration()

Promise 
chrome.usb.getConfiguration(
  handle: ConnectionHandle,
  callback?: function,
)

現在選択されている構成の構成記述子を取得します。

パラメータ

戻り値

  • Chrome 116 以降

    Promise は Manifest V3 以降でのみサポートされます。他のプラットフォームではコールバックを使用する必要があります。

getConfigurations()

Promise Chrome 47 以降 
chrome.usb.getConfigurations(
  device: Device,
  callback?: function,
)

デバイス構成記述子の完全なセットを返します。

パラメータ

戻り値

  • Promise<ConfigDescriptor[]>

    Chrome 116 以降

    Promise は Manifest V3 以降でのみサポートされます。他のプラットフォームではコールバックを使用する必要があります。

getDevices()

Promise 
chrome.usb.getDevices(
  options: EnumerateDevicesOptions,
  callback?: function,
)

接続されている USB デバイスを列挙します。

パラメータ

  • オプション

    EnumerateDevicesOptions

    対象デバイスで検索するプロパティ。

  • callback

    関数（省略可）

    callback パラメータは次のようになります。 

    (devices: Device[])=>void

戻り値

  • Promise<Device[]>

    Chrome 116 以降

    Promise は Manifest V3 以降でのみサポートされます。他のプラットフォームではコールバックを使用する必要があります。

getUserSelectedDevices()

Promise 
chrome.usb.getUserSelectedDevices(
  options: DevicePromptOptions,
  callback?: function,
)

デバイス選択ツールをユーザーに提示し、選択された Device を返します。キャンセルすると、選択ツールは空になります。ダイアログを表示するには、ユーザー操作が必要です。ユーザー操作がない場合、コールバックはユーザーがキャンセルした場合と同様に実行されます。

パラメータ

  • オプション

    DevicePromptOptions

    デバイス選択ツールのダイアログ ボックスの構成。

  • callback

    関数（省略可）

    callback パラメータは次のようになります。 

    (devices: Device[])=>void

戻り値

  • Promise<Device[]>

    Chrome 116 以降

    Promise は Manifest V3 以降でのみサポートされます。他のプラットフォームではコールバックを使用する必要があります。

interruptTransfer()

Promise 
chrome.usb.interruptTransfer(
  handle: ConnectionHandle,
  transferInfo: GenericTransferInfo,
  callback?: function,
)

指定されたデバイスで割り込み転送を実行します。

パラメータ

戻り値

  • Chrome 116 以降

    Promise は Manifest V3 以降でのみサポートされます。他のプラットフォームではコールバックを使用する必要があります。

isochronousTransfer()

Promise 
chrome.usb.isochronousTransfer(
  handle: ConnectionHandle,
  transferInfo: IsochronousTransferInfo,
  callback?: function,
)

特定のデバイスでアイソクロナス転送を実行します。

パラメータ

戻り値

  • Chrome 116 以降

    Promise は Manifest V3 以降でのみサポートされます。他のプラットフォームではコールバックを使用する必要があります。

listInterfaces()

Promise 
chrome.usb.listInterfaces(
  handle: ConnectionHandle,
  callback?: function,
)

USB デバイスのすべてのインターフェースを一覧表示します。

パラメータ

戻り値

  • Chrome 116 以降

    Promise は Manifest V3 以降でのみサポートされます。他のプラットフォームではコールバックを使用する必要があります。

openDevice()

Promise 
chrome.usb.openDevice(
  device: Device,
  callback?: function,
)

getDevices から返された USB デバイスを開きます。

パラメータ

戻り値

  • Chrome 116 以降

    Promise は Manifest V3 以降でのみサポートされます。他のプラットフォームではコールバックを使用する必要があります。

releaseInterface()

Promise 
chrome.usb.releaseInterface(
  handle: ConnectionHandle,
  interfaceNumber: number,
  callback?: function,
)

要求されたインターフェースを解放します。

パラメータ

  • デバイスへのオープン接続。

  • interfaceNumber

    数値

    リリースするインターフェース。

  • callback

    関数（省略可）

    callback パラメータは次のようになります。 

    ()=>void

戻り値

  • Promise<void>

    Chrome 116 以降

    Promise は Manifest V3 以降でのみサポートされます。他のプラットフォームではコールバックを使用する必要があります。

requestAccess()

Promise 非推奨
chrome.usb.requestAccess(
  device: Device,
  interfaceId: number,
  callback?: function,
)

この関数は Chrome OS 固有のもので、他のプラットフォームで呼び出すと失敗します。この操作は、openDevice の一部として暗黙的に実行され、この関数はすべてのプラットフォームで true を返すようになりました。

デバイス上の特定のインターフェースが要求されていない場合、ChromeOS によって要求されたデバイスへのアクセスを権限ブローカーからリクエストします。

パラメータ

  • アクセスをリクエストする Device。

  • interfaceId

    数値

    リクエストされた特定のインターフェース。

  • callback

    関数（省略可）

    callback パラメータは次のようになります。 

    (success: boolean)=>void

    • success

      boolean

戻り値

  • Promise<boolean>

    Chrome 116 以降

    Promise は Manifest V3 以降でのみサポートされます。他のプラットフォームではコールバックを使用する必要があります。

resetDevice()

Promise 
chrome.usb.resetDevice(
  handle: ConnectionHandle,
  callback?: function,
)

USB デバイスのリセットを試みます。リセットに失敗すると、該当の接続ハンドルが閉じ、USB デバイスが接続解除されてから再接続されたように見えます。この場合、デバイスを取得するには、getDevices または findDevices を再度呼び出す必要があります。

パラメータ

  • リセットする接続ハンドル。

  • callback

    関数（省略可）

    callback パラメータは次のようになります。 

    (success: boolean)=>void

    • success

      boolean

戻り値

  • Promise<boolean>

    Chrome 116 以降

    Promise は Manifest V3 以降でのみサポートされます。他のプラットフォームではコールバックを使用する必要があります。

setConfiguration()

Promise 
chrome.usb.setConfiguration(
  handle: ConnectionHandle,
  configurationValue: number,
  callback?: function,
)

デバイス設定を選択します。

この関数は、デバイスで利用可能な設定のいずれかを選択して、事実上デバイスをリセットします。0 より大きい設定値のみ有効ですが、バグのあるデバイスの中には、動作している設定 0 を使用しているものもあるため、この値が許容されます。

パラメータ

  • デバイスへのオープン接続。

  • configurationValue

    数値

  • callback

    関数（省略可）

    callback パラメータは次のようになります。 

    ()=>void

戻り値

  • Promise<void>

    Chrome 116 以降

    Promise は Manifest V3 以降でのみサポートされます。他のプラットフォームではコールバックを使用する必要があります。

setInterfaceAlternateSetting()

Promise 
chrome.usb.setInterfaceAlternateSetting(
  handle: ConnectionHandle,
  interfaceNumber: number,
  alternateSetting: number,
  callback?: function,
)

以前に登録したインターフェースの別の設定を選択します。

パラメータ

  • このインターフェースが申請されているデバイスへのオープン接続。

  • interfaceNumber

    数値

    構成するインターフェース。

  • alternateSetting

    数値

    設定する代替設定。

  • callback

    関数（省略可）

    callback パラメータは次のようになります。 

    ()=>void

戻り値

  • Promise<void>

    Chrome 116 以降

    Promise は Manifest V3 以降でのみサポートされます。他のプラットフォームではコールバックを使用する必要があります。

イベント

onDeviceAdded

chrome.usb.onDeviceAdded.addListener(
  callback: function,
)

デバイスがシステムに追加されたときに生成されるイベント。イベントは、デバイスへのアクセス権限を持つアプリと拡張機能にのみブロードキャストされます。権限は、インストール時、ユーザーがオプションの権限を許可した場合（permissions.request を参照）、または getUserSelectedDevices を介して付与された可能性があります。

パラメータ

  • callback

    機能

    callback パラメータは次のようになります。 

    (device: Device)=>void

onDeviceRemoved

chrome.usb.onDeviceRemoved.addListener(
  callback: function,
)

デバイスがシステムから削除されたときに生成されるイベント。配信されるイベントについては、onDeviceAdded をご覧ください。

パラメータ

  • callback

    機能

    callback パラメータは次のようになります。 

    (device: Device)=>void