WdfUsbTargetDeviceSendControlTransferSynchronously 函式 (wdfusb.h)

發行項
02/27/2024

[適用於 KMDF 和 UMDF]

WdfUsbTargetDeviceSendControlTransferSynchronously 方法會建置 USB 控件傳輸要求，並將它同步傳送至 I/O 目標。

語法

NTSTATUS WdfUsbTargetDeviceSendControlTransferSynchronously(
  [in]            WDFUSBDEVICE                  UsbDevice,
  [in, optional]  WDFREQUEST                    Request,
  [in, optional]  PWDF_REQUEST_SEND_OPTIONS     RequestOptions,
  [in]            PWDF_USB_CONTROL_SETUP_PACKET SetupPacket,
  [in, optional]  PWDF_MEMORY_DESCRIPTOR        MemoryDescriptor,
  [out, optional] PULONG                        BytesTransferred
);

參數

[in] UsbDevice

從先前呼叫 WdfUsbTargetDeviceCreateWithParameters 取得的 USB 裝置物件的句柄。

[in, optional] Request

架構要求物件的句柄。此參數是選擇性的，可以是 NULL。如需詳細資訊，請參閱接下來的＜備註＞一節。

[in, optional] RequestOptions

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

[in] SetupPacket

描述控制項傳輸之呼叫端配置之WDF_USB_CONTROL_SETUP_PACKET 結構的指標。

[in, optional] MemoryDescriptor

呼叫端配置的 WDF_MEMORY_DESCRIPTOR 結構的指標，根據裝置特定的命令，描述輸入或輸出緩衝區。此指標是選擇性的，可以是 NULL。如需詳細資訊，請參閱接下來的＜備註＞一節。

[out, optional] BytesTransferred

接收所傳送位元組數目的位置指標。此參數是選擇性的，可以是 NULL。

傳回值

WdfUsbTargetDeviceSendControlTransferSynchronously 會在作業成功時傳回 I/O 目標的完成狀態值。否則，此方法可以傳回下列其中一個值：

傳回碼	Description
STATUS_INVALID_PARAMETER	偵測到無效的參數。
STATUS_INSUFFICIENT_RESOURCES	記憶體不足。
STATUS_INVALID_DEVICE_REQUEST	指定了無效的記憶體描述元，或指定的 I/O 要求已排入 I/O 目標佇列。
STATUS_IO_TIMEOUT	驅動程式提供了逾時值，而且要求未在分配的時間內完成。

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

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

備註

使用 WdfUsbTargetDeviceSendControlTransferSynchronously 方法來同步傳送 USB 控件傳輸要求。若要以異步方式傳送這類要求，請使用 WdfUsbTargetDeviceFormatRequestForControlTransfer，後面接著 WdfRequestSend。

除非驅動程式在要求完成之前，WdfUsbTargetDeviceSendControlTransferSynchronously 方法不會傳回，除非驅動程式在 RequestOptions 參數指向的 WDF_REQUEST_SEND_OPTIONS 結構中提供逾時值，或除非偵測到錯誤。

您可以轉送驅動程式在 I/O 佇列中收到的 I/O 要求，也可以建立並傳送新的要求。不論是哪一種情況，架構都需要要求物件，而且視控件傳輸的類型而定，可能是某些緩衝區空間。

若要轉送驅動程式在 I/O 佇列中收到的 I/O 要求：

指定 Request 參數的 接收要求句柄。
針對 MemoryDescriptor 參數，使用收到的要求輸入或輸出緩衝區。
驅動程式可以呼叫 WdfRequestRetrieveInputMemory 或 WdfRequestRetrieveOutputMemory，以取得代表要求的輸入或輸出緩衝區的架構記憶體物件的句柄，然後將該句柄放在驅動程式為 MemoryDescriptor 參數提供的WDF_MEMORY_DESCRIPTOR結構中。

若要建立並傳送新的要求：

