usb.util

usb.util - ユーティリティ関数群。

本モジュールからは以下がエスクポートされます:

  • endpoint_address - エンドポイント絶対アドレスを返す。

  • endpoint_direction - エンドポイントの転送方向を返す。

  • endpoint_type - エンドポイントタイプを返す。

  • ctrl_direction - 制御転送control transfer)の転送方向を返す。

  • build_request_type - 制御転送(control transfer)のbmRequestTypeフィールドを構築します。

  • find_descriptor - 内部デスクリプター(inner descriptor)を探します。

  • claim_interface - 明示的にインターフェースを要求(claim)します。

  • release_interface - 明示的にインターフェースを解放します。

  • dispose_resources - オブジェクトによって割り当てられた内部リソースを解放します。

  • get_langids - get_langids-サポートされている文字列言語(string language)のリストをデバイスから取得します。

  • get_string - デバイスから文字列デスクリプターを取得します。

モジュール内容

関数

  • usb.util.endpoint_address

  • usb.util.endpoint_direction

  • usb.util.endpoint_type

  • usb.util.ctrl_direction

  • usb.util.build_request_type

  • usb.util.create_buffer

  • usb.util.find_descriptor

  • usb.util.claim_interface

  • usb.util.release_interface

  • usb.util.dispose_resources

  • usb.util.get_langids

  • usb.util.get_string

Attributes

usb.util.__author__ = Wander Lairson Costa
usb.util.DESC_TYPE_DEVICE = 1
usb.util.DESC_TYPE_CONFIG = 2
usb.util.DESC_TYPE_STRING = 3
usb.util.DESC_TYPE_INTERFACE = 4
usb.util.DESC_TYPE_ENDPOINT = 5
usb.util.ENDPOINT_IN = 128
usb.util.ENDPOINT_OUT = 0
usb.util.ENDPOINT_TYPE_CTRL = 0
usb.util.ENDPOINT_TYPE_ISO = 1
usb.util.ENDPOINT_TYPE_BULK = 2
usb.util.ENDPOINT_TYPE_INTR = 3
usb.util.CTRL_TYPE_STANDARD
usb.util.CTRL_TYPE_CLASS
usb.util.CTRL_TYPE_VENDOR
usb.util.CTRL_TYPE_RESERVED
usb.util.CTRL_RECIPIENT_DEVICE = 0
usb.util.CTRL_RECIPIENT_INTERFACE = 1
usb.util.CTRL_RECIPIENT_ENDPOINT = 2
usb.util.CTRL_RECIPIENT_OTHER = 3
usb.util.CTRL_OUT = 0
usb.util.CTRL_IN = 128
usb.util._ENDPOINT_ADDR_MASK = 15
usb.util._ENDPOINT_DIR_MASK = 128
usb.util._ENDPOINT_TRANSFER_TYPE_MASK = 3
usb.util._CTRL_DIR_MASK = 128
usb.util._dummy_s
usb.util.SPEED_LOW = 1
usb.util.SPEED_FULL = 2
usb.util.SPEED_HIGH = 3
usb.util.SPEED_SUPER = 4
usb.util.SPEED_UNKNOWN = 0
usb.util.endpoint_address(address)

エンドポイント絶対アドレスを返します。

addressパラメータは、エンドポイント・デスクリプターのbEndpointAddressフィールドです。

usb.util.endpoint_direction(address)

エンドポイントの方向を返します。

addressパラメータは、エンドポイントデスクリプターのbEndpointAddressフィールドです。可能な戻り値はENDPOINT_OUTまたはENDPOINT_INです。

usb.util.endpoint_type(bmAttributes)

エンドポイントの転送タイプを返します。

bmAttributesパラメーターは、エンドポイントデスクリプターのbmAttributesフィールドです。 可能な戻り値は、ENDPOINT_TYPE_CTRL、ENDPOINT_TYPE_ISO、ENDPOINT_TYPE_BULK、ENDPOINT_TYPE_INTR です。

usb.util.ctrl_direction(bmRequestType)

制御要求(control request)の方向を返します。

bmRequestTypeパラメーターは、制御転送(control transfere)のbmRequestTypeフィールドの値です。可能な戻り値はCTRL_OUTまたはCTRL_INです。

usb.util.build_request_type(direction, type, recipient)

制御要求(control requests)の為にbmRequestTypeフィールドを構築します。

これらは、制御要求(control request)のbmRequestTypeを作成するための従来の関数です。

directionパラメーターは、CTRL_OUTまたはCTRL_INにすることができます。typeパラメータは、CTRL_TYPE_STANDARD、CTRL_TYPE_CLASS、CTRL_TYPE_VENDOR、CTRL_TYPE_RESERVEDにすることができます。 recipientは、CTRL_RECIPIENT_DEVICE、CTRL_RECIPIENT_INTERFACE、CTRL_RECIPIENT_ENDPOINT、またはCTRL_RECIPIENT_OTHERです。

bmRequestTypeの値を返す。

usb.util.create_buffer(length)

読み取り関数に渡されるバッファを作成します。

