PFN_WSK_ACCEPT_EVENT回呼函式 (wsk.h)

發行項
02/27/2024

WskAcceptEvent 事件回呼函式會通知 WSK 應用程式已接受接聽套接字上的連入連線。

語法

PFN_WSK_ACCEPT_EVENT PfnWskAcceptEvent;

NTSTATUS PfnWskAcceptEvent(
  [in, optional] PVOID SocketContext,
  [in]           ULONG Flags,
  [in]           PSOCKADDR LocalAddress,
  [in]           PSOCKADDR RemoteAddress,
  [in, optional] PWSK_SOCKET AcceptSocket,
  [out]          PVOID *AcceptSocketContext,
  [out]          const WSK_CLIENT_CONNECTION_DISPATCH **AcceptSocketDispatch
)
{...}

參數

[in, optional] SocketContext

接受傳入連接之接聽套接字之套接字內容的指標。當 WskSocket 函式呼叫 WskSocket 函式以建立接聽套接字時，WSK 應用程式會提供 WSK 子系統的這個指標。

[in] Flags

包含下列旗標或零的 ULONG 值：

WSK_FLAG_AT_DISPATCH_LEVEL

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

[in] LocalAddress

緩衝區的指標，其中包含傳入聯機抵達所在的本機傳輸位址。緩衝區包含特定的 SOCKADDR 結構類型，其對應至建立接聽套接字時所指定的 WSK 應用程式所指定的位址系列。

[in] RemoteAddress

緩衝區的指標，其中包含傳入連線的來源遠端傳輸位址。緩衝區包含特定的 SOCKADDR 結構類型，其對應至建立接聽套接字時所指定的 WSK 應用程式所指定的位址系列。

[in, optional] AcceptSocket

WSK_SOCKET 結構的指標，這是所接受套接字的套接字物件。如果此指標為 NULL，則接聽套接字已不再運作，且 WSK 應用程式必須呼叫 WskCloseSocket 函式，儘快關閉接聽套接字。

[out] AcceptSocketContext

接收所接受套接字之 WSK 應用程式所提供內容的指標之變數指標。 WSK 子系統會將這個指標傳遞至已接受套接字的事件回呼函式。內容資訊對 WSK 子系統不透明，而且必須儲存在非分頁記憶體中。如果 WSK 應用程式不會在接受的套接字上啟用任何事件回呼函式，應用程式應該將 AcceptSocketContext 參數所指向的變數設定為 NULL。

[out] AcceptSocketDispatch

接收常數指標之變數的指標 WSK_CLIENT_CONNECTION_DISPATCH 結構。這個結構是分派數據表，其中包含接受套接字之事件回呼函式的指標。如果 WSK 應用程式不會針對接受的套接字啟用所有事件回呼函式，應用程式應該針對它未啟用的事件回呼函式，將分派數據表中的指標設定為 NULL 。如果 WSK 應用程式不會在接受的套接字上啟用任何事件回呼函式，它應該將 AcceptSocketDispatch 參數所指向的變數設定為 NULL。

傳回值

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

傳回碼	Description
STATUS_SUCCESS	WSK 應用程式已接受連入連線。
STATUS_REQUEST_NOT_ACCEPTED	WSK 應用程式拒絕傳入連線。如果傳回此值，WSK 子系統將會代表 WSK 應用程式關閉已接受的套接字。

備註

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

如果 WSK 應用程式的 WskAcceptEvent 事件回呼函式是在接聽套接字上啟用，且應用程式對相同接聽套接字上的 WskAccept 函式有暫止呼叫，則當傳入連線到達時， 對 WskAccept 的暫止呼叫優先於 WskAcceptEvent 事件回呼函式。只有在沒有從擱置呼叫 WskAccept 函式排入佇列的 IRP 時，WSK 子系統才會呼叫應用程式的 WskAccept 事件回呼函式。不過，WSK 應用程式不應該假設 WSK 子系統不會呼叫應用程式的 WskAcceptEvent 事件回呼函式，而接聽套接字具有 WskAccept 函式的暫止呼叫。存在 WSK 子系統仍可呼叫 WSK 應用程式的 WskAcceptEvent 事件回呼函式的競爭條件。 WSK 應用程式確保 WSK 子系統不會針對接聽套接字呼叫應用程式的 WskAcceptEvent 事件回呼函式的唯一方法是停用應用程式的 WskAcceptEvent 事件回呼函式。

當 WSK 子系統呼叫 WSK 應用程式的 WskAcceptEvent 事件回呼函式時，預設會停用所接受套接字上的所有事件回呼函式。如果 WSK 應用程式在接聽套接字上啟用任何連線導向套接字事件回呼函式，則預設會在接聽套接字上接受的所有連線導向套接字上啟用這些事件回呼函式。如需啟用任何已接受套接字事件回呼函式的詳細資訊，請參閱啟用和停用事件回呼函式。

LocalAddress 和 RemoteAddress 參數所指向的 SOCKADDR 結構只有在呼叫 WskAcceptEvent 事件回呼函式的持續時間才有效。如果 WSK 應用程式稍後需要這些傳輸位址，它可以先將這些結構的內容複製到自己的 SOCKADDR 結構，再從 WskAcceptEvent 事件回呼函式傳回，或者稍後可以在接受的套接字上呼叫 WskGetLocalAddress 和 WskGetRemoteAddress 函式。

WSK 子系統會代表 WSK 應用程式設定套接字物件結構的記憶體 ( WSK_SOCKET) 。 WSK 子系統會在套接字關閉時解除分配此記憶體。

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

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

規格需求

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