NDIS_PD_POST_AND_DRAIN_BUFFER_LIST回呼函式 (ndis.h)

PacketDirect (PD) 平臺會呼叫支援 PD 的迷你埠驅動程式 PDPostAndDrainBufferList 函式，將 PD_BUFFER 結構張貼至 PD 傳輸/接收佇列，並清空任何先前張貼 PD_BUFFER 結構已完成。

注意 您必須使用 NDIS_PD_POST_AND_DRAIN_BUFFER_LIST 類型來宣告函式。 如需詳細資訊，請參閱下列範例一節。

 

語法

NDIS_PD_POST_AND_DRAIN_BUFFER_LIST NdisPdPostAndDrainBufferList;

VOID() NdisPdPostAndDrainBufferList(
  [in, out] NDIS_PD_QUEUE *Queue,
  [in, out] PD_BUFFER **PostBufferListHead,
  [in, out] PD_BUFFER ***DrainBufferListTail,
  [in]      ULONG MaxDrainCount
)
{...}

參數

[in, out] Queue

傳送或接收佇列的指標，該佇列將接收張貼的緩衝區，並已移除已完成的緩衝區。

[in, out] PostBufferListHead

文章清單的標頭。 提供者會移除此清單中的緩衝區，並將其新增至 佇列。

[in, out] DrainBufferListTail

清空清單的結尾。 提供者會從 佇列 中移除任何已完成的緩衝區，並將其新增至此清單。

[in] MaxDrainCount

要清空的 PD_BUFFER 結構數量上限。 提供者必須確定不超過此數量。 構成單一 L2 封包計數的部分 PD_BUFFER 結構集為 1。

傳回值

這個回呼函式不會傳回值。

備註

提供者會從 PostBufferList 中移除緩衝區，並將其放在佇列中，從清單中的前端緩衝區開始，並前進到下一個緩衝區，直到 PostBufferList 是空的，或是佇列已滿 (或接近完整) 為止。 進階至 PostListHead 的提供者，並將新的清單標頭傳回給呼叫端。 提供者也會從佇列中移除任何已完成的緩衝區，並將其插入 DrainBufferList 的結尾，並將新的 DrainBufferList 結尾傳回給用戶端。

注意 提供者應該清空最多緩衝區，以便開啟要張貼緩衝區的空間。 PostBufferList 和 DrainBufferList 保證會脫離緩衝區清單， (客戶端永遠不會提供緩衝區清單的前端做為 PostBufferListHead，而該列表的結尾與 DrainBufferListTail) 相同。

 

用戶端也可以將空的後置緩衝區清單傳遞至只清空完成的緩衝區，而不張貼任何新的緩衝區。 用戶端也可以將 MaxDrainCount 設定為0，只張貼新的緩衝區，而不需要清空任何已完成的緩衝區。 在罕見的情況下，用戶端可能會使用空的post緩衝區清單和 MaxDrainCount叫用呼叫至0。 提供者不得假設否則，並正確處理這類呼叫，例如無作業。

例子

若要定義 PDPostAndDrainBufferList 函式，您必須先提供函式宣告來識別您要定義的函式類型。 Windows 提供一組驅動程式的函式類型。 使用函式類型宣告函式有助於 驅動程式的程式代碼分析、 靜態驅動程式驗證程式 (SDV) ，以及其他驗證工具尋找錯誤，而且是撰寫 Windows 作業系統驅動程式的需求。

例如，若要定義名為 「MyPDPostAndDrainBufferList」 的 PDPostAndDrainBufferList 函式，請使用 NDIS_PD_POST_AND_DRAIN_BUFFER_LIST 類型，如下列程式代碼範例所示：

NDIS_PD_POST_AND_DRAIN_BUFFER_LIST MyPDPostAndDrainBufferList;

然後，實作您的函式，如下所示：

_Use_decl_annotations_
VOID
 MyPDPostAndDrainBufferList(
    NDIS_PD_QUEUE*  Queue,
    PD_BUFFER**  PostBufferListHead,
    PD_BUFFER*** DrainBufferListTail,
    ULONG  MaxDrainCount
    )
  {...}

NDIS_PD_POST_AND_DRAIN_BUFFER_LIST函式類型定義於 Ntddndis.h 頭檔中。 若要在執行程式代碼分析工具時更精確地識別錯誤，請務必將 Use_decl_annotations 批註新增至函式定義。 Use_decl_annotations註釋可確保使用頭檔中套用至NDIS_PD_POST_AND_DRAIN_BUFFER_LIST函式類型的註釋。 如需函數宣告需求的詳細資訊，請參閱 使用 NDIS 驅動程式的函式角色類型來宣告函式。

如需 Use_decl_annotations的詳細資訊，請參閱 標註函式行為。

以下是範例代碼段，說明此函式的指標間接取值。

PD_BUFFER* PostHead = NULL;
PD_BUFFER** PostTail = &PostHead;
PD_BUFFER* DrainHead = NULL;
PD_BUFFER** DrainTail = &DrainHead;

PD_BUFFER* bufX = <allocated PD_BUFFER>;

bufX->NextPDBuffer = NULL;
*PostTail = bufX;
PostTail = &bufX->NextPDBuffer;

// BEFORE:
//PostHead == bufX
//PostTail == &bufZ->NextPDBuffer
//DrainHead == NULL
//DrainTail == &DrainHead

NDIS_PD_POST_AND_DRAIN_BUFFER_LIST(
          Queue,
          &PostHead,
          &DrainTail,
          32);

// AFTER:
//PostHead == bufY
//PostTail == &bufZ->NextPDBuffer
//DrainHead == buf1
//DrainTail == &buf5->NextPDBuffer

規格需求

需求	值
最低支援的用戶端	Windows 10
最低支援的伺服器	Windows Server 2016
目標平台	Windows
標頭	ndis.h
IRQL	<= DISPATCH_LEVEL