WdfUsbTargetDeviceSendControlTransferSynchronously 関数 (wdfusb.h)

[KMDF と UMDF に適用]

WdfUsbTargetDeviceSendControlTransferSynchronously メソッドは、USB コントロール転送要求をビルドし、I/O ターゲットに同期的に送信します。

構文

NTSTATUS WdfUsbTargetDeviceSendControlTransferSynchronously(
  [in]            WDFUSBDEVICE                  UsbDevice,
  [in, optional]  WDFREQUEST                    Request,
  [in, optional]  PWDF_REQUEST_SEND_OPTIONS     RequestOptions,
  [in]            PWDF_USB_CONTROL_SETUP_PACKET SetupPacket,
  [in, optional]  PWDF_MEMORY_DESCRIPTOR        MemoryDescriptor,
  [out, optional] PULONG                        BytesTransferred
);

パラメーター

[in] UsbDevice

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

[in, optional] Request

フレームワーク要求オブジェクトへのハンドル。 このパラメーターは省略可能であり、 NULL にすることができます。 詳細については、「解説」を参照してください。

[in, optional] RequestOptions

要求のオプションを指定する呼び出し元によって割り当てられた WDF_REQUEST_SEND_OPTIONS 構造体へのポインター。 このポインターは省略可能であり、 NULL にすることができます。 詳細については、「解説」を参照してください。

[in] SetupPacket

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

[in, optional] MemoryDescriptor

デバイス固有のコマンドに応じて、入力バッファーまたは出力バッファーを記述する呼び出し元によって割り当てられた WDF_MEMORY_DESCRIPTOR 構造体へのポインター。 このポインターは省略可能であり、 NULL にすることができます。 詳細については、「解説」を参照してください。

[out, optional] BytesTransferred

転送されるバイト数を受け取る場所へのポインター。 このパラメーターは省略可能であり、 NULL にすることができます。

戻り値

操作が成功した場合、WdfUsbTargetDeviceSendControlTransferSynchronously は I/O ターゲットの完了状態値を返します。 それ以外の場合、このメソッドは次のいずれかの値を返すことができます。

リターン コード 説明
STATUS_INVALID_PARAMETER
無効なパラメーターが検出されました。
STATUS_INSUFFICIENT_RESOURCES
メモリ不足が使用可能でした。
STATUS_INVALID_DEVICE_REQUEST
無効なメモリ記述子が指定されたか、指定された I/O 要求が既に I/O ターゲットにキューに登録されています。
STATUS_IO_TIMEOUT
ドライバーはタイムアウト値を指定し、割り当てられた時間内に要求が完了しませんでした。
 

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

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

注釈

USB コントロール転送要求を同期的に送信するには、 WdfUsbTargetDeviceSendControlTransferSynchronously メソッドを使用します。 このような要求を非同期に送信するには、 WdfUsbTargetDeviceFormatRequestForControlTransferWdfRequestSend を使用します。

WdfUsbTargetDeviceSendControlTransferSynchronously メソッドは、要求が完了するまで戻りません。ただし、ドライバーが RequestOptions パラメーターが指すWDF_REQUEST_SEND_OPTIONS構造体のタイムアウト値を指定しない限り、またはエラーが検出されない限り、

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

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

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

    ドライバーは、WdfRequestRetrieveInputMemory または WdfRequestRetrieveOutputMemory を呼び出して、要求の入力バッファーまたは出力バッファーを表すフレームワーク メモリ オブジェクトへのハンドルを取得し、ドライバーが MemoryDescriptor パラメーターに提供するWDF_MEMORY_DESCRIPTOR構造体にそのハンドルを配置できます。