読み取り関数は出力バッファを受け取ることができるため、データは決まった場所に読み取られ、オブジェクトを再利用できます。これにより、新しい読み取り呼び出しごとに新しいオブジェクトを作成するオーバーヘッドを回避できます。この関数は、指定された長さの互換性のあるシーケンスバッファを作成します。

usb.util.find_descriptor(desc, find_all=False, custom_match=None, **args)

内部デスクリプター(inner descriptor)を探します。

find_descriptorは、core.find()関数と同じように機能しますが、一般的なデスクリプターオブジェクトに対して機能します。 たとえば、devというDeviceオブジェクトがあり、bConfigurationValueが1に等しいこのオブジェクトのconfigurationが必要な場合、コードは以下のようになります:

>>> cfg = util.find_descriptor(dev, bConfigurationValue=1)

デスクリプターの任意のフィールドを一致基準として使用でき、core.find()と同じようにカスタマイズされた一致を指定できます。find_descriptor関数は、find_allパラメーターも受け入れる事ができ、その場合は1つのデスクリプターではなくイテレーターを取得します。

usb.util.claim_interface(device, interface)

明示的にインターフェース(interface)を要求(claim)します。

PyUSBユーザーは通常、ライブラリが自動的に処理するため、インターフェイスの要求(claim)について心配する必要はありません。 ただし、確定的なインターフェイスの要求(claim)が必要な場合があります。 これらのまれなケースでは、claim_interfaceを使用できます。

以前にclaim_interfaceを呼び出したかまたはデバイスオブジェクトによって内部的に呼び出された場合、インターフェイスがすでに要求(claim)されていた場合は、何も起こりません。

usb.util.release_interface(device, interface)

明示的にインターフェースを解除します。

この関数は、claim_interfaceの呼び出しを通じて、またはデバイスオブジェクトによって内部的に呼び出された、以前に要求されたインターフェイスを解放するために使用されます。

通常、デバイスオブジェクトが自動的に処理するため、あなたはポリシーの要求について心配する必要はありません。

usb.util.dispose_resources(device)

オブジェクトによって割り当てられた内部リソースを解放します。

たとえば、別のアプリケーションがデバイスと通信できるようにするために、あなたは指定指名的なリソース解放をする必要がある場合があります。 Pythonは指定指名的な破棄を提供しないため、この関数は、デバイスハンドルやインターフェイスポリシーなど、デバイスによって割り当てられたすべての内部リソースを解放します。

この関数を呼び出した後、デバイスオブジェクトを通常どおり使用し続けることができます。 リソースが再び必要になる場合は、自動的に割り当てられます。

usb.util.get_langids(dev)

サポートされている言語IDのリストをデバイスから取得します。

ほとんどのクライアントコードは、この関数を直接呼び出すべきではありませんが、代わりにDeviceオブジェクトのlangidsプロパティを使用します。これにより、必要に応じてこの関数が呼び出され、結果がキャッシュされます。

USB LANGIDは、Windows開発者に馴染みのある16ビット整数です。たとえば、en-USの代わりに0x0409と言います。完全であるとは主張していないリストについては、usb.orgサイトのどこかにあるファイルUSB_LANGIDS.pdfを参照してください。「システムソフトウェアは、現在このリストにないLANGIDの列挙と選択を許可する必要があります」("system software must allow the enumeration and selection of LANGIDs that are not currently on this list.")が要求されます。 また、「システムソフトウェアは、デバイスによって提示されるLANGIDコード配列（文字列インデックス= 0）で定義されていないLANGIDを要求してはなりません」("system software should never request a LANGID not defined in the LANGID code array (string index = 0) presented by a device.")も要求されます。 クライアントコードは、特定の言語IDの文字列要求を発行する前に、このタプルをチェックできます。

devは、サポートされている言語IDが取得されるDeviceオブジェクトです。

戻り値は整数のLANGIDのタプルであり、デバイスが文字列をまったくサポートしていない場合は空になる可能性があります(USB 3.1 仕様書 r1.0 section 9.6.9で許可されています)。 その場合、クライアントコードは文字列をまったく要求しないでください。

空のタプルを返す代わりに、文字列をサポートしていない一部のデバイスでは、この関数からUSBErrorが発生する場合があります。デバイスのlangidsプロパティのアクセサーはそのケースをキャッチし、空のタプルを提供するため、クライアントコードは、この関数を直接呼び出す代わりにlangidsプロパティを使用して、この詳細を無視できます。

usb.util.get_string(dev, index, langid=None)

デバイスから文字列記述子(string descriptor)を取得します。

devは、文字列が読み取られるDeviceオブジェクトです。

indexは文字列デスクリプターのインデックスであり、langidはデスクリプターの言語IDです。langidを省略すると、最初の言語IDの文字列デスクリプターが返されます。

ゼロが実際の文字列のインデックスになることはありません。USB仕様では、デバイスが文字列インデックスフィールドでゼロを使用して、文字列が提供されていないことを示すことができます。したがって、呼び出し元はそのケースを特別に処理する必要はありません。この関数は、インデックスがゼロの場合にNoneを返し、デバイスへのトラフィックを生成しません。

戻り値はデスクリプターに存在するUnicode文字列であり、要求されたインデックスがゼロの場合はNoneです。