PFN_WSK_GET_LOCAL_ADDRESS回呼函式 (wsk.h)

發行項
02/27/2024

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

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

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

[in, out] Irp

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

傳回值

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

傳回碼	Description
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 作業系統中使用。
目標平台	Universal
標頭	wsk.h (包含 Wsk.h)
IRQL	<= DISPATCH_LEVEL