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

リターン コード 説明
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 キューで受信したデバイス制御要求を転送するには:

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

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

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

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

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

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

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

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

    ドライバーは NULL 以外のRequestOptions パラメーターを指定できます。これは、ドライバーが NULL 以外の要求パラメーターまたは NULL要求パラメーターを提供するかどうかです。 たとえば、 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 を指定します。

      ドライバーは、 WdfRequestRetrieveInputWdmMdlWdfRequestRetrieveOutputWdmdl を呼び出すことによって、受信した 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
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)

こちらもご覧ください

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