NDIS_TCP_OFFLOAD_RECEIVE_INDICATE回呼函式 (ndischimney.h)

發行項
03/01/2024

[TCP chimney 卸除功能已被取代，不應使用。]

卸除目標會呼叫 NdisTcpOffloadReceiveHandler 函式，以指出接收的網路數據可供用戶端應用程式取用。

語法

NDIS_TCP_OFFLOAD_RECEIVE_INDICATE NdisTcpOffloadReceiveIndicate;

NDIS_STATUS NdisTcpOffloadReceiveIndicate(
  [in]  IN NDIS_HANDLE NdisOffloadHandle,
  [in]  IN PNET_BUFFER_LIST NetBufferList,
  [in]  IN NDIS_STATUS Status,
  [out] OUT PULONG BytesConsumed
)
{...}

參數

[in] NdisOffloadHandle

句柄，識別發出指示的卸除 TCP 連線。卸除連線時，此句柄是在 的 NdisOffloadHandle 成員中提供 NDIS_MINIPORT_OFFLOAD_BLOCK_LIST 與連接狀態相關聯的結構。

[in] NetBufferList

NET_BUFFER_LIST 結構的指標。每個 NET_BUFFER_LIST 結構都會描述 NET_BUFFER 結構的清單。清單中的每個 NET_BUFFER 結構都會對應至 (MDL) 的記憶體描述元清單鏈結。 MDL 包含收到的數據。 MDL 會鎖定，讓它們保持駐留狀態，但不會對應到系統記憶體。

NetBufferList 指定的NET_BUFFER_LIST結構必須是獨立結構，而且不能是NET_BUFFER_LIST結構連結清單中的第一個結構。卸除目標可以藉由鏈結至卸除接收指示中相同 NET_BUFFER 所需的多個 MDL，來解決這項限制。

[in] Status

卸除目標必須提供下列狀態值：

NDIS_STATUS_SUCCESS

這表示主機堆疊可以保留NET_BUFFER_LIST結構和相關聯結構的擁有權，直到將這些結構傳回至卸除目標的 MiniportTcpOffloadReceiveReturn 函式。

[out] BytesConsumed

ULONG 型別變數的指標，可接收用戶端應用程式所取用的位元元組數目。

傳回值

NdisTcpOffloadReceiveHandler 函式可以傳回下列其中一個值：

傳回碼	Description
NDIS_STATUS_SUCCESS	用戶端應用程式已取用所有指定的接收數據。
NDIS_STATUS_OFFLOAD_DATA_NOT_ACCEPTED	用戶端應用程式拒絕所有指定的接收數據。
NDIS_STATUS_OFFLOAD_DATA_PARTIALLY_ACCEPTED	用戶端應用程式已取用所指定接收數據的子集。用戶端應用程式所取用的數據量，以位元組為單位，會在 BytesConsumed 參數所指定的變數中傳回。

備註

接收緩衝區會張貼至卸除目標的 MiniportTcpOffloadReceive 函式。如果預先發佈接收要求 (用戶端應用程式提供的緩衝區) 可供連線使用，卸除目標應該藉由呼叫來傳輸接收數據 NdisTcpOffloadReceiveComplete 函式。如需詳細資訊，請參閱傳遞演算法。

卸除目標 (必須完成所有接收要求，即使這些要求是零位元組接收要求) 也一樣。

卸除目標指出接收數據且數據遭到拒絕之後，卸除目標無法再次指出數據，直到主機堆棧張貼接收要求為止：

一般接收要求
如果主機堆疊張貼一般接收要求，卸除目標必須先完成這些要求，才能發出任何接收指示。如需詳細資訊，請參閱傳遞演算法。
零位元組接收要求
主機堆疊可以張貼零位元組接收要求，以啟用卸除目標的接收指示。零位元組接收要求是 DataLength 成員值 (的一個，如需詳細資訊，請參閱 NET_BUFFER結構) 為零。零位元組接收要求不會取用任何緩衝的數據。

在初始化期間，卸除目標應該配置兩個緩衝區集區，每個集區都包含NET_BUFFER_LIST結構和NET_BUFFER結構。卸除目標會在呼叫時使用一個集區，透過TCP chimney 進行接收指示 NdisTcpOffloadReceiveHandler 函 式。卸除目標使用其他集區，在呼叫時透過非卸除 NDIS 介面進行接收指示 NdisMIndicateReceiveNetBufferLists 函式。

每個配置NET_BUFFER_LIST結構都必須只有一個與其相關聯的NET_BUFFER結構。要配置的這類結構數目由驅動程式寫入器決定。如需配置這類結構的詳細資訊，請參閱 Miniport 驅動程式緩衝區管理。

如果卸除目標沒有延遲認可，卸除目標應該會在卸除目標具有可儲存數據的內部緩衝區時立即認可收到的數據。卸除目標可以在呼叫 NdisTcpOffloadReceiveHandler 函式之前、期間或之後認可已接收的數據。

卸除目標一律會在呼叫 NdisTcpOffloadReceiveHandler 函式時提供狀態值NDIS_STATUS_SUCCESS。這表示主機堆疊可以保留NET_BUFFER_LIST結構和相關聯結構的擁有權，直到將這些結構傳回卸除目標為止。

如果主機堆疊傳回NDIS_STATUS_SUCCESS，表示用戶端應用程式已接受並取用接收數據，主機堆疊會將NET_BUFFER_LIST結構傳回至卸除目標的 MiniportTcpOffloadReceiveReturn 函式。主機堆疊會將 BytesConsumed 參數指定的變數設定為卸除目標所指示的位元組數目。
如果主機堆棧傳回NDIS_STATUS_NOT_ACCEPTED，表示用戶端應用程式拒絕接收數據，卸除目標會在 傳回 NdisTcpOffloadReceiveHandler 函式時繼續擁有所指示NET_BUFFER_LIST結構的擁有權。卸除目標必須緩衝接收數據，預期用戶端應用程式會在連線上張貼接收緩衝區。用戶端應用程式張貼接收緩衝區之後，卸除目標會將緩衝接收的數據複製到張貼的緩衝區，並藉由呼叫來完成張貼的緩衝區。 NdisTcpOffloadReceiveComplete 函式。如需詳細資訊，請參閱傳遞演算法。主機堆疊會將 BytesConsumed 參數指定的變數設定為零。
如果主機堆棧傳回NDIS_STATUS_OFFLOAD_DATA_PARTIALLY_ACCEPTED，表示用戶端應用程式取用接收數據的子集，當 NdisTcpOffloadReceiveHandler 函式傳回時，卸除目標會繼續指定之NET_BUFFER_LIST結構的擁有權。主機堆疊會將 BytesConsumed 參數指定的變數設定為非零值，以位元組為單位，以位元組為單位，由用戶端應用程式取用。卸除目標必須緩衝剩餘的接收數據，預期用戶端應用程式會在連線上張貼接收緩衝區。