WdfIoTargetSendWriteSynchronously 関数 (wdfiotarget.h)

[アーティクル]
03/08/2023

[KMDF と UMDF に適用]

WdfIoTargetSendWriteSynchronously メソッドは、書き込み要求をビルドし、I/O ターゲットに同期的に送信します。

構文

NTSTATUS WdfIoTargetSendWriteSynchronously(
  [in]            WDFIOTARGET               IoTarget,
  [in, optional]  WDFREQUEST                Request,
  [in, optional]  PWDF_MEMORY_DESCRIPTOR    InputBuffer,
  [in, optional]  PLONGLONG                 DeviceOffset,
  [in, optional]  PWDF_REQUEST_SEND_OPTIONS RequestOptions,
  [out, optional] PULONG_PTR                BytesWritten
);

パラメーター

[in] IoTarget

WdfDeviceGetIoTarget または WdfIoTargetCreate の以前の呼び出し、または特殊化された I/O ターゲットが提供するメソッドから取得されたローカルまたはリモートの I/O ターゲットオブジェクトへのハンドル。

[in, optional] Request

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

[in, optional] InputBuffer

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

[in, optional] DeviceOffset

転送の開始オフセットを指定する場所へのポインター。 I/O ターゲット (つまり、次の下位ドライバー) は、この値の使用方法を定義します。たとえば、ディスクのドライバースタック内のドライバーは、ディスクの先頭からのオフセットを指定する場合があります。 I/O ターゲットは、要求のWDF_REQUEST_PARAMETERS構造体の Parameters.Write.DeviceOffset メンバーでこの情報を取得します。このポインターは省略可能です。ほとんどのドライバーは、このポインターを NULL に設定 します。

[in, optional] RequestOptions

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

[out, optional] BytesWritten

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

戻り値

操作が成功した場合、 WdfIoTargetSendWriteSynchronously は I/O 要求の完了後にを返し、戻り値は要求の完了状態値です。それ以外の場合、このメソッドは次のいずれかの値を返す可能性があります。

リターンコード	説明
STATUS_INVALID_PARAMETER	無効なパラメーターが検出されました。
STATUS_INFO_LENGTH_MISMATCH	RequestOptions パラメーターが指すWDF_REQUEST_SEND_OPTIONS構造体のサイズが正しくありません。
STATUS_INVALID_DEVICE_REQUEST	I/O 要求は既に I/O ターゲットにキューに入れられました。
STATUS_INSUFFICIENT_RESOURCES	フレームワークはシステムリソース (通常はメモリ) を割り当てませんでした。
STATUS_IO_TIMEOUT	ドライバーはタイムアウト値を指定し、割り当てられた時間内に要求が完了しませんでした。
STATUS_REQUEST_NOT_ACCEPTED	要求パラメーターが表す I/O 要求パケット (IRP) は、ドライバーが要求を転送できるようにするための十分なIO_STACK_LOCATION構造を提供しません。

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

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

注釈

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

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

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

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

WdfIoTargetSendWriteSynchronously メソッドの Request パラメーターに対して、受信した要求のハンドルを指定します。
WdfIoTargetSendWriteSynchronously メソッドの InputBuffer パラメーターには、受信した要求の入力バッファーを使用します。
ドライバーは WdfRequestRetrieveInputMemory を呼び出して、要求の入力バッファーを表すフレームワークメモリオブジェクトへのハンドルを取得し、そのハンドルを、ドライバーが InputBuffer パラメーターに提供するWDF_MEMORY_DESCRIPTOR構造体に配置する必要があります。

I/O 要求の転送の詳細については、「I /O 要求の転送」を参照してください。

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

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

