WdfUsbTargetDeviceRetrieveConfigDescriptor 関数 (wdfusb.h)

[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を返します。 それ以外の場合、このメソッドは次のいずれかの値を返すことができます。

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

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

注釈

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

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

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

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

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

要件

こちらもご覧ください

ExAllocatePoolWithTag

USB_CONFIGURATION_DESCRIPTOR

USB_ENDPOINT_DESCRIPTOR

USB_INTERFACE_DESCRIPTOR

WdfUsbTargetDeviceCreateWithParameters

WdfUsbTargetDeviceGetDeviceDescriptor