PFN_WSK_SOCKET_CONNECT回呼函式 (wsk.h)

發行項
03/01/2024

WskSocketConnect 函式會建立新的連接導向套接字、將它系結至本機傳輸位址、將它連接到指定的遠端傳輸位址，以及傳回相關聯套接字物件的指標。

語法

PFN_WSK_SOCKET_CONNECT PfnWskSocketConnect;

NTSTATUS PfnWskSocketConnect(
  [in]           PWSK_CLIENT Client,
  [in]           USHORT SocketType,
  [in]           ULONG Protocol,
  [in]           PSOCKADDR LocalAddress,
  [in]           PSOCKADDR RemoteAddress,
                 ULONG Flags,
  [in, optional] PVOID SocketContext,
  [in, optional] const WSK_CLIENT_CONNECTION_DISPATCH *Dispatch,
  [in, optional] PEPROCESS OwningProcess,
  [in, optional] PETHREAD OwningThread,
  [in, optional] PSECURITY_DESCRIPTOR SecurityDescriptor,
  [in, out]      PIRP Irp
)
{...}

參數

[in] Client

透過的 WskProviderNpi 參數傳回之WSK_CLIENT結構的指標 WskCaptureProviderNPI 函式。

[in] SocketType

要建立的套接字類型。支援下列套接字型態：

SOCK_STREAM

支援可靠的連線導向位元組數據流通訊。

SOCK_DGRAM

支援不可靠的無連線數據報通訊。

SOCK_RAW

支援原始存取傳輸通訊協定。

如需每個支援位址系列所支援套接字類型的詳細資訊，請參閱
WSK 位址系列。

[in] Protocol

所建立套接字的傳輸通訊協定。如需每個支援位址系列所支援通訊協定的詳細資訊，請參閱 WSK 位址系列。

[in] LocalAddress

結構的指標，指定要系結套接字的本機傳輸位址。 WSK 應用程式必須指定特定 SOCKADDR 結構類型的指標，該類型對應至所建立套接字的位址系列。

[in] RemoteAddress

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

Flags

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

[in, optional] SocketContext

所建立套接字之呼叫端所提供內容的指標。 WSK 子系統會將這個指標傳遞至套接字的事件回呼函式。內容資訊對 WSK 子系統不透明，而且必須儲存在非分頁記憶體中。如果 WSK 應用程式不會在新套接字上啟用任何事件回呼函式，它應該將此指標設定為 NULL。

[in, optional] Dispatch

常數的指標 WSK_CLIENT_CONNECTION_DISPATCH 結構。這個結構是分派數據表，其中包含新套接字之事件回呼函式的指標。如果 WSK 應用程式不會啟用新套接字的所有事件回呼函式，它應該將分派數據表中的指標設定為 NULL ，以供未啟用的事件回呼函式使用。如果 WSK 應用程式不會在新套接字上啟用任何事件回呼函式，它應該將此指標設定為 NULL。

[in, optional] OwningProcess

WSK 子系統從中擷取系結套接字時要使用的安全性內容之進程的指標。 WSK 子系統會使用安全性內容來判斷如果該位址已在使用中，是否可以共用本機傳輸位址。若要指定目前的進程，WSK 應用程式會將此指標設定為 NULL。

[in, optional] OwningThread

WSK 子系統從中擷取系結套接字時要使用的安全性內容的特定線程指標。 WSK 子系統會使用安全性內容來判斷如果該位址已在使用中，是否可以共用本機傳輸位址。如果 WSK 應用程式不需要指定特定線程，它會將此指標設定為 NULL。

[in, optional] SecurityDescriptor

SECURITY_DESCRIPTOR 結構的指標，指定要套用至所建立套接字的安全性描述元。安全性描述項會控制套接字所系結之本機傳輸地址的共用。如果 WSK 應用程式指定非 NULL 指標，則必須使用 WSK_CACHE_SD 控件程式代碼呼叫 WskControlClient 函式，指定已快取之安全性描述元複本的指標。若要指定不允許共用本機傳輸位址的預設安全性描述元，WSK 應用程式會將 SecurityDescriptor 設定為 NULL。

如需SECURITY_DESCRIPTOR結構的詳細資訊，請參閱 Microsoft Windows SDK 檔中SECURITY_DESCRIPTOR的參考頁面。

[in, out] Irp

WSK 子系統用來以異步方式建立新套接字之呼叫端配置的 IRP 指標。如需搭配 WSK 函式使用 IRP 的詳細資訊，請參閱搭配 Winsock 核心函式使用 IRP。

傳回值

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

傳回碼	Description
STATUS_SUCCESS	已成功建立新的套接字。 IRP 將會以成功狀態完成。
STATUS_PENDING	WSK 子系統無法立即建立套接字。 WSK 子系統會在建立新的套接字之後完成 IRP。套接字建立的狀態將會在 IRP 的 [IoStatus.Status ] 字段中傳回。
其他狀態代碼	發生錯誤。 IRP 將會以失敗狀態完成。

備註

如果 IRP 已完成成功狀態，IRP 的 IoStatus.Information 欄位會包含套接字物件結構的指標， ( WSK_SOCKET 新套接字的) 。

WSK 應用程式可以使用 WSK_TRANSPORT_LIST_QUERY 控制項程式代碼呼叫 WskControlClient 函式，以取得可用的傳輸通訊協定清單。 WskControlClient 會傳回包含 SocketType 和 Protocol 參數之所有有效組合的WSK_TRANSPORT結構清單。

WSK 子系統會從由 LocalAddress 參數指向的 SOCKADDR 結構中指定的位址系列，判斷新套接字的位址系列。

如果 WSK 應用程式需要在系結或連接套接字之前，在套接字上設定套接字選項或發出 I/O 控制作業，WSK 應用程式必須呼叫 WskSocket、 WskBind 和 WskConnect 函式，而不是呼叫 WskSocketConnect 函式。

當 WSK 應用程式成功建立新的套接字時，預設會停用新套接字上的所有事件回呼函式。如需啟用任何新套接字事件回呼函式的詳細資訊，請參閱啟用和停用事件回呼函式。

如果 WSK 應用程式指定 SecurityDescriptor 參數的非 NULL 指標，則必須先在 IRP 完成之後，才釋放快取的安全性描述元。

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

規格需求

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