WdfUsbTargetDeviceFormatRequestForControlTransfer 関数 (wdfusb.h)

[KMDF と UMDF に適用]

WdfUsbTargetDeviceFormatRequestForControlTransfer メソッドは USB コントロール転送要求をビルドしますが、要求は送信しません。

構文

NTSTATUS WdfUsbTargetDeviceFormatRequestForControlTransfer(
  [in]           WDFUSBDEVICE                  UsbDevice,
  [in]           WDFREQUEST                    Request,
  [in]           PWDF_USB_CONTROL_SETUP_PACKET SetupPacket,
  [in, optional] WDFMEMORY                     TransferMemory,
  [in, optional] PWDFMEMORY_OFFSET             TransferOffset
);

パラメーター

[in] UsbDevice

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

[in] Request

フレームワーク要求オブジェクトへのハンドル。 詳細については、「解説」を参照してください。

[in] SetupPacket

制御転送を記述する呼び出し元によって割り当てられた WDF_USB_CONTROL_SETUP_PACKET 構造体へのポインター。

[in, optional] TransferMemory

デバイス固有のコマンドに応じて、入力バッファーまたは出力バッファーを記述するフレームワーク メモリ オブジェクトへのハンドル。 このポインターは省略可能であり、 NULL にすることができます。 詳細については、「解説」を参照してください。

[in, optional] TransferOffset

省略可能なバイト オフセットと長さの値を提供する呼び出し元によって割り当てられた WDFMEMORY_OFFSET 構造体へのポインター。 フレームワークでは、これらの値を使用して、 TransferMemory が指定するバッファー内の開始アドレスと長さを決定します。 このポインターが NULL の場合、フレームワークはバッファー全体を使用します。

戻り値

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

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

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

注釈

WdfUsbTargetDeviceFormatRequestForControlTransfer の後に WdfRequestSend を使用して、USB コントロール転送要求を同期的または非同期的に送信します。 または、 WdfUsbTargetDeviceSendControlTransferSynchronously メソッドを使用して、要求を同期的に送信します。

ドライバーが I/O キューで受信した I/O 要求を転送することも、新しい要求を作成して送信することもできます。 どちらの場合も、フレームワークには要求オブジェクトが必要であり、制御転送の種類によっては、バッファー領域が必要になる場合があります。

ドライバーが I/O キューで受信した I/O 要求を転送するには:

1. WdfUsbTargetDeviceFormatRequestForControlTransfer メソッドの Request パラメーターに対して、受信した要求のハンドルを指定します。
2. TransferMemory パラメーターには、受信した要求の入力バッファーまたは出力バッファーを使用します。

   ドライバーは WdfRequestRetrieveInputMemory または WdfRequestRetrieveOutputMemory を呼び出して、要求の入力バッファーまたは出力バッファーを表すフレームワーク メモリ オブジェクトへのハンドルを取得し、そのハンドルを TransferMemory の値として使用する必要があります。

1. 新しい要求オブジェクトを作成し、 WdfUsbTargetDeviceFormatRequestForControlTransfer メソッドの Request パラメーターのハンドルを 指定 します。

   WdfRequestCreate を呼び出して、1 つ以上の要求オブジェクトを事前割り当てします。 これらの要求オブジェクトを再利用するには、 WdfRequestReuse を呼び出します。 ドライバーの EvtDriverDeviceAdd コールバック関数は、デバイスの要求オブジェクトを事前割り当てできます。

2. バッファー領域を指定し、 WdfUsbTargetDeviceFormatRequestForControlTransfer メソッドの TransferMemory パラメーターのバッファーのハンドルを指定します。

   ドライバーでは、フレームワークマネージド メモリへの WDFMEMORY ハンドルとしてこのバッファー領域を指定する必要があります。 ドライバーは、次のいずれかを実行できます。

   • ドライバーが新しいバッファーを I/O ターゲットに渡す場合は、 WdfMemoryCreate または WdfMemoryCreatePreallocated を呼び出して新しいメモリ バッファーを作成します。
   • ドライバーがそのバッファーの内容を I/O ターゲットに渡す場合は、 WdfRequestRetrieveInputMemory または WdfRequestRetrieveOutputMemory を呼び出して、受信した I/O 要求のバッファーを表すメモリ オブジェクトへのハンドルを取得します。
   ドライバーが WdfRequestRetrieveInputMemory または WdfRequestRetrieveOutputMemory を呼び出し、メモリ ハンドルを WdfUsbTargetDeviceFormatRequestForControlTransfer に渡す場合、ドライバーは、ドライバーが新しく作成した要求オブジェクトを削除、再利用、または再フォーマットするまで、受信した I/O 要求を完了しないようにする必要があることに注意してください。 (WdfUsbTargetDeviceFormatRequestForControlTransfer は、メモリ オブジェクトの参照カウントをインクリメントします。要求オブジェクトを削除、再利用、または再フォーマットすると、メモリ オブジェクトの参照カウントがデクリメントされます)。

