PFN_WSK_ACCEPT回呼函式 (wsk.h)

發行項
02/27/2024

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

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

[out, optional] RemoteAddress

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

[in, out] Irp

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

傳回值

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

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

備註

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

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

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

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

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

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

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

規格需求

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