WdfIoTargetSendInternalIoctlOthersSynchronously 関数 (wdfiotarget.h)
[KMDF にのみ適用]
WdfIoTargetSendInternalIoctlOthersSynchronously メソッドは、標準以外の内部デバイス制御要求をビルドし、I/O ターゲットに同期的に送信します。
構文
NTSTATUS WdfIoTargetSendInternalIoctlOthersSynchronously(
[in] WDFIOTARGET IoTarget,
[in, optional] WDFREQUEST Request,
[in] ULONG IoctlCode,
[in, optional] PWDF_MEMORY_DESCRIPTOR OtherArg1,
[in, optional] PWDF_MEMORY_DESCRIPTOR OtherArg2,
[in, optional] PWDF_MEMORY_DESCRIPTOR OtherArg4,
[in, optional] PWDF_REQUEST_SEND_OPTIONS RequestOptions,
[out, optional] PULONG_PTR BytesReturned
);
パラメーター
[in] IoTarget
[in, optional] Request
フレームワーク要求オブジェクトへのハンドル。 このパラメーターは省略可能であり、NULL
[in] IoctlCode
I/O ターゲットがサポートする I/O 制御コード (IOCTL)。
[in, optional] OtherArg1
コンテキスト情報を含むメモリ バッファーを記述する WDF_MEMORY_DESCRIPTOR 構造体へのポインター。 このパラメーターは省略可能であり、NULL
[in, optional] OtherArg2
コンテキスト情報を含むメモリ バッファーを記述するWDF_MEMORY_DESCRIPTOR構造体へのポインター。 このパラメーターは省略可能であり、NULL
[in, optional] OtherArg4
コンテキスト情報を含むメモリ バッファーを記述するWDF_MEMORY_DESCRIPTOR構造体へのポインター。 このパラメーターは省略可能であり、NULL
[in, optional] RequestOptions
要求のオプションを指定する呼び出し元によって割り当てられた WDF_REQUEST_SEND_OPTIONS 構造体へのポインター。 このポインターは省略可能であり、NULL
[out, optional] BytesReturned
WdfRequestCompleteWithInformationを呼び
戻り値
操作が成功した場合、WdfIoTargetSendInternalIoctlOthersSynchronously は、内部デバイス制御要求が完了した後に戻り、戻り値は要求の完了状態値になります。 それ以外の場合、このメソッドは次のいずれかの値を返す可能性があります。
リターン コード | 形容 |
---|---|
|
無効なパラメーターが検出されました。 |
|
RequestOptions パラメーターが指す WDF_REQUEST_SEND_OPTIONS 構造体のサイズが正しくありません。 |
|
要求は既に I/O ターゲットにキューに入れられました。 |
|
フレームワークは、システム リソース (通常はメモリ) を割り当てませんでした。 |
|
ドライバーがタイムアウト値を指定し、割り当てられた時間内に要求が完了しませんでした。 |
|
要求 パラメーターが表す I/O 要求パケット (IRP) は、ドライバーが要求を転送するのに十分な IO_STACK_LOCATION 構造体を提供しません。 |
このメソッドは、他の
ドライバーが無効なオブジェクト ハンドルを提供すると、バグ チェックが発生します。
備考
非標準の内部デバイス制御要求では、IOCTL コードを使用して実行する操作を識別しますが、要求では、他の内部デバイス制御要求で使用される標準の入力バッファーと出力バッファーは使用されません。 一連の対話ドライバーを作成する場合は、この一連のドライバーが要求の引数を使用する方法を定義できます。
フレームワークは、これらのパラメーター をドライバーの IO_STACK_LOCATION 構造体の Argument1、Argument2、および Argument4 メンバーに関連付けるので、OtherArg3 呼び出されるパラメーターはありません。 その共用体の Argument3 メンバーは、IoctlCode パラメーターから値を受け取るので、他のドライバー指定値では使用できません。
WdfIoTargetSendInternalIoctlOthersSynchronously メソッドを使用して、標準以外の内部デバイス制御要求を同期的に送信します。 内部デバイス制御要求を非同期的に送信するには、
内部デバイス制御要求の詳細については、「I/O 制御コードを使用する」を参照してください。
WdfIoTargetSendInternalIoctlOthersSynchronously メソッドは、RequestOptions パラメーターの WDF_REQUEST_SEND_OPTIONS 構造体にタイムアウト値を指定しない限り、またはエラーが検出されない限り、要求が完了するまで戻りません。
ドライバーが I/O キューで受信した標準以外の内部デバイス制御要求を転送することも、新しい要求を作成して送信することもできます。 どちらの場合も、フレームワークには要求オブジェクトと場合によってはコンテキスト領域が必要です。
ドライバーが I/O キューで受信した標準以外の内部デバイス制御要求を転送するには:
- WdfIoTargetSendInternalIoctlOthersSynchronously メソッドの Request パラメーターに対して、受信した要求のハンドルを指定します。
-
WdfIoTargetSendInternalIoctlOthersSynchronously 、OtherArg1 OtherArg2 、および OtherArg4 パラメーターをするために、受信した要求のコンテキスト情報を使用します。 これらのパラメーター値を取得するには、ドライバー WdfRequestGetParameters を呼び出し、返される WDF_REQUEST_PARAMETERS 構造体の DeviceIoControl メンバーを使用する必要があります。
ドライバーは、多くの場合、受信した I/O 要求を、I/O ターゲットに送信する小さな要求に分割するため、ドライバーは新しい要求を作成する可能性があります。
新しい I/O 要求を作成するには:
-
WdfIoTargetSendInternalIoctlOthersSynchronously Request パラメーターに対して、NULL 要求ハンドルを指定するか、新しい要求オブジェクトを作成してそのハンドルを指定します。
- NULL 要求ハンドルを指定すると、フレームワークは内部要求オブジェクトを使用します。 この手法は簡単に使用できますが、ドライバーは要求をキャンセルできません。
WdfRequestCreate を呼び出して 1 つ以上の要求オブジェクトを作成する場合は、WdfRequestReuse呼び出すことによって、これらの要求オブジェクトを再利用できます。 この手法を使用すると、ドライバーの EvtDriverDeviceAdd コールバック関数を使用して、デバイスの要求オブジェクトを事前に割り当てることができます。 さらに、別のドライバー スレッドは、WdfRequestCancelSentRequest を呼び出して、必要に応じて要求を取り消すことができます。
ドライバーは、以外の NULL または NULLRequest パラメーターを提供するかどうかに関係なく、NULLRequestOptions パラメーターを指定できます。 たとえば、RequestOptions パラメーターを使用してタイムアウト値を指定できます。
-
要求に必要な場合は、WdfIoTargetSendInternalIoctlOthersSynchronously OtherArg1、OtherArg2、および OtherArg4 パラメーターを するコンテキスト領域を指定します。
ドライバーは、ローカルに割り当てられたバッファーとして、WDFMEMORY ハンドルとして、またはメモリ記述子リスト (MDL) として、このコンテキスト領域を指定できます。 最も便利な方法を使用できます。
バッファー領域を指定する次の手法を使用できます。
-
ローカル バッファーを指定します。
WdfIoTargetSendInternalIoctlOthersSynchronously は 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);
-
MDL を指定します。
ドライバーは、WdfRequestRetrieveInputWdmMdl
を呼び出し、WdfRequestRetrieveOutputWdmMdlを することで、受信した I/O 要求に関連付けられている MDL を取得できます。
-
ローカル バッファーを指定します。
WdfIoTargetSendInternalIoctlOthersSynchronously
I/O ターゲットの詳細については、「I/O ターゲットの使用」を参照してください。
例
次のコード例では、IEEE 1394 IRB 構造体を初期化し、構造体のアドレスを使用して WDF_MEMORY_DESCRIPTOR 構造体を初期化した後、WdfIoTargetSendInternalIoctlOthersSynchronouslyを呼び出します。
WDF_MEMORY_DESCRIPTOR descriptor;
IRB Irb;
Irb.FunctionNumber = REQUEST_ALLOCATE_ADDRESS_RANGE;
Irb.Flags = 0;
Irb.u.AllocateAddressRange.Mdl = pAsyncAddressData->pMdl;
Irb.u.AllocateAddressRange.fulFlags = fulFlags;
Irb.u.AllocateAddressRange.nLength = nLength;
Irb.u.AllocateAddressRange.MaxSegmentSize = MaxSegmentSize;
Irb.u.AllocateAddressRange.fulAccessType = fulAccessType;
Irb.u.AllocateAddressRange.fulNotificationOptions = fulNotificationOptions;
Irb.u.AllocateAddressRange.Callback = NULL;
Irb.u.AllocateAddressRange.Context = NULL;
Irb.u.AllocateAddressRange.Required1394Offset = *Required1394Offset;
Irb.u.AllocateAddressRange.FifoSListHead = NULL;
Irb.u.AllocateAddressRange.FifoSpinLock = NULL;
Irb.u.AllocateAddressRange.AddressesReturned = 0;
Irb.u.AllocateAddressRange.p1394AddressRange = pAsyncAddressData->AddressRange;
Irb.u.AllocateAddressRange.DeviceExtension = deviceExtension;
WDF_MEMORY_DESCRIPTOR_INIT_BUFFER(
&descriptor,
&Irb,
sizeof (IRB)
);
ntStatus = WdfIoTargetSendInternalIoctlOthersSynchronously(
IoTarget,
NULL,
IOCTL_1394_CLASS,
&descriptor,
NULL,
NULL,
NULL,
NULL
);
必要条件
要件 | 価値 |
---|---|
ターゲット プラットフォーム の |
万国 |
最小 KMDF バージョン | 1.0 |
ヘッダー | wdfiotarget.h (Wdf.h を含む) |
ライブラリ | Wdf01000.sys (フレームワーク ライブラリのバージョン管理を参照)。 |
IRQL | PASSIVE_LEVEL |
DDI コンプライアンス規則 を |
関連項目
EvtDriverDeviceAdd の
WDF_MEMORY_DESCRIPTOR_INIT_BUFFER
WdfDeviceGetIoTarget の
WdfIoTargetCreate の
WdfIoTargetFormatRequestForInternalIoctlOthers
WdfMemoryCreatePreallocated の
WdfRequestCompleteWithInformation の