共用方式為


WdfIoTargetSendReadSynchronously 函式 (wdfiotarget.h)

[適用於 KMDF 和 UMDF]

WdfIoTargetSendReadSynchronously 方法會建置讀取要求,並將它同步傳送至 I/O 目標。

語法

NTSTATUS WdfIoTargetSendReadSynchronously(
  [in]            WDFIOTARGET               IoTarget,
  [in, optional]  WDFREQUEST                Request,
  [in, optional]  PWDF_MEMORY_DESCRIPTOR    OutputBuffer,
  [in, optional]  PLONGLONG                 DeviceOffset,
  [in, optional]  PWDF_REQUEST_SEND_OPTIONS RequestOptions,
  [out, optional] PULONG_PTR                BytesRead
);

參數

[in] IoTarget

從先前呼叫 WdfDeviceGetIoTarget WdfIoTargetCreate 或從特殊 I/O 目標提供的方法取得的本機或遠端 I/O 目標物件的句柄。

[in, optional] Request

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

[in, optional] OutputBuffer

呼叫端配置的 WDF_MEMORY_DESCRIPTOR 結構的指標,描述將從裝置接收數據的緩衝區。這個參數是選擇性的,而且可以 NULL。 如需此參數的詳細資訊,請參閱下列一節。

[in, optional] DeviceOffset

指定傳輸起始位移之位置的指標。 I/O 目標 (也就是下一個較低的驅動程式) 會定義如何使用此值。 例如,磁碟驅動程式堆疊中的驅動程式可能會指定磁碟開頭的位移。 I/O 目標會在要求 WDF_REQUEST_PARAMETERS 結構 成員的 Parameters.Read.DeviceOffset 中取得這項資訊。 這個指標是選擇性的。 大部分的驅動程式都會將此指標設定為 NULL

[in, optional] RequestOptions

呼叫端配置的 WDF_REQUEST_SEND_OPTIONS 結構的指標,指定讀取要求的選項。 此指標是選擇性的,而且可以 NULL

[out, optional] BytesRead

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

傳回值

如果作業成功,WdfIoTargetSendReadSynchronously I/O 要求完成之後傳回,而傳回值則是要求的完成狀態值。 否則,此方法可能會傳回下列其中一個值:

傳回碼 描述
STATUS_INVALID_PARAMETER
偵測到無效的參數。
STATUS_INFO_LENGTH_MISMATCH
RequestOptions 參數所指向WDF_REQUEST_SEND_OPTIONS結構的大小不正確。
STATUS_INVALID_DEVICE_REQUEST
I/O 要求已排入 I/O 目標佇列。
STATUS_INSUFFICIENT_RESOURCES
架構無法配置系統資源(通常是記憶體)。
STATUS_IO_TIMEOUT
驅動程式提供逾時值,且要求未在分配的時間內完成。
STATUS_REQUEST_NOT_ACCEPTED
Request 參數所代表的 I/O 要求封包(IRP),無法提供足夠的 IO_STACK_LOCATION 結構,讓驅動程式轉送要求。
 

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

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

言論

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

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

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

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

  1. 要求 參數指定收到的要求句柄。
  2. 針對 WdfIoTargetSendReadSynchronously 方法的 outputBuffer 參數,使用收到的要求輸出緩衝區。

    驅動程式必須呼叫 WdfRequestRetrieveOutputMemory,以取得表示要求輸出緩衝區之架構記憶體物件的句柄。 然後,驅動程式必須將該句柄放在驅動程式提供給 OutputBuffer 參數的 WDF_MEMORY_DESCRIPTOR 結構中。

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

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

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

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

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

  2. WdfIoTargetSendReadSynchronously 方法的 outputBuffer 參數提供緩衝區空間。

    您的驅動程式可以將此緩衝區空間指定為本機配置的緩衝區、作為WDFMEMORY句柄,或指定為記憶體描述元清單 (MDL)。 您可以使用哪一種方法最方便。

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

    下列指定緩衝區空間的技術可供使用:

    • 提供本機緩衝區。

      因為 WdfIoTargetSendReadSynchronously 同步處理 I/O 要求,因此驅動程式可以建立呼叫例程本機的要求緩衝區,如下列程式代碼範例所示。

      WDF_MEMORY_DESCRIPTOR  MemoryDescriptor;
      MY_BUFFER_TYPE  MyBuffer;
      WDF_MEMORY_DESCRIPTOR_INIT_BUFFER(&MemoryDescriptor,
                                        (PVOID) &MyBuffer,
                                        sizeof(MyBuffer));
      
    • 提供WDFMEMORY句柄。

      呼叫 WdfMemoryCreateWdfMemoryCreatePreallocated,以取得架構管理的記憶體句柄,如下列程式代碼範例所示。

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

    • 提供 MDL。

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

某些 I/O 目標接受具有零長度緩衝區的讀取要求。 針對這類 I/O 目標,您的驅動程式可以為 OutputBuffer 參數指定 NULL

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

如需 WdfIoTargetSendReadSynchronously的詳細資訊,請參閱 將 I/O 要求傳送至一般 I/O 目標

如需 I/O 目標的詳細資訊,請參閱使用 I/O 目標

例子

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

WDF_MEMORY_DESCRIPTOR  MemoryDescriptor;
WDFMEMORY  MemoryHandle = NULL;
ULONG_PTR  bytesRead = NULL;

status = WdfMemoryCreate(
                         NULL,
                         NonPagedPool,
                         POOL_TAG,
                         MY_BUFFER_SIZE,
                         &MemoryHandle,
                         NULL
                         );
WDF_MEMORY_DESCRIPTOR_INIT_HANDLE(
                                  &MemoryDescriptor,
                                  MemoryHandle,
                                  NULL
                                  );
status = WdfIoTargetSendReadSynchronously(
                                          ioTarget,
                                          NULL,
                                          &MemoryDescriptor,
                                          NULL,
                                          NULL,
                                          &bytesRead
                                          );
 

要求

要求 價值
目標平臺 普遍
最低 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)IoctlReqs(kmdf)KmdfIrql(kmdf)KmdfIrql2(kmdf),KmdfIrqlExplicit(kmdf),RequestCompleted(kmdf)RequestCompletedLocal(kmdf)SyncReqSend(kmdf)WriteReqs(kmdf)

另請參閱

EvtDriverDeviceAdd

WDF_MEMORY_DESCRIPTOR

WDF_MEMORY_DESCRIPTOR_INIT_HANDLE

WDF_REQUEST_PARAMETERS

WDF_REQUEST_SEND_OPTIONS

WdfDeviceGetIoTarget

WdfIoTargetCreate

WdfIoTargetFormatRequestForRead

WdfIoTargetSendWriteSynchronously

WdfMemoryCreate

WdfMemoryCreatePreallocated

WdfRequestCancelSentRequest

WdfRequestCreate

WdfRequestRetrieveOutputMemory

WdfRequestRetrieveOutputWdmMdl

WdfRequestReuse

WdfRequestSend