PFN_WSK_GET_REMOTE_ADDRESS回呼函式 (wsk.h)

發行項
02/27/2024

WskGetRemoteAddress 函式會擷取連線導向或數據流套接字的遠端傳輸位址。

語法

PFN_WSK_GET_REMOTE_ADDRESS PfnWskGetRemoteAddress;

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

參數

[in] Socket

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

[out] RemoteAddress

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

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

[in, out] Irp

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

傳回值

WskGetRemoteAddress 會傳回下列其中一個 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 應用程式只能在已連線至遠端傳輸地址的連接導向或數據流套接字上呼叫 WskGetRemoteAddress 函 式。數據流套接字會藉由呼叫 WskConnect 函式來連線到遠端傳輸位址。線上導向套接字會以下列其中一種方式連線到遠端傳輸位址：

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

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

規格需求

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