在 Request 參數中提供 NULL 要求句柄，或建立新的要求物件，並提供其句柄：
- 如果您提供 NULL 要求句柄，架構會使用內部要求物件。這項技術很容易使用，但驅動程式無法取消要求。
- 如果您呼叫 WdfRequestCreate 來建立一或多個要求物件，您可以呼叫 WdfRequestReuse 來重複使用這些要求物件。這項技術可讓驅動程式的 EvtDriverDeviceAdd 回呼函式預先配置裝置的要求物件。此外，另一個驅動程式線程可以視需要呼叫 WdfRequestCancelSentRequest 來取消要求。
不論驅動程式是否提供非 NULL 或NULL要求參數，您的驅動程式都可以指定非 NULLRequestOptions 參數。例如，您可以使用 RequestOptions 參數來指定逾時值。
為 WdfUsbTargetDeviceSendControlTransferSynchronously 方法的 MemoryDescriptor 參數提供緩衝區空間。
您的驅動程式可以將此緩衝區空間指定為本機配置的緩衝區、WDFMEMORY 句柄或 MDL。您可以使用哪一種方法最方便。

如有必要，架構會將緩衝區描述轉換成 I/O 目標方法的正確緩衝區描述，以存取數據緩衝區。

下列技術可供使用：
- 提供本機緩衝區
  由於 WdfUsbTargetDeviceSendControlTransferSynchronously 會 同步處理 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 要求的緩衝區。在 WdfUsbTargetDeviceSendControlTransferSynchronously 傳送 至 I/O 目標已刪除、重複使用或重新格式化的新要求之前，驅動程式不得完成收到的 I/O 要求。 (WdfUsbTargetDeviceSendControlTransferSynchronous 遞 增記憶體對象的參考計數。刪除、重複使用或重新格式化要求物件會遞減記憶體對象的參考計數。)
- 提供 MDL
  驅動程式可以藉由呼叫 WdfRequestRetrieveInputWdmMdl 或 WdfRequestRetrieveOutputWdmMdl 來取得與接收 I/O 要求相關聯的 MDL。

架構會在其內部 URB 中設定USBD_SHORT_TRANSFER_OK旗標。設定此旗標可讓數據傳輸的最後一個封包小於封包大小上限。

如需 I/O 要求完成之後取得狀態資訊的相關信息，請參閱取得完成資訊。

如需 WdfUsbTargetDeviceSendControlTransferSynchronously 方法和 USB I/O 目標的詳細資訊，請參閱 USB I/O 目標。

範例

下列程式代碼範例會初始化 WDF_USB_CONTROL_SETUP_PACKET 結構，然後呼叫 WdfUsbTargetDeviceSendControlTransferSynchronously 來傳送廠商特定的控件傳輸。

WDF_USB_CONTROL_SETUP_PACKET  controlSetupPacket;

WDF_USB_CONTROL_SETUP_PACKET_INIT_VENDOR(
                                         &controlSetupPacket,
                                         BmRequestHostToDevice,
                                         BmRequestToDevice,
                                         USBFX2LK_REENUMERATE,
                                         0,
                                         0
                                         );

status = WdfUsbTargetDeviceSendControlTransferSynchronously(
                                         UsbDevice,
                                         WDF_NO_HANDLE,
                                         NULL,
                                         &controlSetupPacket,
                                         NULL,
                                         NULL
                                         );
return status;

規格需求

需求	值
目標平台	Universal
最小 KMDF 版本	1.0
最低UMDF版本	2.0
標頭	wdfusb.h (包含 Wdfusb.h)
程式庫	Wdf01000.sys (KMDF) ;WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
DDI 合規性規則	DriverCreate (kmdf) 、 KmdfIrql (kmdf) 、 KmdfIrql2 (kmdf) 、 KmdfIrqlExplicit (kmdf) 、 RequestForUrbXrb (kmdf) 、 SyncReqSend (kmdf) 、 UsbKmdfIrql (kmdf) 、 UsbKmdfIrql2 (kmdf) 、UsbKmdfIrqlExplicit (kmdf)