PROTOCOL_RECEIVE_NET_BUFFER_LISTS回呼函式 (ndis.h)

發行項
02/29/2024

ProtocolReceiveNetBufferLists 函式進程會接收基礎驅動程式的指示。

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

語法

PROTOCOL_RECEIVE_NET_BUFFER_LISTS ProtocolReceiveNetBufferLists;

void ProtocolReceiveNetBufferLists(
  [in] NDIS_HANDLE ProtocolBindingContext,
  [in] PNET_BUFFER_LIST NetBufferLists,
  [in] NDIS_PORT_NUMBER PortNumber,
  [in] ULONG NumberOfNetBufferLists,
  [in] ULONG ReceiveFlags
)
{...}

參數

[in] ProtocolBindingContext

通訊協定驅動程式配置來維護系結狀態資訊的內容區域句柄。此句柄在先前呼叫 NdisOpenAdapterEx 函式時傳遞至 NDIS。

[in] NetBufferLists

基礎驅動程式配置的 NET_BUFFER_LIST 結構連結清單。每個 NET_BUFFER_LIST 結構通常與一個 NET_BUFFER 結構相關聯。

[in] PortNumber

識別迷你埠配接器埠的埠號碼。迷你埠配接器的預設埠號碼為零。不使用迷你埠適配卡埠的通訊協定驅動程序應該忽略此參數。

[in] NumberOfNetBufferLists

NetBufferLists 之結構連結清單中的NET_BUFFER_LIST結構數目。

[in] ReceiveFlags

定義傳送作業屬性的旗標。旗標可以與 OR 作業結合。若要清除所有旗標，請將此成員設定為零。此函式支援下列旗標：

NDIS_RECEIVE_FLAGS_DISPATCH_LEVEL

指定目前的 IRQL DISPATCH_LEVEL。如需此旗標的詳細資訊，請參閱分派 IRQL 追蹤。

NDIS_RECEIVE_FLAGS_RESOURCES

指定 NDIS 會在呼叫 ProtocolReceiveNetBufferLists 之後，立即回收NET_BUFFER_LIST結構的擁有權，以及任何附加的NET_BUFFER結構。

NDIS_RECEIVE_FLAGS_SINGLE_ETHER_TYPE

指定 NetBufferLists 清單中的所有NET_BUFFER_LIST結構都具有相同的通訊協定類型， (EtherType) 。

NDIS_RECEIVE_FLAGS_SINGLE_VLAN

指定 NetBufferLists 清單中的所有NET_BUFFER_LIST結構都屬於相同的 VLAN。

NDIS_RECEIVE_FLAGS_PERFECT_FILTERED

指定 NetBufferList 清單中所有NET_BUFFER_LIST結構只包含符合指派給迷你埠配接器之封包篩選和多播清單的數據。

NDIS_RECEIVE_FLAGS_SINGLE_QUEUE

指定 NetBufferLists 清單中的所有NET_BUFFER_LIST結構都屬於相同的 VM 佇列。如果已在的 Flags 成員中設定NDIS_RECEIVE_QUEUE_PARAMETERS_PER_QUEUE_RECEIVE_INDICATION旗標，迷你埠驅動程式就必須針對佇列上所有接收指示設定此旗標配置該佇列時NDIS_RECEIVE_QUEUE_PARAMETERS結構。

NDIS_RECEIVE_FLAGS_SHARED_MEMORY_INFO_VALID

指定 NetBufferLists 清單中的所有NET_BUFFER_LIST結構都包含有效的共用記憶體資訊。當收到 NET_BUFFER_LIST上設定此旗標時，NDIS 會將共用記憶體資訊視為有效。未設定此旗標時，NDIS 和驅動程式會忽略共用記憶體資訊。例如，修改封包數據的中繼驅動程式可以使用這個旗標來判斷是否應該複製數據。迷你埠驅動程式可以使用旗標來判斷刪除佇列時，如何釋放與 VM 佇列相關聯的記憶體。

NDIS_RECEIVE_FLAGS_MORE_NBLS

保留的。

傳回值

無

備註

ProtocolReceiveNetBufferLists 是通訊協定驅動程式的必要函式。 NDIS 會在系結的迷你埠驅動程式呼叫之後呼叫 ProtocolReceiveNetBufferLists NdisMIndicateReceiveNetBufferLists 函式。 對 ProtocolReceiveNetBufferLists 的呼叫也可能因為回送而發生。

如果未設定 ReceiveFlags 參數中的NDIS_RECEIVE_FLAGS_RESOURCES旗標，通訊協定驅動程式會保留NET_BUFFER_LIST結構的擁有權，直到呼叫 NdisReturnNetBufferLists 函式。

如果 NDIS 設定 NDIS_RECEIVE_FLAGS_RESOURCES 旗標，通訊協定驅動程式就無法保留 NET_BUFFER_LIST 結構和相關聯的資源。 set NDIS_RECEIVE_FLAGS_RESOURCES 旗標表示基礎驅動程式在接收資源上執行不足。在此情況下， ProtocolReceiveNetBufferLists 函 式應該將收到的數據複製到通訊協定配置的記憶體中，並儘快傳回。

注意如果已設定 NDIS_RECEIVE_FLAGS_RESOURCES 旗標，通訊協定驅動程式必須保留連結清單中的原始 NET_BUFFER_LIST 結構集。例如，當設定此旗標時，驅動程式可能會處理結構，並指示它們一次一個堆棧，但在函式傳回之前，它必須還原原始的連結清單。

在多處理器系統上，此函式可以在多個處理器上同時執行。例如，套用保護 (，請使用微調鎖定) 至 ProtocolReceiveNetBufferLists 存取的重要數據結構。

NDIS 會在 IRQL<= DISPATCH_LEVEL呼叫 ProtocolReceiveNetBufferLists。

例子

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

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

PROTOCOL_RECEIVE_NET_BUFFER_LISTS MyReceiveNetBufferLists;

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

_Use_decl_annotations_
VOID
 MyReceiveNetBufferLists(
    NDIS_HANDLE  ProtocolBindingContext,
    PNET_BUFFER_LIST  NetBufferLists,
    NDIS_PORT_NUMBER  PortNumber,
    ULONG  NumberOfNetBufferLists,
    ULONG ReceiveFlags
    )
  {...}

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

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