WdfIoTargetSendIoctlSynchronously 函式 (wdfiotarget.h)

發行項
02/27/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

呼叫端配置的 WDF_MEMORY_DESCRIPTOR 結構的指標，描述將寫入 I/O 目標的緩衝區。如需詳細資訊，請參閱接下來的＜備註＞一節。此參數是選擇性的，如果要求未傳送數據，則可為 NULL 。

[in, optional] OutputBuffer

呼叫端配置的 WDF_MEMORY_DESCRIPTOR 結構的指標，描述將從 I/O 目標接收數據的緩衝區。如需詳細資訊，請參閱接下來的＜備註＞一節。此參數是選擇性的，如果要求未收到數據，則可以是 NULL 。

[in, optional] RequestOptions

呼叫端配置的 WDF_REQUEST_SEND_OPTIONS 結構的指標，指定要求的選項。此指標是選擇性的，而且可以是 NULL。如需詳細資訊，請參閱接下來的＜備註＞一節。

[out, optional] BytesReturned

接收資訊的位置指標 (，例如另一個驅動程式呼叫 WdfRequestCompleteWithInformation 完成要求時所傳送的位元組數) 。此指標是選擇性的，而且可以是 NULL。

傳回值

如果作業成功， WdfIoTargetSendIoctlSynchronous 會在 裝置控制要求完成之後傳回，而傳回值為要求的完成狀態值。否則，這個方法可能會傳回下列其中一個值：

傳回碼	Description
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	Request 參數所代表的 I/O 要求封包 (IRP) 沒有足夠的IO_STACK_LOCATION結構，可讓驅動程序轉送要求。

這個方法也可能傳回其他 NTSTATUS值。

如果驅動程式提供無效的物件句柄，就會發生錯誤檢查。

備註

使用 WdfIoTargetSendIoctlSynchronously 方法同步傳送裝置控制要求。若要以異步方式傳送裝置控制要求，請使用 WdfIoTargetFormatRequestForIoctl 方法，後面接著 WdfRequestSend 方法。

如需裝置控制要求的詳細資訊，請參閱使用 I/O 控制程式碼。

除非驅動程式在 RequestOptions 參數的WDF_REQUEST_SEND_OPTIONS結構中提供逾時值，否則 WdfIoTargetSendIoctlSynchronously 方法不會傳回，除非偵測到錯誤。

您可以轉送驅動程式在 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 來建立一或多個要求物件，您可以呼叫 WdfRequestReuse 來重複使用這些要求物件。這項技術可讓您的驅動程式 EvtDriverDeviceAdd 回呼函式預先配置裝置的要求物件。此外，另一個驅動程式線程可以視需要呼叫 WdfRequestCancelSentRequest 來取消要求。
不論驅動程式提供非 NULL 或NULL 要求參數，驅動程式都可以指定非 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);
```
  或者，如果您想要驅動程式將該緩衝區的內容傳遞至 I/O 目標，驅動程式也可以呼叫 WdfRequestRetrieveOutputMemory 來取得架構記憶體物件的句柄，此物件代表接收的 I/O 要求的緩衝區。在 WdfIoTargetSendIoctlSynchronously 傳送至 I/O 目標的新要求已刪除、重複使用或重新格式化之前，驅動程式不得完成收到的 I/O 要求。 (WdfIoTargetSendIoctlSynchronous 遞 增記憶體對象的參考計數。刪除、重複使用或重新格式化要求物件會遞減記憶體對象的參考計數。)
- 提供 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
                                           );

規格需求

需求	值
目標平台	Universal
最低 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 () 、 WriteReqs (kmdf)