WdfUsbTargetDeviceRetrieveConfigDescriptor 関数 (wdfusb.h)

[アーティクル]
02/27/2024

[KMDF と UMDF に適用]

WdfUsbTargetDeviceRetrieveConfigDescriptor メソッドは、指定されたフレームワーク USB デバイスオブジェクトに関連付けられている USB デバイスの USB 構成記述子を取得します。

構文

NTSTATUS WdfUsbTargetDeviceRetrieveConfigDescriptor(
  [in]      WDFUSBDEVICE UsbDevice,
  [out]     PVOID        ConfigDescriptor,
  [in, out] PUSHORT      ConfigDescriptorLength
);

パラメーター

[in] UsbDevice

WdfUsbTargetDeviceCreateWithParameters の以前の呼び出しから取得された USB デバイスオブジェクトへのハンドル。

[out] ConfigDescriptor

USB_CONFIGURATION_DESCRIPTOR構造体を受け取り、その後に 1 つ以上のUSB_INTERFACE_DESCRIPTORと USB_ENDPOINT_DESCRIPTOR構造体が続く呼び出し元によって割り当てられたバッファーへのポインター。このパラメーターは省略可能であり、 NULL にすることができます。この場合、 WdfUsbTargetDeviceRetrieveConfigDescriptor は必要なバッファー長を返します。詳細については、「解説」を参照してください。

[in, out] ConfigDescriptorLength

ConfigDescriptor が指すバッファーの長さを提供する場所へのポインター。 ConfigDescriptor に指定されたポインターが NULL の場合、WdfUsbTargetDeviceRetrieveConfigDescriptor は ConfigDescriptorLength が指す場所で必要なバッファー長を返します。

戻り値

WdfUsbTargetDeviceRetrieveConfigDescriptor は、操作が成功した場合にSTATUS_SUCCESSを返します。それ以外の場合、このメソッドは次のいずれかの値を返すことができます。

リターンコード	説明
STATUS_INVALID_DEVICE_STATE	指定したターゲットに対して構成記述子を使用できませんでした。
STATUS_INVALID_PARAMETER	無効なパラメーターが検出されました。
STATUS_BUFFER_TOO_SMALL	指定したバッファーサイズがデータに対して小さすぎたか、呼び出し元が ConfigDescriptor パラメーターに NULL を指定しました。

このメソッドは、他の NTSTATUS 値を返す場合もあります。

ドライバーが無効なオブジェクトハンドルを提供すると、バグチェックが発生します。

注釈

WdfUsbTargetDeviceRetrieveConfigDescriptor メソッドは、指定されたすべての USB デバイスの構成情報 (つまり、構成記述子と、存在する可能性がある任意のインターフェイスまたはエンドポイント記述子) を取得します。この情報の形式については、USB 仕様に関するページを参照してください。

WdfUsbTargetDeviceSelectConfig を使用すると、記述子リストにリストされている最初の USB 構成のみを選択できますが、この 1 つの構成内で複数のインターフェイスを選択できます。

ドライバーは、次のように WdfUsbTargetDeviceRetrieveConfigDescriptor を 2 回呼び出す必要があります。

ConfigDescriptor ポインターを NULL に設定して、WdfUsbTargetDeviceRetrieveConfigDescriptor が ConfigDescriptorLength が指すアドレスに必要なバッファーサイズを返すようにします。
構成情報を保持するバッファー領域を割り当てます。たとえば、ドライバーが ExAllocatePoolWithTag を呼び出してバッファーを割り当てる場合や、 WdfMemoryCreate を呼び出してフレームワークメモリオブジェクトを作成する場合があります。
WdfUsbTargetDeviceRetrieveConfigDescriptor をもう一度呼び出し、新しいバッファーへのポインターとバッファーのサイズを渡します。

WdfUsbTargetDeviceRetrieveConfigDescriptor の 2 回目の呼び出しが返された後、ConfigDescriptor によって指されるバッファーには、USB_CONFIGURATION_DESCRIPTOR構造体が含まれており、その後に 1 つ以上のUSB_INTERFACE_DESCRIPTORとUSB_ENDPOINT_DESCRIPTOR構造体が続きます。これらの後者の構造は、USB 仕様に記載されている順序で配置されます。

WdfUsbTargetDeviceRetrieveConfigDescriptor メソッドと USB I/O ターゲットの詳細については、「USB I/O ターゲット」を参照してください。

例

次のコード例では 、WdfUsbTargetDeviceRetrieveConfigDescriptor を呼び出して必要なバッファーサイズを取得し、 WdfMemoryCreate を呼び出してメモリオブジェクトとバッファーを作成した後、 WdfUsbTargetDeviceRetrieveConfigDescriptor を再度呼び出してデバイスの構成情報を取得します。

USHORT  size;
NTSTATUS  ntStatus;
PMY_DEVICE_CONTEXT  myDeviceContext;
PUSB_CONFIGURATION_DESCRIPTOR  configurationDescriptor = NULL;
WDF_OBJECT_ATTRIBUTES  objectAttribs;
WDFMEMORY  memoryHandle;

myDeviceContext = GetDeviceContext(Device);

ntStatus = WdfUsbTargetDeviceRetrieveConfigDescriptor(
                                            myDeviceContext->WdfUsbTargetDevice,
                                            NULL,
                                            &size
                                            );

if (ntStatus != STATUS_BUFFER_TOO_SMALL) {
    return ntStatus;
}

WDF_OBJECT_ATTRIBUTES_INIT(&objectAttribs);
objectAttribs.ParentObject = myDeviceContext->WdfUsbTargetDevice;

ntStatus = WdfMemoryCreate(
                           &objectAttribs,
                           NonPagedPool,
                           POOL_TAG,
                           size,
                           &memoryHandle,
                           (PVOID)&configurationDescriptor
                           );
if (!NT_SUCCESS(ntStatus)) {
    return ntStatus;
}

ntStatus = WdfUsbTargetDeviceRetrieveConfigDescriptor(
                                            myDeviceContext->WdfUsbTargetDevice,
                                            configurationDescriptor,
                                            &size
                                            );
if (!NT_SUCCESS(ntStatus)) {
    return ntStatus;
}

要件

要件	値
対象プラットフォーム	ユニバーサル
最小 KMDF バージョン	1.0
最小 UMDF バージョン	2.0
Header	wdfusb.h (Wdfusb.h を含む)
Library	Wdf01000.sys (KMDF);WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
DDI コンプライアンス規則	DriverCreate(kmdf)、 KmdfIrql(kmdf)、 KmdfIrql2(kmdf)、KmdfIrqlExplicit(kmdf)、 UsbKmdfIrql(kmdf)、 UsbKmdfIrql2(kmdf)、UsbKmdfIrqlExplicit(kmdf)