WdfUsbTargetPipeWriteSynchronously 関数 (wdfusb.h)

[KMDF と UMDF に適用]

WdfUsbTargetPipeWriteSynchronously メソッドは、書き込み要求をビルドし、指定された USB 出力パイプに同期的に送信します。

構文

NTSTATUS WdfUsbTargetPipeWriteSynchronously(
  [in]            WDFUSBPIPE                Pipe,
  [in, optional]  WDFREQUEST                Request,
  [in, optional]  PWDF_REQUEST_SEND_OPTIONS RequestOptions,
  [in, optional]  PWDF_MEMORY_DESCRIPTOR    MemoryDescriptor,
  [out, optional] PULONG                    BytesWritten
);

パラメーター

[in] Pipe

WdfUsbInterfaceGetConfiguredPipe呼び出すことによって取得されたフレームワーク パイプ オブジェクトへのハンドル。

[in, optional] Request

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

[in, optional] RequestOptions

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

[in, optional] MemoryDescriptor

デバイスに書き込まれるデータを含むバッファーを記述する呼び出し元によって割り当てられた WDF_MEMORY_DESCRIPTOR 構造体へのポインター。 このバッファーの詳細については、次の「解説」セクションを参照してください。

[out, optional] BytesWritten

操作が成功した場合に書き込まれたバイト数を受け取る場所へのポインター。 このパラメーターは省略可能であり、NULLできます。

戻り値

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

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

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

備考

WdfUsbTargetPipeWriteSynchronously メソッドを使用して、書き込み要求を同期的に送信します。 書き込み要求を非同期に送信するには、WdfUsbTargetPipeFormatRequestForWriteを使用し、その後に WdfRequestSendします。

指定するパイプは出力パイプでなければならず、パイプの の種類 WdfUsbPipeTypeBulk または WdfUsbPipeTypeInterruptする必要があります。

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

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

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

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

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

ドライバーは、多くの場合、受信した I/O 要求を、I/O ターゲットに送信する小さな要求に分割するため、ドライバーは新しい要求を作成する可能性があります。

新しい I/O 要求を作成するには:

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

   ドライバーは、以外の NULL または NULLRequest パラメーターを提供するかどうかに関係なく、NULLRequestOptions パラメーターを指定できます。 たとえば、RequestOptions パラメーターを使用してタイムアウト値を指定できます。

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

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

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

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

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

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

   • MDL を提供する

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

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

例

次のコード例では、メモリ オブジェクトを作成し、オブジェクトのバッファーへのポインターを取得し、バッファーを埋め、バッファーを入力として使用して WdfUsbTargetPipeWriteSynchronouslyします。

WDF_MEMORY_DESCRIPTOR  writeBufDesc;
WDFMEMORY  wdfMemory;
ULONG  writeSize, bytesWritten;
size_t  bufferSize;
NTSTATUS status;

writeSize = SMALL_BUF_LEN;
status = WdfMemoryCreate(
                         WDF_NO_OBJECT_ATTRIBUTES,
                         NonPagedPool,
                         0,
                         writeSize,
                         &wdfMemory,
                         NULL
                         );
if (!NT_SUCCESS(status)){
    return status;
}

writeBuffer = WdfMemoryGetBuffer(
                                 wdfMemory,
                                 &bufferSize
                                 );

FillMyBuffer(
             writeBuffer,
             writeSize
             );

WDF_MEMORY_DESCRIPTOR_INIT_BUFFER(
                                  &writeBufDesc,
                                  writeBuffer,
                                  writeSize
                                  );

status = WdfUsbTargetPipeWriteSynchronously(
                                            pipeHandle,
                                            NULL,
                                            NULL,
                                            &writeBufDesc,
                                            &bytesWritten
                                            );

必要条件

関連項目

WDF_MEMORY_DESCRIPTOR_INIT_BUFFER

WdfMemoryCreate

WdfMemoryGetBuffer の

WdfRequestCancelSentRequest

WdfUsbTargetPipeReadSynchronously を する