PFN_WSK_RECEIVE_EVENT回呼函式（wsk.h）

發行項
02/07/2025

WskReceiveEvent 事件回呼函式會通知 WSK 應用程式已收到連線導向套接字上的數據。

語法

PFN_WSK_RECEIVE_EVENT PfnWskReceiveEvent;

NTSTATUS PfnWskReceiveEvent(
  [in, optional] PVOID SocketContext,
  [in]           ULONG Flags,
  [in, optional] PWSK_DATA_INDICATION DataIndication,
  [in]           SIZE_T BytesIndicated,
  [in, out]      SIZE_T *BytesAccepted
)
{...}

參數

[in, optional] SocketContext

已接收數據之連接導向套接字之套接字內容的指標。 WSK 應用程式會以下欄其中一種方式提供此指標給 WSK 子系統：

它會呼叫 WskSocket 函式來建立套接字。
它會呼叫 WskSocketConnect 函式來建立套接字。
它會呼叫 WskAccept 函式，以接受套接字作為傳入連線。
其 WskAcceptEvent 事件回呼函式被呼叫，以接受套接字作為傳入連線。

[in] Flags

ULONG 值，其中包含下列旗標組合的位 OR：

價值	意義
WSK_FLAG_RELEASE_ASAP	如果可能的話，WSK 應用程式不應保留包含已接收數據的數據緩衝區。如果 WSK 應用程式保留緩衝區，則應該呼叫 WskRelease 函式，儘快釋放它們。
WSK_FLAG_ENTIRE_MESSAGE	數據緩衝區包含整個訊息或訊息的最後部分。構成整個訊息之內容的解釋是傳輸通訊協定特定的。針對 TCP，此旗標表示已針對構成數據緩衝區中數據的一或多個 TCP 區段設定推送位。
WSK_FLAG_AT_DISPATCH_LEVEL	WSK 子系統在 IRQL = DISPATCH_LEVEL 呼叫 WskReceiveEvent 事件回呼函式。如果未設定此旗標，WSK 子系統可能會在任何 IRQL <= DISPATCH_LEVEL 呼叫 WskReceiveEvent 事件回呼函式。

[in, optional] DataIndication

描述所接收數據之 WSK_DATA_INDICATION 結構連結清單的指標。如果此參數 NULL，套接字就無法再運作，而且 WSK 應用程式必須呼叫 WskCloseSocket 函式，才能儘快關閉套接字。

[in] BytesIndicated

WSK_DATA_INDICATION 結構連結清單所描述的已接收數據的位元組數目。

[in, out] BytesAccepted

SIZE_T型別變數的指標，可接收 WSK 應用程式所接受之已接收數據的位元組數目。只有當 WSK 應用程式接受所接收數據位元組總數的一部分時，才需要設定此變數。如果 WSK 應用程式接受所有已接收的數據，則不需要設定此變數。如果 WskReceiveEvent 事件回呼函式傳回STATUS_SUCCESS以外的狀態，WSK 子系統會忽略此變數的值。

傳回值

WSK 應用程式的 WskReceiveEvent 事件回呼函式可以傳回下列其中一個 NTSTATUS 程式代碼：