WdfIoTargetSendWriteSynchronously メソッドの Request パラメーターに NULL 要求ハンドルを指定するか、新しい要求オブジェクトを作成してそのハンドルを指定します。
- NULL 要求ハンドルを指定すると、フレームワークは内部要求オブジェクトを使用します。この手法は簡単に使用できますが、ドライバーは要求をキャンセルできません。
- WdfRequestCreate を呼び出して 1 つ以上の要求オブジェクトを作成する場合は、WdfRequestReuse を呼び出すことで、これらの要求オブジェクトを再利用できます。この手法を使用すると、ドライバーの EvtDriverDeviceAdd コールバック関数を使用して、デバイスの要求オブジェクトを事前に割り当てできます。さらに、別のドライバースレッドは WdfRequestCancelSentRequest を呼び出して、必要に応じて要求を取り消すことができます。
ドライバーは、NULL 以外の RequestOptions パラメーターを指定できます。これは、ドライバーが NULL 以外の要求パラメーターまたは NULL要求パラメーターを提供するかどうかです。たとえば、 RequestOptions パラメーターを使用してタイムアウト値を指定できます。
WdfIoTargetSendWriteSynchronously メソッドの InputBuffer パラメーターにバッファー領域を指定します。
ドライバーでは、ローカルに割り当てられたバッファーとして、WDFMEMORY ハンドルとして、またはメモリ記述子リスト (MDL) として、このバッファー領域を指定できます。最も便利な方法を使用できます。

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

バッファー領域を指定するには、次の手法を使用できます。
- ローカルバッファーを指定します。
  WdfIoTargetSendWriteSynchronously は 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 ターゲットに渡す場合)。 WdfIoTargetSendWriteSynchronously が I/O ターゲットに送信する新しい要求が削除、再利用、または再フォーマットされるまで、ドライバーは受信した I/O 要求を完了してはなりません。 (WdfIoTargetSendWriteSynchronously は、メモリオブジェクトの参照カウントをインクリメントします。要求オブジェクトを削除、再利用、または再フォーマットすると、メモリオブジェクトの参照カウントがデクリメントされます)。
- MDL を指定します。
  ドライバーは、 WdfRequestRetrieveInputWdmMdl を呼び出すことによって、受信した I/O 要求に関連付けられている MDL を取得できます。

一部の I/O ターゲットは、長さ 0 のバッファーを持つ書き込み要求を受け入れます。このような I/O ターゲットの場合、ドライバーは InputBuffer パラメーターに NULL を指定できます。

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

WdfIoTargetSendWriteSynchronously の詳細については、「一般的な I/O ターゲットへの I/O 要求の送信」を参照してください。

I/O ターゲットの詳細については、「I /O ターゲットの使用」を参照してください。

例

次のコード例では、フレームワークメモリオブジェクトを作成し、 WDF_MEMORY_DESCRIPTOR 構造体を初期化し、その構造体を WdfIoTargetSendWriteSynchronously に渡します。この例では、要求オブジェクトハンドルに NULL を 指定するため、フレームワークは I/O ターゲットの新しい要求オブジェクトを作成します。

WDF_MEMORY_DESCRIPTOR  MemoryDescriptor;
WDFMEMORY  MemoryHandle = NULL;
ULONG_PTR  bytesWritten = NULL;

status = WdfMemoryCreate(
                         NULL,
                         NonPagedPool,
                         POOL_TAG,
                         MY_BUFFER_SIZE,
                         &MemoryHandle,
                         NULL
                         );
WDF_MEMORY_DESCRIPTOR_INIT_HANDLE(
                                  &MemoryDescriptor,
                                  MemoryHandle,
                                  NULL
                                  );
status = WdfIoTargetSendWriteSynchronously(
                                          ioTarget,
                                          NULL,
                                          &MemoryDescriptor,
                                          NULL,
                                          NULL,
                                          &bytesWritten
                                          );

要件

要件	値
対象プラットフォーム	ユニバーサル
最小 KMDF バージョン	1.0
最小 UMDF バージョン	2.0
Header	wdfiotarget.h (Wdf.h を含む)
Library	Wdf01000.sys (KMDF);WUDFx02000.dll (UMDF)
IRQL	<=PASSIVE_LEVEL
DDI コンプライアンス規則	DeferredRequestCompleted(kmdf)、DriverCreate(kmdf)、InternalIoctlReqs(kmdf)、IoctlReqs(kmdf)、KmdfIrql(kmdf)、KmdfIrql2 (kmdf)、KmdfIrqlExplicit(kmdf)、ReadReqs(kmdf)、RequestCompleted(kmdf)、RequestCompletedLocal(kmdf)、SyncReqSend(kmdf)