PFN_WSK_RECEIVE_FROM_EVENT回呼函式 (wsk.h)

發行項
02/27/2024

WskReceiveFromEvent 事件回呼函式會通知 WSK 應用程式已在數據報套接字上收到一或多個數據報。

語法

PFN_WSK_RECEIVE_FROM_EVENT PfnWskReceiveFromEvent;

NTSTATUS PfnWskReceiveFromEvent(
  [in, optional] PVOID SocketContext,
  [in]           ULONG Flags,
  [in, optional] PWSK_DATAGRAM_INDICATION DataIndication
)
{...}

參數

[in, optional] SocketContext

已接收數據報之數據報套接字之套接字內容的指標。當 WSkSocket 函式呼叫 WskSocket 函式以建立數據報套接字時，WSK 應用程式會提供此指標給 WSK 子系統。

[in] Flags

包含下列旗標組合之位 OR 的 ULONG 值：

MSG_BCAST

數據報會以連結層廣播的形式接收，或接收目的地傳輸地址為廣播位址。

MSG_MCAST

數據報是以多播位址的目的地傳輸位址接收。

WSK_FLAG_AT_DISPATCH_LEVEL

WSK 子系統在 IRQL = DISPATCH_LEVEL呼叫 WskReceiveFromEvent 事件回呼函式。如果未設定此旗標，WSK 子系統可能已在任何 IRQL <= DISPATCH_LEVEL呼叫 WskReceiveFromEvent 事件回呼函式。

[in, optional] DataIndication

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

傳回值

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

傳回碼	Description
STATUS_SUCCESS	WSK 應用程式接受數據報，並從連結清單中擷取所有數據報 WSK_DATAGRAM_INDICATION 結構。當套接字上收到新的數據報時，WSK 子系統可以再次呼叫 WskReceiveFromEvent 事件回呼函式。
STATUS_PENDING	WSK 應用程式已接受數據報，但未從連結清單擷取所有數據報 WSK_DATAGRAM_INDICATION 結構。 WSK 應用程式會保留WSK_DATAGRAM_INDICATION結構的連結清單，直到擷取所有數據報為止。在 WSK 應用程式擷取所有數據報之後，它會呼叫 WskRelease 函式，將WSK_DATAGRAM_INDICATION結構的連結清單釋放回 WSK 子系統。當套接字上收到新的數據報時，WSK 子系統可以再次呼叫 WskReceiveFromEvent 事件回呼函式。
STATUS_DATA_NOT_ACCEPTED	WSK 應用程式不接受數據報。如果 WSK 應用程式傳回此狀態代碼，WSK 子系統會根據 WSK 應用程式啟用 WskReceiveFromEvent 事件回呼函式的方式，以不同的方式回應。如果 WSK 應用程式使用 [SO_WSK_EVENT_CALLBACK 套接字] 選項啟用 WskReceiveFromEvent 事件回呼函式，WSK 子系統會盡可能有基礎傳輸緩衝區數據報，或者通訊協定需要的話。 WSK 子系統會停用 WskReceiveFromEvent 事件回呼函式，而且不會再次呼叫 WskReceiveFromEvent 事件回呼函式，直到 WSK 應用程式使用 SO_WSK_EVENT_CALLBACK 套接字選項重新啟用此事件回呼函式為止。在 WSK 應用程式重新啟用 WskReceiveFromEvent 事件回呼函式之後，WSK 子系統會繼續呼叫 WskReceiveFromEvent 事件回呼函式，其中包含任何剩餘緩衝的數據報，以及在套接字上收到新的數據報時。如果 WSK 應用程式已啟用 WskReceiveFromEvent 事件回呼函式，請使用 WSK_SET_STATIC_EVENT_CALLBACKS 用戶端控制作業，WSK 子系統將不會停用 WskReceiveFromEvent 事件回呼函式。當套接字上收到新的數據報時，WSK 子系統會繼續呼叫 WskReceiveFromEvent 事件回呼函式。

備註

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

如果在數據報套接字上啟用 WSK 應用程式的 WskReceiveFromEvent 事件回呼函式，而且應用程式在相同的數據報套接字上也有對 WskReceiveFrom 函式的暫止呼叫，則當數據報送達時， WskReceiveFrom 函 式的暫止呼叫會優先於 WskReceiveFromEvent 事件回呼函式。只有在 WskReceiveFromFrom 函式沒有佇列從擱置呼叫到 WskReceiveFrom 函式的 IRP 時，WSK 子系統才會呼叫應用程式的 WskReceiveFrom 事件回呼函式。不過，WSK 應用程式不應該假設 WSK 子系統不會針對對 WskReceiveFromFromEvent 函式進行暫止呼叫的數據報套接字呼叫 WskReceiveFrom 事件 回呼函式呼叫。 WSK 子系統仍可針對套接字呼叫 WSK 應用程式的 WskReceiveFromEvent 事件回呼函式的競爭條件。 WSK 應用程式確保 WSK 子系統不會在數據報套接字上呼叫應用程式的 WskReceiveFromEvent 事件回呼函式的唯一方法是停用應用程式的 WskReceiveFromEvent 事件回呼函式。

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

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

規格需求

需求	值
最低支援的用戶端	可在 Windows Vista 和更新版本的 Windows 作業系統中使用。
目標平台	Windows
標頭	wsk.h (包含 Wsk.h)
IRQL	<= DISPATCH_LEVEL