WdfIoTargetSendIoctlSynchronously 関数 (wdfiotarget.h)
[KMDF と UMDF に適用]
WdfIoTargetSendIoctlSynchronously メソッドは、デバイス制御要求をビルドし、I/O ターゲットに同期的に送信します。
構文
NTSTATUS WdfIoTargetSendIoctlSynchronously(
[in] WDFIOTARGET IoTarget,
[in, optional] WDFREQUEST Request,
[in] ULONG IoctlCode,
[in, optional] PWDF_MEMORY_DESCRIPTOR InputBuffer,
[in, optional] PWDF_MEMORY_DESCRIPTOR OutputBuffer,
[in, optional] PWDF_REQUEST_SEND_OPTIONS RequestOptions,
[out, optional] PULONG_PTR BytesReturned
);
パラメーター
[in] IoTarget
WdfDeviceGetIoTarget または WdfIoTargetCreate の以前の呼び出しから取得されたローカルまたはリモートの I/O ターゲット オブジェクト、または特殊な I/O ターゲットが提供するメソッドからのハンドル。
[in, optional] Request
フレームワーク要求オブジェクトへのハンドル。 このパラメーターは省略可能であり、 NULL にすることができます。 詳細については、「解説」を参照してください。
[in] IoctlCode
I/O ターゲットがサポートする I/O 制御コード (IOCTL)。
[in, optional] InputBuffer
I/O ターゲットに書き込まれるバッファーを記述する呼び出し元によって割り当てられた WDF_MEMORY_DESCRIPTOR 構造体へのポインター。 詳細については、「解説」を参照してください。 このパラメーターは省略可能であり、要求がデータを送信しない場合は NULL にすることができます 。
[in, optional] OutputBuffer
I/O ターゲットからデータを受信するバッファーを記述する呼び出し元によって割り当てられた WDF_MEMORY_DESCRIPTOR 構造体へのポインター。 詳細については、「解説」を参照してください。 このパラメーターは省略可能であり、要求がデータを受信しない場合は NULL にすることができます 。
[in, optional] RequestOptions
要求のオプションを指定する呼び出し元によって割り当てられた WDF_REQUEST_SEND_OPTIONS 構造体へのポインター。 このポインターは省略可能であり、 NULL にすることができます。 詳細については、「解説」を参照してください。
[out, optional] BytesReturned
別のドライバーが WdfRequestCompleteWithInformation を呼び出して要求を完了したときに提供する情報 (転送されたバイト数など) を受け取る場所へのポインター。 このポインターは省略可能であり、 NULL にすることができます。
戻り値
操作が成功した場合、 WdfIoTargetSendIoctlSynchronously はデバイス制御要求の完了後にを返し、戻り値は要求の完了状態値です。 それ以外の場合、このメソッドは次のいずれかの値を返す可能性があります。
リターン コード | 説明 |
---|---|
|
無効なパラメーターが検出されました。 |
|
RequestOptions パラメーターが指すWDF_REQUEST_SEND_OPTIONS構造体のサイズが正しくありません。 |
|
要求は既に I/O ターゲットにキューに登録されています。 |
|
フレームワークは、システム リソース (通常はメモリ) を割り当てることができません。 |
|
要求パラメーターが表す I/O 要求パケット (IRP) は、ドライバーが 要求 を転送できるようにするため の十 分なIO_STACK_LOCATION構造体を提供しません。 |
このメソッドは、他の NTSTATUS 値を返す場合もあります。
ドライバーが無効なオブジェクト ハンドルを提供すると、バグ チェックが発生します。
注釈
デバイス制御要求を同期的に送信するには、 WdfIoTargetSendIoctlSynchronously メソッドを使用します。 デバイス制御要求を非同期的に送信するには、 WdfIoTargetFormatRequestForIoctl メソッドを使用し、その後に WdfRequestSend メソッドを使用します。
デバイス制御要求の詳細については、「 I/O 制御コードの使用」を参照してください。
WdfIoTargetSendIoctlSynchronously メソッドは、要求が完了するまで戻りません。ただし、ドライバーが RequestOptions パラメーターのWDF_REQUEST_SEND_OPTIONS構造体にタイムアウト値を指定しない限り、またはエラーが検出されない限り返されません。
ドライバーが I/O キューで受信したデバイス制御要求を転送することも、新しい要求を作成して送信することもできます。 どちらの場合も、フレームワークには要求オブジェクトとバッファー領域が必要です。
ドライバーが I/O キューで受信したデバイス制御要求を転送するには:
- WdfIoTargetSendIoctlSynchronously メソッドの Request パラメーターに対して、受信した要求のハンドルを指定します。
-
WdfIoTargetSendIoctlSynchronously メソッドの InputBuffer パラメーターには、受信した要求の入力バッファーを使用します。
ドライバーは WdfRequestRetrieveInputMemory を呼び出して、要求の入力バッファーを表すフレームワーク メモリ オブジェクトへのハンドルを取得する必要があります。 その後、ドライバーは、ドライバーが WdfIoTargetSendIoctlSynchronousously の InputBuffer パラメーターに指定するWDF_MEMORY_DESCRIPTOR構造体にそのハンドルを配置する必要があります。
-
WdfIoTargetSendIoctlSynchronously メソッドの OutputBuffer パラメーターには、受信した要求の出力バッファーを使用します。
ドライバーは、要求の出力バッファーを表すフレームワーク メモリ オブジェクトへのハンドルを取得するには、 WdfRequestRetrieveOutputMemory を呼び出す必要があります。 その後、ドライバーは、ドライバーが WdfIoTargetSendIoctlSynchronousously の OutputBuffer パラメーターに指定するWDF_MEMORY_DESCRIPTOR構造体にそのハンドルを配置する必要があります。
ドライバーは、多くの場合、受信した I/O 要求を、I/O ターゲットに送信する小さな要求に分割するため、ドライバーは新しい要求を作成する可能性があります。
新しい I/O 要求を作成するには:
-
WdfIoTargetSendIoctlSynchronously メソッドの Request パラメーターに NULL 要求ハンドルを指定するか、新しい要求オブジェクトを作成してそのハンドルを指定します。
- NULL 要求ハンドルを指定すると、フレームワークは内部要求オブジェクトを使用します。 この手法は簡単に使用できますが、ドライバーは要求を取り消すことができません。
- WdfRequestCreate を呼び出して 1 つ以上の要求オブジェクトを作成する場合は、WdfRequestReuse を呼び出してこれらの要求オブジェクトを再利用できます。 この手法を使用すると、ドライバーの EvtDriverDeviceAdd コールバック関数を使用して、デバイスの要求オブジェクトを事前に割り当てることができます。 さらに、別のドライバー スレッドは WdfRequestCancelSentRequest を呼び出して、必要に応じて要求を取り消すことができます。
ドライバーは、NULL 以外の RequestOptions パラメーターを指定できます。ドライバーが NULL 以外の要求パラメーターと NULL要求パラメーターのどちらを提供しているか。 たとえば、 RequestOptions パラメーターを使用してタイムアウト値を指定できます。
-
要求に必要な場合は、 WdfIoTargetSendIoctlSynchronously メソッドの InputBuffer パラメーターと OutputBuffer パラメーターのバッファー領域を指定します。
ドライバーでは、このバッファー領域をローカルに割り当てられたバッファーとして、WDFMEMORY ハンドルとして、またはメモリ記述子リスト (MDL) として指定できます。 最も便利な方法を使用できます。
必要に応じて、フレームワークは、IOCTL の転送の種類に合ったバッファーの説明を変換します。 IOCTL 転送の種類の詳細については、「 I/O 制御コードの定義」を参照してください。
バッファー領域を指定する次の手法を使用できます。
-
ローカル バッファーを指定します。
WdfIoTargetSendIoctlSynchronously は 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 ターゲットに渡す場合)。 ドライバーは、 WdfIoTargetSendIoctlSynchronously が I/O ターゲットに送信する新しい要求が削除、再利用、または再フォーマットされるまで、受信した I/O 要求を完了することはできません。 (WdfIoTargetSendIoctlSynchronously は、メモリ オブジェクトの参照カウントをインクリメントします。要求オブジェクトを削除、再利用、または再フォーマットすると、メモリ オブジェクトの参照カウントがデクリメントされます)。
-
MDL を指定します。
ドライバーは、WdfRequestRetrieveInputWdmMdl と WdfRequestRetrieveOutputWdmmdl を呼び出すことによって、受信した I/O 要求に関連付けられている MDL を取得できます。
-
ローカル バッファーを指定します。
WdfIoTargetSendIoctlSynchronously の詳細については、「一般的な I/O ターゲットへの I/O 要求の送信」を参照してください。
I/O ターゲットの詳細については、「 I/O ターゲットの使用」を参照してください。
例
次のコード例では、ローカル バッファーを定義し、 WDF_MEMORY_DESCRIPTOR 構造体を初期化し、 WdfIoTargetSendIoctlSynchronously を呼び出します。 この例では、要求オブジェクト ハンドルに NULL を 指定するため、フレームワークは I/O ターゲットの新しい要求オブジェクトを作成します。
WDF_MEMORY_DESCRIPTOR outputDescriptor;
NTSTATUS status;
HID_COLLECTION_INFORMATION collectionInformation;
WDF_MEMORY_DESCRIPTOR_INIT_BUFFER(
&outputDescriptor,
(PVOID) &collectionInformation,
sizeof(HID_COLLECTION_INFORMATION)
);
status = WdfIoTargetSendIoctlSynchronously(
hidTarget,
NULL,
IOCTL_HID_GET_COLLECTION_INFORMATION,
NULL,
&outputDescriptor,
NULL,
NULL
);
要件
要件 | 値 |
---|---|
対象プラットフォーム | ユニバーサル |
最小 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)、 KmdfIrql(kmdf)、 KmdfIrql2(kmdf)、KmdfIrqlExplicit(kmdf)、 ReadReqs(kmdf)、 RequestCompleted(kmdf)、 RequestCompletedLocal(kmdf)、 SyncReqSend(kmdf)、 WriteReqs(kmdf) |
こちらもご覧ください
WDF_MEMORY_DESCRIPTOR_INIT_BUFFER
WdfIoTargetFormatRequestForIoctl
WdfIoTargetSendInternalIoctlSynchronously
WdfRequestCompleteWithInformation
WdfRequestRetrieveOutputMemory
フィードバック
https://aka.ms/ContentUserFeedback」を参照してください。
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「フィードバックの送信と表示