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

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

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

備考

WdfIoTargetSendIoctlSynchronously メソッドを使用して、デバイス制御要求を同期的に送信します。 デバイス制御要求を非同期的に送信するには、WdfIoTargetFormatRequestForIoctl メソッドを使用し、その後に WdfRequestSend メソッドを使用します。

デバイス制御要求の詳細については、「I/O 制御コードの使用」を参照してください。

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

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

ドライバーが I/O キューで受信したデバイス コントロール要求を転送するには:

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

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

3. WdfIoTargetSendIoctlSynchronously メソッドの OutputBuffer パラメーターに対して、受信した要求の出力バッファー 使用します。

   ドライバーは、要求の出力バッファー 表すフレームワーク メモリ オブジェクトへのハンドルを取得する WdfRequestRetrieveOutputMemory を呼び出す必要があります。 その後、ドライバーは、WdfIoTargetSendIoctlSynchronouslyの OutputBuffer パラメーターにドライバーが提供する WDF_MEMORY_DESCRIPTOR 構造体にそのハンドル 配置する必要があります。

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

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

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

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

2. 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
                                           );

必要条件

関連項目

EvtDriverDeviceAdd の

WDF_MEMORY_DESCRIPTOR

WDF_MEMORY_DESCRIPTOR_INIT_BUFFER

WDF_REQUEST_SEND_OPTIONS

WdfDeviceGetIoTarget の

WdfIoTargetCreate の

WdfIoTargetFormatRequestForIoctl

WdfIoTargetSendInternalIoctlSynchronously

WdfMemoryCreate

WdfMemoryCreatePreallocated の

WdfRequestCancelSentRequest

WdfRequestCompleteWithInformation の

WdfRequestCreate

WdfRequestRetrieveInputMemory

WdfRequestRetrieveInputWdmMdl

WdfRequestRetrieveOutputMemory

WdfRequestRetrieveOutputWdmMdl

WdfRequestReuse