傳回碼	描述
STATUS_SUCCESS	WSK 應用程式至少接受一些已接收的數據。如果 WSK 應用程式接受所有已接收的數據，WSK 子系統可以在套接字上收到新數據時，再次呼叫 WskReceiveEvent 事件回呼函式。不過，如果 WSK 應用程式只接受所接收數據的一部分，WSK 子系統將不會再次呼叫 WskReceiveEvent 事件回呼函式，直到 WSK 應用程式呼叫 WskReceive 函式為止。在 WSK 應用程式呼叫 WskReceive 函式之後，WSK 子系統會繼續呼叫 WskReceiveEvent 事件回呼函式，其中包含任何剩餘的緩衝數據，以及在套接字上收到新數據時。 WSK 應用程式可以使用零長度緩衝區呼叫 WskReceive 函式，這會導致 WSK 子系統繼續呼叫 WskReceiveEvent 事件回呼函式，而不呼叫 WskReceive 以接收套接字的任何數據。
STATUS_PENDING	WSK 應用程式接受數據，但並未擷取包含在 WSK_DATA_INDICATION 結構連結清單中的所有數據。 WSK 應用程式會保留WSK_DATA_INDICATION結構的連結清單，直到擷取所有數據為止。在 WSK 應用程式擷取所有數據之後，它會呼叫 WskRelease 函式，將WSK_DATA_INDICATION結構的連結清單釋放回 WSK 子系統。 WSK 子系統可以在套接字上收到新數據時，再次呼叫 WskReceiveEvent 事件回呼函式。
STATUS_DATA_NOT_ACCEPTED	WSK 應用程式不接受數據。在此情況下，WSK 子系統會盡可能有基礎傳輸緩衝區數據，或者如果通訊協定需要的話。 WSK 子系統不會再次呼叫 WskReceiveEvent 事件回呼函式，直到 WSK 應用程式呼叫 WskReceive 函式之後。在 WSK 應用程式呼叫 WskReceive 函式之後，WSK 子系統會繼續呼叫 WskReceiveEvent 事件回呼函式，其中包含任何剩餘的緩衝數據，以及在套接字上收到新數據時。 WSK 應用程式可以使用零長度緩衝區呼叫 WskReceive 函式，這會導致 WSK 子系統繼續呼叫 WskReceiveEvent 事件回呼函式，而不呼叫 WskReceive 以接收套接字的任何數據。

言論

只有在先前使用 SO_WSK_EVENT_CALLBACK 套接字選項啟用事件回呼函式時，WSK 子系統才會呼叫 WSK 應用程式的 WskReceiveEvent 事件回呼函式。如需啟用套接字事件回呼函式的詳細資訊，請參閱啟用和停用事件回呼函式。

如果 WSK 應用程式的 WskReceiveEvent 事件回呼函式是在連線導向套接字上啟用，而且應用程式在相同的連線導向套接字上也具有對 WskReceive 函式的暫止呼叫，然後，當數據到達時，WskReceive 函式的暫止呼叫會優先於 WskReceiveEvent 事件回呼函式。 WSK 子系統只有在沒有從暫止呼叫佇列至 WskReceive 函式時，才會呼叫應用程式的 WskReceiveEvent 事件回呼函式。不過，WSK 應用程式不應該假設 WSK 子系統不會呼叫應用程式的 WskReceiveEvent 事件回呼函式，而連接導向套接字具有對 WskReceive 函式的暫止呼叫。存在競爭條件，其中 WSK 子系統仍可呼叫 WSK 應用程式的 WskReceiveEvent 套接字事件回呼函式。 WSK 應用程式確保 WSK 子系統不會針對連線導向套接字呼叫應用程式的 WskReceiveEvent 事件回呼函式的唯一方法是停用應用程式的 WskReceiveEvent 事件回呼函式。

注意

Winsock Kernel （WSK）會以序列方式呼叫此回呼，因此在收到數據時，不一定會叫用此回呼。

WSK 子系統會在 IRQL <= DISPATCH_LEVEL 呼叫 WSK 應用程式的 WskReceiveEvent 事件回呼函式。

WSK 應用程式的 WskReceiveEvent 事件回呼函式不得等候 WSK 完成或事件回呼函式內容中的其他 WSK 要求完成。回呼可以起始其他 WSK 要求（假設它不會花太多時間在DISPATCH_LEVEL），但即使在 IRQL = PASSIVE_LEVEL 呼叫回呼，也不得等待完成。

要求

要求	價值
最低支援的用戶端	可在 Windows Vista 和更新版本的 Windows作系統中使用。
目標平臺	窗戶
標頭	wsk.h （包括 Wsk.h）
IRQL	<= DISPATCH_LEVEL