PFN_WSK_RECEIVE_EVENT回呼函式 (wsk.h)

發行項
02/27/2024

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	在 IRQL = DISPATCH_LEVEL呼叫 WskReceiveEvent 事件回呼函式的 WSK 子系統。如果未設定此旗標，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 代碼：

傳回碼	Description
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 事件回呼函式。只有在沒有從擱置呼叫 WskReceive 函式排入佇列的 IRP 時，WSK 子系統才會呼叫應用程式的 WskReceiveEvent 事件回呼函式。不過，WSK 應用程式不應該假設 WSK 子系統不會針對對 WskReceive 函式進行擱置呼叫的連接導向套接字呼叫應用程式的 WskReceiveEvent 事件回呼函式。存在 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 作業系統中使用。
目標平台	Windows
標頭	wsk.h (包含 Wsk.h)
IRQL	<= DISPATCH_LEVEL