PFN_WSK_CONNECT_EX回呼函式 (wsk.h)

發行項
03/01/2024

WskConnectEx 函式會將連接導向或數據流套接字連線到遠端傳輸位址。

WskConnectEx 類似於 WskConnect ，不同之處在於它也可以在連接同步處理期間或之後選擇性地傳送數據的緩衝區。

語法

PFN_WSK_CONNECT_EX PfnWskConnectEx;

NTSTATUS PfnWskConnectEx(
  [in]           PWSK_SOCKET Socket,
  [in]           PSOCKADDR RemoteAddress,
  [in, optional] PWSK_BUF Buffer,
                 ULONG Flags,
  [in, out]      PIRP Irp
)
{...}

參數

[in] Socket

WSK_SOCKET 結構的指標，指定連接到遠端傳輸位址之套接字的套接字物件。

[in] RemoteAddress

結構的指標，指定要連接套接字的遠端傳輸位址。這個指標必須是特定 SOCKADDR 結構類型的指標，對應至建立套接字時所指定的 WSK 應用程式所指定的位址系列。

[in, optional] Buffer

WSK_BUF 結構的指標，其中包含在連線同步處理期間或之後要傳送的數據。位元組中允許的大小上限為65,535。

Flags

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

[in, out] Irp

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

傳回值

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

傳回碼	Description
STATUS_SUCCESS	套接字已成功連線到遠端傳輸位址。 IRP 將會以成功狀態完成。
STATUS_PENDING	WSK 子系統無法立即連接套接字。 WSK 子系統將套接字連線到遠端傳輸地址之後，將會完成 IRP。線上作業的狀態將會在 IRP 的 [IoStatus.Status ] 字段中傳回。
STATUS_FILE_FORCED_CLOSED	套接字已不再運作。 IRP 將會以失敗狀態完成。 WSK 應用程式必須呼叫 WskCloseSocket 函式，才能儘快關閉套接字。
STATUS_INVALID_PARAMETER	WSK 應用程式嘗試將旗標傳遞至 Flags 參數 (，因為 WskConnectEx 目前未定義有效的旗標，因此不允許) 。
STATUS_BUFFER_OVERFLOW	WSK 應用程式嘗試將大於 65,535 個字節的緩衝區傳入 Buffer 參數。
其他狀態代碼	發生錯誤。 IRP 將會以失敗狀態完成。

備註

WSK 應用程式可以藉由呼叫 WskSocketConnect 函式，而不是呼叫 WskSocket 函式、 WskBind 函式，以及 WskConnectEx 函式，在單一函式呼叫中建立、系結及連接連接導向套接字。建議您呼叫 WskSocketConnect 函式，除非 WSK 應用程式需要設定套接字選項，或在系結或連接套接字之前發出 I/O 控制作業。

WSK 應用程式只能藉由呼叫 WskBind 函式，在應用程式先前系結至本機傳輸位址的連接導向或數據流套接字上呼叫 WskConnectEx 函式。

針對數據流套接字，一旦成功在數據流套接字上呼叫 WskConnectEx ，套接字就會認可至連線導向的流程，而且無法再呼叫接聽套接字函式。

如果使用 Buffer 參數，呼叫端只要連接要求完成，就可以在其 WSK_BUF 結構中釋放 MDL。

使用提供的傳送緩衝區呼叫 WskConnectEx 之前，如果 WSK 應用程式透過 WskControlSocket 函式設定 WSK 套接字上的 TCP_FASTOPEN 選項，系統將會選擇性地傳送 SYN 封包中的部分或所有數據。如需詳細資訊，請參閱 IPPROTO_TCP套接字選項中的 TCP Fastopen 選項。