WdfIoTargetSendIoctlSynchronously 関数 (wdfiotarget.h)

[アーティクル]
07/16/2024

[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 は、デバイス制御要求が完了した後に返されます。戻り値は要求の完了状態値です。それ以外の場合、このメソッドは次のいずれかの値を返す可能性があります。

リターンコード	形容
STATUS_INVALID_PARAMETER	無効なパラメーターが検出されました。
STATUS_INFO_LENGTH_MISMATCH	RequestOptions パラメーターが指す WDF_REQUEST_SEND_OPTIONS 構造体のサイズが正しくありません。
STATUS_INVALID_DEVICE_REQUEST	要求は既に I/O ターゲットにキューに入れられました。
STATUS_INSUFFICIENT_RESOURCES	フレームワークは、システムリソース (通常はメモリ) を割り当てることができません。
STATUS_REQUEST_NOT_ACCEPTED	要求パラメーターが表す 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 を呼び出す必要があります。その後、ドライバーは、WdfIoTargetSendIoctlSynchronouslyの InputBuffer パラメーターにドライバーが提供する WDF_MEMORY_DESCRIPTOR 構造体にそのハンドル配置する必要があります。
WdfIoTargetSendIoctlSynchronously メソッドの OutputBuffer パラメーターに対して、受信した要求の出力バッファー使用します。
ドライバーは、要求の出力バッファー表すフレームワークメモリオブジェクトへのハンドルを取得する WdfRequestRetrieveOutputMemory を呼び出す必要があります。その後、ドライバーは、WdfIoTargetSendIoctlSynchronouslyの OutputBuffer パラメーターにドライバーが提供する WDF_MEMORY_DESCRIPTOR 構造体にそのハンドル配置する必要があります。

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

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

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

WdfIoTargetSendIoctlSynchronously メソッドの Request パラメーターに対して、NULL 要求ハンドルを指定するか、新しい要求オブジェクトを作成してそのハンドルを指定します。
- NULL 要求ハンドルを指定すると、フレームワークは内部要求オブジェクトを使用します。この手法は簡単に使用できますが、ドライバーは要求をキャンセルできません。
- WdfRequestCreate を呼び出して 1 つ以上の要求オブジェクトを作成する場合は、WdfRequestReuse呼び出すことによって、これらの要求オブジェクトを再利用できます。この手法を使用すると、ドライバーの EvtDriverDeviceAdd コールバック関数を使用して、デバイスの要求オブジェクトを事前に割り当てることができます。さらに、別のドライバースレッドは、WdfRequestCancelSentRequest を呼び出して、必要に応じて要求を取り消すことができます。
ドライバーは、以外の NULL または NULLRequest パラメーターを提供するかどうかに関係なく、NULLRequestOptions パラメーターを指定できます。たとえば、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 を取得できます。

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

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
ヘッダー	wdfiotarget.h (Wdf.h を含む)
ライブラリ	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)

次の方法で共有

WdfIoTargetSendIoctlSynchronously 関数 (wdfiotarget.h)

構文

パラメーター

戻り値

備考

例

必要条件

関連項目

フィードバック

フィードバック

その他のリソース