同じ要求を使用する WdfUsbTargetDeviceFormatRequestForControlTransfer を 複数回呼び出しても、追加のリソース割り当ては発生しません。 そのため、 WdfRequestCreate がSTATUS_INSUFFICIENT_RESOURCESを返す可能性を減らすために、ドライバーの EvtDriverDeviceAdd コールバック関数は WdfRequestCreate を呼び出して、デバイスの 1 つ以上の要求オブジェクトを事前割り当てできます。 ドライバーは、その後、 WdfRequestReuse の呼び出し、再フォーマット ( WdfUsbTargetDeviceFormatRequestForControlTransfer の呼び出し)、および WdfRequestCreate への後の呼び出しからSTATUS_INSUFFICIENT_RESOURCES戻り値を危険にさらすことなく、各要求オブジェクトを再送信 (呼び出し WdfRequestSend) できます。 再利用された要求オブジェクトに対する WdfUsbTargetDeviceFormatRequestForControlTransfer に 対する後続のすべての呼び出しは、パラメーター値が変更されない場合、STATUS_SUCCESSを返します。 (ドライバーが毎回同じ要求形式メソッドを呼び出さない場合は、追加のリソースが割り当てられる可能性があります)。

フレームワークは、内部 URB に USBD_SHORT_TRANSFER_OK フラグを設定します。 このフラグを設定すると、データ転送の最後のパケットが最大パケット サイズより小さくなります。

I/O 要求の完了後に状態情報を取得する方法については、「 完了情報の取得」を参照してください。

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

例

次のコード例では、要求オブジェクトとメモリ オブジェクトを作成し、"get status" コントロール転送の WDF_USB_CONTROL_SETUP_PACKET 構造体を初期化します。 次に、この例では WdfUsbTargetDeviceFormatRequestForControlTransfer を呼び出して要求の書式を設定します。 次に、 CompletionRoutine コールバック関数を設定し、要求を I/O ターゲットに送信します。

WDF_USB_CONTROL_SETUP_PACKET packet;
NTSTATUS status;
WDF_OBJECT_ATTRIBUTES attributes;
WDFMEMORY memHandle;

WDF_OBJECT_ATTRIBUTES_INIT(&attributes);

status = WdfRequestCreate(
                          &attributes,
                          WdfUsbTargetDeviceGetIoTarget(
                              UsbTargetDevice,
                              &request
                              )
                          );
if (!NT_SUCCESS(status)){
    return status;
}

WDF_OBJECT_ATTRIBUTES_INIT(&attributes);
attributes.ParentObject = request;
status = WdfMemoryCreate(
                         &attributes,
                         NonPagedPool,
                         0,
                         sizeof(USHORT),
                         &memHandle,
                         NULL
                         );
if (!NT_SUCCESS(status)){
    return status;
}

WDF_USB_CONTROL_SETUP_PACKET_INIT_GET_STATUS(
                                             &packet,
                                             BmRequestToDevice,
                                             0
                                             );
status = WdfUsbTargetDeviceFormatRequestForControlTransfer(
                         UsbTargetDevice,
                         request,
                         &packet,
                         memHandle,
                         NULL
                         );
if (!NT_SUCCESS(status)){
    return status;
}
WdfRequestSetCompletionRoutine(
                               request,
                               MyCompletionRoutine,
                               NULL
                               );
if (WdfRequestSend(
                   request,
                   WdfUsbTargetDeviceGetIoTarget(UsbTargetDevice),
                   NULL
                   ) == FALSE) {
    status = WdfRequestGetStatus(request);
}

要件

こちらもご覧ください

WDF_USB_CONTROL_SETUP_PACKET

WDF_USB_CONTROL_SETUP_PACKET_INIT_GET_STATUS

WdfUsbTargetDeviceSendControlTransferSynchronously