WdfIoTargetSendWriteSynchronously 関数 (wdfiotarget.h)
[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
[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 要求の完了後に戻り、戻り値は要求の完了状態値になります。 それ以外の場合、このメソッドは次のいずれかの値を返す可能性があります。
| リターン コード | 形容 |
|---|---|
|
無効なパラメーターが検出されました。 |
|
RequestOptions パラメーターが指す WDF_REQUEST_SEND_OPTIONS 構造体のサイズが正しくありません。 |
|
I/O 要求は既に I/O ターゲットにキューに登録されています。 |
|
フレームワークは、システム リソース (通常はメモリ) を割り当てませんでした。 |
|
ドライバーがタイムアウト値を指定し、割り当てられた時間内に要求が完了しませんでした。 |
|
要求 パラメーターが表す I/O 要求パケット (IRP) は、ドライバーが要求を転送するのに十分な IO_STACK_LOCATION 構造体を提供しません。 |
このメソッドは、他の
ドライバーが無効なオブジェクト ハンドルを提供すると、バグ チェックが発生します。
備考
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 要求を作成するには:
-
WdfIoTargetSendWriteSynchronously メソッドの Request パラメーターに対して、NULL 要求ハンドルを指定するか、新しい要求オブジェクトを作成してそのハンドルを指定します。
- NULL 要求ハンドルを指定すると、フレームワークは内部要求オブジェクトを使用します。 この手法は簡単に使用できますが、ドライバーは要求をキャンセルできません。
WdfRequestCreate を呼び出して 1 つ以上の要求オブジェクトを作成する場合は、WdfRequestReuse呼び出すことによって、これらの要求オブジェクトを再利用できます。 この手法を使用すると、ドライバーの EvtDriverDeviceAdd コールバック関数を使用して、デバイスの要求オブジェクトを事前に割り当てることができます。 さらに、別のドライバー スレッドは、WdfRequestCancelSentRequest を呼び出して、必要に応じて要求を取り消すことができます。
ドライバーは、以外の NULL または NULLRequest パラメーターを提供するかどうかに関係なく、NULLRequestOptions パラメーターを指定できます。 たとえば、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 要求が完了した後の状態情報の取得については、「完了情報の取得を参照してください。
WdfIoTargetSendWriteSynchronously
I/O ターゲットの詳細については、「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 |
| ヘッダー | wdfiotarget.h (Wdf.h を含む) |
| ライブラリ | Wdf01000.sys (KMDF);WUDFx02000.dll (UMDF) |
| IRQL | <=PASSIVE_LEVEL |
| DDI コンプライアンス規則 を |
DeferredRequestCompleted(kmdf), DriverCreate(kmdf), InternalIoctlReqs(kmdf), IoctlReqs(kmdf), KmdfIrql(kmdf), KmdfIrql 2(kmdf), KmdfIrqlExplicit(kmdf), ReadReqs(kmdf), RequestCompleted(kmdf), RequestCompletedLocal(kmdf), SyncReqSend(km) |
関連項目
EvtDriverDeviceAdd の
WDF_MEMORY_DESCRIPTOR_INIT_HANDLE
WdfDeviceGetIoTarget の
WdfIoTargetCreate の
WdfIoTargetFormatRequestForWrite の
WdfMemoryCreatePreallocated の