WdfUsbTargetPipeWriteSynchronously 函式 (wdfusb.h)

  • 發行項

[適用於 KMDF 和 UMDF]

WdfUsbTargetPipeWriteSynchronously 方法會建置寫入要求，並以同步方式將它傳送至指定的 USB 輸出管道。

語法

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

參數

[in] Pipe

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

[in, optional] Request

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

[in, optional] RequestOptions

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

[in, optional] MemoryDescriptor

呼叫端配置的 WDF_MEMORY_DESCRIPTOR 結構的指標，描述將寫入裝置之數據的緩衝區。 如需此緩衝區的詳細資訊，請參閱下列一節。

[out, optional] BytesWritten

如果作業成功，則為接收寫入位元組數目的位置指標。 此參數是選擇性的，可以是 NULL。

傳回值

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

傳回碼 Description
STATUS_INFO_LENGTH_MISMATCH
 RequestOptions 參數指向的WDF_REQUEST_SEND_OPTIONS結構大小不正確。
STATUS_INVALID_PARAMETER
 偵測到無效的參數。
STATUS_INSUFFICIENT_RESOURCES
 記憶體不足。
STATUS_INVALID_DEVICE_REQUEST
 呼叫者的 IRQL 未PASSIVE_LEVEL、指定的記憶體描述元無效、管道的類型無效、傳輸方向無效，或指定的 I/O 要求已排入 I/O 目標佇列。
STATUS_IO_TIMEOUT
 驅動程式提供了逾時值，而且要求未在分配的時間內完成。
STATUS_REQUEST_NOT_ACCEPTED
 要求參數所代表的 I/O 要求封包 (IRP) 沒有足夠的IO_STACK_LOCATION結構，可讓驅動程式轉送要求。
 

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

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

備註

使用 WdfUsbTargetPipeWriteSynchronously 方法來同步傳送寫入要求。 若要以異步方式傳送寫入要求，請使用 WdfUsbTargetPipeFormatRequestForWrite，後面接著 WdfRequestSend。

指定的管道必須是輸出管道，管道的類型必須是 WdfUsbPipeTypeBulk 或 WdfUsbPipeTypeInterrupt。

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

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

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

  1. 指定 Request 參數的 接收要求句柄。
  2. 針對 MemoryDescriptor 參數使用收到的要求輸入緩衝區。

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

如需轉送 I/O 要求的詳細資訊，請參閱 轉送 I/O 要求。

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

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

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

    不論驅動程式是否提供非 NULL 或NULL要求參數，您的驅動程式都可以指定非 NULLRequestOptions 參數。 例如，您可以使用 RequestOptions 參數來指定逾時值。

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

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

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

    下列技術可供使用：

    • 提供本機緩衝區

      由於 WdfUsbTargetPipeWriteSynchronously 會同步處理 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 目標，則驅動程式可以呼叫 WdfRequestRetrieveInputMemory ，以取得架構記憶體物件的句柄，代表所接收 I/O 要求的輸入緩衝區。 在 WdfUsbTargetPipeWriteSynchronously 傳送 至 I/O 目標的新要求已刪除、重複使用或重新格式化之前，驅動程式不得完成收到的 I/O 要求。 (WdfUsbTargetPipeWriteSynchronous 遞 增記憶體對象的參考計數。刪除、重複使用或重新格式化要求物件會遞減記憶體對象的參考計數。)

    • 提供 MDL

      驅動程式可以藉由呼叫 WdfRequestRetrieveInputWdmMdl 來取得與已接收 I/O 要求相關聯的 MDL。

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

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

範例

下列程式代碼範例會建立記憶體物件、取得對象的緩衝區指標、填滿緩衝區，並使用緩衝區做為 WdfUsbTargetPipeWriteSynchronously 的輸入。

WDF_MEMORY_DESCRIPTOR  writeBufDesc;
WDFMEMORY  wdfMemory;
ULONG  writeSize, bytesWritten;
size_t  bufferSize;
NTSTATUS status;

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

writeBuffer = WdfMemoryGetBuffer(
                                 wdfMemory,
                                 &bufferSize
                                 );

FillMyBuffer(
             writeBuffer,
             writeSize
             );

WDF_MEMORY_DESCRIPTOR_INIT_BUFFER(
                                  &writeBufDesc,
                                  writeBuffer,
                                  writeSize
                                  );

status = WdfUsbTargetPipeWriteSynchronously(
                                            pipeHandle,
                                            NULL,
                                            NULL,
                                            &writeBufDesc,
                                            &bytesWritten
                                            );

規格需求

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

另請參閱

WDF_MEMORY_DESCRIPTOR_INIT_BUFFER

WdfMemoryCreate

WdfMemoryGetBuffer

WdfRequestCancelSentRequest

WdfUsbTargetPipeReadSynchronously