PFN_WSK_GET_LOCAL_ADDRESS回呼函式（wsk.h）

發行項
02/07/2025

WskGetLocalAddress 函式會擷取套接字的本機傳輸位址。

語法

PFN_WSK_GET_LOCAL_ADDRESS PfnWskGetLocalAddress;

NTSTATUS PfnWskGetLocalAddress(
  [in]      PWSK_SOCKET Socket,
  [out]     PSOCKADDR LocalAddress,
  [in, out] PIRP Irp
)
{...}

參數

[in] Socket

WSK_SOCKET 結構的指標，指定正在查詢之套接字的套接字物件。

[out] LocalAddress

接收套接字本機傳輸位址之呼叫端配置的緩衝區指標。緩衝區必須位於非分頁記憶體中。緩衝區也必須夠大，才能包含對應至 WSK 應用程式在建立套接字時所指定的位址系列的特定 SOCKADDR 結構類型。

對於 WSK 應用程式在接聽套接字上接受的連接導向套接字，位址系列與建立接聽套接字時所指定的 WSK 應用程式位址系列相同。

[in, out] Irp

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

傳回值

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

傳回碼	描述
STATUS_SUCCESS	已成功擷取套接字的本機傳輸位址。 IRP 將會以成功狀態完成。
STATUS_PENDING	WSK 子系統無法立即擷取套接字的本機傳輸位址。 WSK 子系統會在擷取套接字的本機傳輸地址之後完成 IRP。擷取作業的狀態將會在 IRP 的 IoStatus.Status 字段中傳回。
STATUS_INVALID_DEVICE_STATE	套接字未系結至本機傳輸位址。 IRP 將會以失敗狀態完成。
STATUS_FILE_FORCED_CLOSED	套接字已不再運作。 IRP 將會以失敗狀態完成。 WSK 應用程式必須呼叫 WskCloseSocket 函式，以儘快關閉套接字。
其他狀態代碼	發生錯誤。 IRP 將會以失敗狀態完成。

言論

WSK 應用程式只能在已系結至本機傳輸位址的套接字上呼叫 WskGetLocalAddress 函式。

當 WSK 應用程式呼叫 WskBind 函式時，接聽、數據報或數據流套接字會系結至本機傳輸位址。

線上導向套接字會以下列其中一種方式系結至本機傳輸位址：

WSK 應用程式會呼叫 WskBind 函式。
WSK 應用程式會呼叫 WskSocketConnect 函式來建立、系結及連接套接字。
當 WSK 應用程式接受接聽套接字上的連入連線要求時，WSK 子系統會繫結套接字。

WskGetLocalAddress 函式特別適用於判斷套接字在套接字系結至本機通配符位址時，由傳輸通訊協定指派給套接字的特定本機傳輸位址。對於系結至本機通配符位址的連接導向套接字，在套接字連線到遠端傳輸位址之前，本機傳輸位址可能不會由傳輸通訊協定指派給套接字。指派本機傳輸位址給套接字的步驟與傳輸通訊協定相依。針對 TCP，當連接導向套接字系結時，會指派埠號碼，但在連線套接字之前，不會指派 IP 位址。

如果 WskGetLocalAddress 函式傳回STATUS_PENDING，LocalAddress 參數所指向的緩衝區必須維持有效，直到 IRP 完成為止。如果 WSK 應用程式使用其中一個 ExAllocateXxx 函式來配置緩衝區，則在 IRP 完成之前，它無法使用對應的 ExFreeXxx 函式釋放記憶體。如果 WSK 應用程式在堆疊上配置緩衝區，它就無法從呼叫 WskGetLocalAddress 的函式傳回，直到 IRP 完成之後， 才會傳回函式。

要求

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