PFN_WSK_ACCEPT回呼函式（wsk.h）

發行項
02/07/2025

WskAccept 函式會接受接聽套接字上的連入連線。

語法

PFN_WSK_ACCEPT PfnWskAccept;

NTSTATUS PfnWskAccept(
  [in]            PWSK_SOCKET ListenSocket,
                  ULONG Flags,
  [in, optional]  PVOID AcceptSocketContext,
  [in, optional]  const WSK_CLIENT_CONNECTION_DISPATCH *AcceptSocketDispatch,
  [out, optional] PSOCKADDR LocalAddress,
  [out, optional] PSOCKADDR RemoteAddress,
  [in, out]       PIRP Irp
)
{...}

參數

[in] ListenSocket

WSK_SOCKET 結構的指標，指定正在檢查連入連線之接聽或數據流套接字的套接字物件。

Flags

此參數保留供系統使用。 WSK 應用程式必須將此參數設定為零。

[in, optional] AcceptSocketContext

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

[in, optional] AcceptSocketDispatch

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

[out, optional] LocalAddress

呼叫端配置的緩衝區指標，接收傳入連線抵達的本機傳輸位址。緩衝區必須位於非分頁記憶體中。緩衝區也必須夠大，才能包含對應至 WSK 應用程式在建立接聽套接字時所指定的位址系列的特定 SOCKADDR 結構類型。此指標是選擇性的，而且可以 NULL。

[out, optional] RemoteAddress

呼叫端配置的緩衝區指標，接收傳入連線的來源遠端傳輸位址。緩衝區必須位於非分頁記憶體中。緩衝區也必須夠大，才能包含對應至 WSK 應用程式在建立接聽套接字時所指定的位址系列的特定 SOCKADDR 結構類型。此指標是選擇性的，而且可以 NULL。

[in, out] Irp

WSK 子系統用來異步完成接受作業的呼叫端配置 IRP 指標。如需搭配 WSK 函式使用 IRP 的詳細資訊，請參閱搭配 Winsock 核心函式使用 IRP。

傳回值

WskAccept 會傳回下列其中一個 NTSTATUS 程式代碼：

傳回碼	描述
STATUS_SUCCESS	已成功接受連入連線。 IRP 將會以成功狀態完成。
STATUS_PENDING	IRP 已由 WSK 子系統排入佇列，該子系統正在等候接聽套接字上的連入連線。
STATUS_FILE_FORCED_CLOSED	套接字已不再運作。 IRP 將會以失敗狀態完成。 WSK 應用程式必須呼叫 WskCloseSocket 函式，以儘快關閉套接字。
其他狀態代碼	發生錯誤。 IRP 將會以失敗狀態完成。

言論

WSK 應用程式可以在接聽套接字或串流套接字上呼叫 WskAccept 函式，其先前呼叫 WskBind 函式系結至本機傳輸位址。

WskAccept 函式的行為取決於傳入連線是否在接聽套接字上等候接受：

如果連入連線已抵達接聽套接字且正在等候接受，則 WskAccept 函式會傳回STATUS_SUCCESS。在此情況下，IRP 會以成功狀態完成，且 IRP 的 IoStatus.Information 字段包含已接受套接字之套接字物件的指標。
如果傳入連線未在接聽套接字上接受，WskAccept 會傳回STATUS_PENDING，而 WSK 子系統會排入 IRP 佇列，直到收到連入連線為止。收到連入連線時，WSK 子系統會以異步方式完成 IRP 並成功狀態。在此情況下，IRP 的 IoStatus.Information 字段包含已接受套接字之套接字物件的指標。

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

當 WskAccept 函式成功接受連入連線時，預設會停用接受套接字上的所有事件回呼函式。如需開啟任何已接受套接字事件回呼函式的詳細資訊，請參閱啟用和停用事件回呼函式。

如果 WSK 應用程式在 LocalAddress 參數、RemoteAddress 參數或兩個參數中指定非NULL 指標，則 STATUS_PENDING 這些參數所指向的緩衝區必須維持有效，直到 IRP 完成為止。如果 WSK 應用程式使用其中一個 ExAllocateXxx 函式配置緩衝區，則除非 IRP 完成之後，才能使用對應的 ExFreeXxx 函式釋放記憶體。如果 WSK 應用程式在堆疊上配置緩衝區，它就無法從呼叫 WskAccept 函式的函式傳回，直到 IRP 完成之後。

WSK 子系統會代表 WSK 應用程式，為接受的連接配置套接字對象結構的記憶體（WSK_SOCKET）。 WSK 子系統會在套接字關閉時解除分配此記憶體。

要求

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