WdfUsbTargetPipeReadSynchronously 函式 （wdfusb.h）

[適用於 KMDF 和 UMDF]

WdfUsbTargetPipeReadSynchronously 方法會建置讀取要求，並將它同步傳送至指定的 USB 輸入管道。

語法

NTSTATUS WdfUsbTargetPipeReadSynchronously(
  [in]            WDFUSBPIPE                Pipe,
  [in, optional]  WDFREQUEST                Request,
  [in, optional]  PWDF_REQUEST_SEND_OPTIONS RequestOptions,
  [in, optional]  PWDF_MEMORY_DESCRIPTOR    MemoryDescriptor,
  [out, optional] PULONG                    BytesRead
);

參數

[in] Pipe

呼叫 WdfUsbInterfaceGetConfiguredPipe 取得之架構管道物件的句柄。

[in, optional] Request

架構要求物件的句柄。 這個參數是選擇性的，而且可以 NULL。 如需詳細資訊，請參閱下列一節。

[in, optional] RequestOptions

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

[in, optional] MemoryDescriptor

呼叫端配置的 WDF_MEMORY_DESCRIPTOR 結構的指標，描述將從裝置接收數據的緩衝區。 除非驅動程式已呼叫 WdfUsbTargetPipeSetNoMaximumPacketSizeCheck，否則緩衝區大小必須是管道最大封包大小的倍數。 如需此緩衝區的詳細資訊，請參閱下列一節。

[out, optional] BytesRead

如果作業成功，則為接收讀取位元組數目之位置的指標。 這個參數是選擇性的，而且可以 NULL。

傳回值

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

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

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

言論

使用 WdfUsbTargetPipeReadSynchronously 方法來同步傳送讀取要求。 若要以異步方式傳送讀取要求，請使用 WdfUsbTargetPipeFormatRequestForRead，後面接著 WdfRequestSend。

Pipe 參數指定的管道必須是輸入管道，而管道的 類型 必須 WdfUsbPipeTypeBulk 或 WdfUsbPipeTypeInterrupt。

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

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

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

1. 為 要求 參數指定收到的要求句柄。
2. 針對 WdfUsbTargetPipeReadSynchronously 方法的 MemoryDescriptor 參數，使用收到的要求輸出緩衝區。

   驅動程式必須呼叫 WdfRequestRetrieveOutputMemory，以取得表示要求輸出緩衝區的架構記憶體物件的句柄，然後將該句柄放在 MemoryDescriptor 指向的 WDF_MEMORY_DESCRIPTOR 結構中。

驅動程式通常會將收到的 I/O 要求分成較小的要求，這些要求會傳送至 I/O 目標，因此您的驅動程式可能會建立新的要求。

若要建立新的 I/O 要求：

1. 在 WdfUsbTargetPipeReadSynchronously 方法的 Request 參数中，提供 NULL 要求句柄，或建立新的要求物件並提供句柄：
   • 如果您提供 NULL 要求句柄，架構會使用內部要求物件。 這項技術很容易使用，但驅動程式無法取消要求。
   • 如果您呼叫 WdfRequestCreate 來建立一或多個要求物件，您可以呼叫 WdfRequestReuse來重複使用這些要求物件。 這項技術可讓您的驅動程式 EvtDriverDeviceAdd 回呼函式預先配置裝置的要求物件。 此外，另一個驅動程式線程可以視需要呼叫 WdfRequestCancelSentRequest 來取消要求。

   您的驅動程式可以指定非NULLRequestOptions 參數、驅動程式提供非NULL 或 NULLRequest 參數。 例如，您可以使用 RequestOptions 參數來指定逾時值。

2. 為 WdfUsbTargetPipeReadSynchronously 方法的 MemoryDescriptor 參數提供緩衝區空間。

   您的驅動程式可以將此緩衝區空間指定為本機配置的緩衝區、WDFMEMORY 句柄或 MDL。 您可以使用哪一種方法最方便。

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

   下列技術可供使用：

   • 提供本機緩衝區

     因為 WdfUsbTargetPipeReadSynchronously 同步處理 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 要求的輸出緩衝區。 除非 WdfUsbTargetPipeReadSynchronously 傳送至 I/O 目標的新要求已刪除、重複使用或重新格式化，否則驅動程式必須完成收到的 I/O 要求。 （WdfUsbTargetPipeReadSynchronously 遞增記憶體對象的參考計數。刪除、重複使用或重新格式化要求物件會遞減記憶體對象的參考計數。

   • 提供 MDL

     驅動程式可以呼叫 WdfRequestRetrieveOutputWdmMdl，以取得與接收的 I/O 要求相關聯的 MDL。

如果驅動程式已設定管道的 連續讀取器，則驅動程式無法呼叫 WdfUsbTargetPipeReadSynchronously。

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

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

例子

下列程式代碼範例會建立架構記憶體物件、初始化 WDF_MEMORY_DESCRIPTOR 結構，並將 結構傳遞至 WdfUsbTargetPipeReadSynchronously。 此範例會針對要求物件句柄指定 NULL，因此架構會為 I/O 目標建立新的要求物件。

WDFMEMORY  wdfMemory;
WDF_MEMORY_DESCRIPTOR  readBufDesc;
ULONG  BytesRead;

status = WdfMemoryCreate(
                         WDF_NO_OBJECT_ATTRIBUTES,
                         NonPagedPool,
                         0,
                         readSize,
                         &wdfMemory,
                         NULL
                         );
if (!NT_SUCCESS(status)){
    return ;
}

buffer = WdfMemoryGetBuffer(
                            wdfMemory,
                            NULL
                            );

WDF_MEMORY_DESCRIPTOR_INIT_BUFFER(
                                  &readBufDesc,
                                  buffer,
                                  readSize
                                  );

status = WdfUsbTargetPipeReadSynchronously(
                                           Pipe,
                                           NULL,
                                           NULL,
                                           &readBufDesc,
                                           &BytesRead
                                           );

要求

另請參閱

WDF_MEMORY_DESCRIPTOR_INIT_BUFFER

WdfMemoryCreate

WdfUsbTargetPipeGetInformation