新しい要求を作成して送信するには:
  1. Request パラメーターに NULL 要求ハンドルを 指定 するか、新しい要求オブジェクトを作成してそのハンドルを指定します。
    • NULL 要求ハンドルを指定すると、フレームワークは内部要求オブジェクトを使用します。 この手法は簡単に使用できますが、ドライバーは要求を取り消すことができません。
    • WdfRequestCreate を呼び出して 1 つ以上の要求オブジェクトを作成する場合は、WdfRequestReuse を呼び出すことによって、これらの要求オブジェクトを再利用できます。 この手法により、ドライバーの EvtDriverDeviceAdd コールバック関数は、デバイスの要求オブジェクトを事前に割り当てることができます。 さらに、別のドライバー スレッドは、必要に応じて、要求を取り消すために WdfRequestCancelSentRequest を呼び出すことができます。

    ドライバーは NULL 以外のRequestOptions パラメーターを指定できます。これは、ドライバーが NULL 以外の要求パラメーターまたは NULL要求パラメーターを提供するかどうかです。 たとえば、 RequestOptions パラメーターを使用してタイムアウト値を指定できます。

  2. WdfUsbTargetDeviceSendControlTransferSynchronously メソッドの MemoryDescriptor パラメーターのバッファー領域を指定します。

    ドライバーは、ローカルに割り当てられたバッファー、WDFMEMORY ハンドル、または MDL として、このバッファー領域を指定できます。 最も便利な方法を使用できます。

    必要に応じて、フレームワークはバッファーの説明を、データ バッファーにアクセスするための I/O ターゲットの メソッドに適した記述に変換します。

    次の手法を使用できます。

    • ローカル バッファーを指定する

      WdfUsbTargetDeviceSendControlTransferSynchronously は I/O 要求を同期的に処理するため、次のコード例に示すように、ドライバーは呼び出し元ルーチンに対してローカルな要求バッファーを作成できます。

      WDF_MEMORY_DESCRIPTOR  memoryDescriptor;
      MY_BUFFER_TYPE  myBuffer;
      WDF_MEMORY_DESCRIPTOR_INIT_BUFFER(&memoryDescriptor,
                                        (PVOID) &myBuffer,
                                        sizeof(myBuffer));
      
    • WDFMEMORY ハンドルを指定する

      次のコード例に示すように、 WdfMemoryCreate または WdfMemoryCreatePreallocated を呼び出して、フレームワークマネージド メモリへのハンドルを取得します。

      WDF_MEMORY_DESCRIPTOR  memoryDescriptor;
      WDFMEMORY  memoryHandle = NULL;
      status = WdfMemoryCreate(NULL,
                               NonPagedPool,
                               POOL_TAG,
                               MY_BUFFER_SIZE,
                               &memoryHandle,
                               NULL);
      WDF_MEMORY_DESCRIPTOR_INIT_HANDLE(&memoryDescriptor,
                                        memoryHandle,
                                        NULL);
      

      または、ドライバーは WdfRequestRetrieveInputMemory または WdfRequestRetrieveOutputMemory を呼び出して、受信した I/O 要求のバッファーを表すフレームワーク メモリ オブジェクトへのハンドルを取得できます (ドライバーがそのバッファーの内容を I/O ターゲットに渡す場合)。 ドライバーは、 WdfUsbTargetDeviceSendControlTransferSynchronously が I/O ターゲットに送信する新しい要求が削除、再利用、または再フォーマットされるまで、受信した I/O 要求を完了できません。 (WdfUsbTargetDeviceSendControlTransferSynchronously メモリ オブジェクトの参照カウントをインクリメントします。要求オブジェクトを削除、再利用、または再フォーマットすると、メモリ オブジェクトの参照カウントがデクリメントされます)。

    • MDL を指定する

      ドライバーは、WdfRequestRetrieveInputWdmMdl または WdfRequestRetrieveOutputWdmdl を呼び出すことによって、受信した I/O 要求に関連付けられている MDL を取得できます。

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

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

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

次のコード例では 、WDF_USB_CONTROL_SETUP_PACKET 構造体を初期化し、 WdfUsbTargetDeviceSendControlTransferSynchronously を呼び出してベンダー固有の制御転送を送信します。

WDF_USB_CONTROL_SETUP_PACKET  controlSetupPacket;

WDF_USB_CONTROL_SETUP_PACKET_INIT_VENDOR(
                                         &controlSetupPacket,
                                         BmRequestHostToDevice,
                                         BmRequestToDevice,
                                         USBFX2LK_REENUMERATE,
                                         0,
                                         0
                                         );

status = WdfUsbTargetDeviceSendControlTransferSynchronously(
                                         UsbDevice,
                                         WDF_NO_HANDLE,
                                         NULL,
                                         &controlSetupPacket,
                                         NULL,
                                         NULL
                                         );
return status;

要件

   
対象プラットフォーム ユニバーサル
最小 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)、 RequestForUrbXrb(kmdf)SyncReqSend(kmdf)UsbKmdfIrql(kmdf)UsbKmdfIrql2(kmdf)、UsbKmdfIrqlExplicit(kmdf)

こちらもご覧ください

WDF_USB_CONTROL_SETUP_PACKET

WDF_USB_CONTROL_SETUP_PACKET_INIT_VENDOR

WdfRequestCancelSentRequest

WdfUsbTargetDeviceFormatRequestForControlTransfer

WdfUsbTargetDeviceSendUrbSynchronously