PFN_WSK_SOCKET回呼函式 (wsk.h)

發行項
03/01/2024

WskSocket 函式會建立新的套接字，並傳回相關聯套接字物件的指標。

語法

PFN_WSK_SOCKET PfnWskSocket;

NTSTATUS PfnWskSocket(
  [in]           PWSK_CLIENT Client,
  [in]           ADDRESS_FAMILY AddressFamily,
  [in]           USHORT SocketType,
  [in]           ULONG Protocol,
  [in]           ULONG Flags,
  [in, optional] PVOID SocketContext,
  [in, optional] const VOID *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] AddressFamily

所建立套接字的位址系列。如需支援位址系列的詳細資訊，請參閱 WSK 位址系列。

[in] SocketType

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

SOCK_STREAM

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

SOCK_DGRAM

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

SOCK_RAW

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

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

[in] Protocol

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

[in] Flags

旗標，指定所建立套接字的 WSK 套接字類別。此參數可以是下列其中一個旗標：

WSK_FLAG_BASIC_SOCKET

將會建立基本套接字，其只能用來取得和設定傳輸堆疊套接字選項，或執行套接字 I/O 控制作業。

WSK_FLAG_LISTEN_SOCKET

將會建立接聽套接字，可用來接聽來自遠端傳輸位址的連入連線。

WSK_FLAG_DATAGRAM_SOCKET

將會建立數據報套接字，可用來傳送和接收數據報。

WSK_FLAG_CONNECTION_SOCKET

將會建立連線導向套接字，可用來透過連線傳送和接收網路數據。

WSK_FLAG_STREAM_SOCKET

將建立數據流套接字，可用來接聽來自遠端傳輸位址的連入連線，或透過連線傳送和接收網路數據。

如果 WSK 應用程式未指定上述任何旗標， WskSocket 會建立基本套接字。

[in, optional] SocketContext

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

[in, optional] Dispatch

常數用戶端分派結構的指標。這個結構是分派數據表，其中包含新套接字之事件回呼函式的指標。根據套接字的 WSK 套接字類別目錄， (由 Flags 參數所指定) ，此參數是下列其中一個結構的指標。

旗標	分派數據表結構
WSK_FLAG_LISTEN_SOCKET	WSK_CLIENT_LISTEN_DISPATCH
WSK_FLAG_DATAGRAM_SOCKET	WSK_CLIENT_DATAGRAM_DISPATCH
WSK_FLAG_CONNECTION_SOCKET	WSK_CLIENT_CONNECTION_DISPATCH
WSK_FLAG_STREAM_SOCKET	WSK_CLIENT_STREAM_DISPATCH

如果 WSK 應用程式不會啟用新套接字的所有事件回呼函式，它應該將分派數據表中的指標設定為 NULL ，以供未啟用的事件回呼函式使用。如果 WSK 應用程式不會在新套接字上啟用任何事件回呼函式，它應該會將 Dispatch 指標設定為 NULL。對於基本套接字，此指標應一律為 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。

傳回值

WskSocket 會傳回下列其中一個 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 會傳回包含 AddressFamily、SocketType 和 Protocol 參數之所有有效組合的WSK_TRANSPORT結構清單。

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

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

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

規格需求

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