PFN_WSK_SOCKET_CONNECT callback function (wsk.h)

Article
10/21/2021

The WskSocketConnect function creates a new connection-oriented socket, binds it to a local transport address, connects it to a given remote transport address, and returns a pointer to the associated socket object.

Syntax

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
)
{...}

Parameters

[in] Client

A pointer to a WSK_CLIENT structure that was returned through the WskProviderNpi parameter of the WskCaptureProviderNPI function.

[in] SocketType

The type of the socket that is being created. The following socket types are supported:

SOCK_STREAM

Supports reliable connection-oriented byte stream communication.

SOCK_DGRAM

Supports unreliable connectionless datagram communication.

SOCK_RAW

Supports raw access to the transport protocol.

For more information about the socket types that are supported for each supported address family, see
WSK Address Families.

[in] Protocol

The transport protocol for the socket that is being created. For more information about the protocols that are supported for each supported address family, see WSK Address Families.

[in] LocalAddress

A pointer to a structure that specifies the local transport address to which to bind the socket. The WSK application must specify a pointer to the specific SOCKADDR structure type that corresponds to the address family for the socket that is being created.

[in] RemoteAddress

A pointer to a structure that specifies the remote transport address to which to connect the socket. The WSK application must specify a pointer to the specific SOCKADDR structure type that corresponds to the address family for the socket that is being created.

Flags

This parameter is reserved for system use. WSK applications must set this parameter to zero.

[in, optional] SocketContext

A pointer to a caller-supplied context for the socket that is being created. The WSK subsystem passes this pointer to the socket's event callback functions. The context information is opaque to the WSK subsystem and must be stored in non-paged memory. If the WSK application will not be enabling any event callback functions on the new socket, it should set this pointer to NULL.

[in, optional] Dispatch

A pointer to a constant WSK_CLIENT_CONNECTION_DISPATCH structure. This structure is a dispatch table that contains pointers to the event callback functions for the new socket. If the WSK application will not be enabling all of the event callback functions for the new socket, it should set the pointers in the dispatch table to NULL for those event callback functions that it does not enable. If the WSK application will not be enabling any event callback functions on the new socket, it should set this pointer to NULL.

[in, optional] OwningProcess

A pointer to the process from which the WSK subsystem will retrieve the security context to use when it binds the socket. The WSK subsystem uses the security context to determine whether the local transport address can be shared if that address is already in use. To specify the current process, a WSK application sets this pointer to NULL.

[in, optional] OwningThread

A pointer to a specific thread from which the WSK subsystem will retrieve the security context to use when it binds the socket. The WSK subsystem uses the security context to determine whether the local transport address can be shared if that address is already in use. If a WSK application does not need to specify a specific thread, it sets this pointer to NULL.

[in, optional] SecurityDescriptor

A pointer to a SECURITY_DESCRIPTOR structure that specifies the security descriptor to apply to the socket that is being created. The security descriptor controls the sharing of the local transport address to which the socket is bound. If a WSK application specifies a non-NULL pointer, it must specify a pointer to a cached copy of a security descriptor that was obtained by calling the WskControlClient function with the WSK_CACHE_SD control code. To specify a default security descriptor that does not allow sharing of the local transport address, a WSK application sets SecurityDescriptor to NULL.

For more information about the SECURITY_DESCRIPTOR structure, see the reference page for SECURITY_DESCRIPTOR in the Microsoft Windows SDK documentation.

[in, out] Irp

A pointer to a caller-allocated IRP that the WSK subsystem uses to complete the creation of the new socket asynchronously. For more information about using IRPs with WSK functions, see Using IRPs with Winsock Kernel Functions.

Return value

WskSocketConnect returns one of the following NTSTATUS codes:

Return code	Description
STATUS_SUCCESS	The new socket was successfully created. The IRP will be completed with success status.
STATUS_PENDING	The WSK subsystem could not create the socket immediately. The WSK subsystem will complete the IRP after it has created the new socket. The status of the socket creation will be returned in the IoStatus.Status field of the IRP.
Other status codes	An error occurred. The IRP will be completed with failure status.

Remarks

If the IRP is completed with success status, the IoStatus.Information field of the IRP contains a pointer to a socket object structure ( WSK_SOCKET) for the new socket.

A WSK application can obtain a list of available transport protocols by calling the WskControlClient function with the WSK_TRANSPORT_LIST_QUERY control code. WskControlClient returns a list of WSK_TRANSPORT structures that contains all of the valid combinations of the SocketType and Protocol parameters.

The WSK subsystem determines the address family for the new socket from the address family that is specified in the SOCKADDR structure that is pointed to by the LocalAddress parameter.

If the WSK application needs to set a socket option or issue an I/O control operation on the socket before binding or connecting the socket, the WSK application must call the WskSocket, WskBind, and WskConnect functions instead of calling the WskSocketConnect function.

When a WSK application successfully creates a new socket, all of the event callback functions on the new socket are disabled by default. For more information about enabling any of the new socket's event callback functions, see Enabling and Disabling Event Callback Functions.

If a WSK application specifies a non-NULL pointer for the SecurityDescriptor parameter, it must not release the cached security descriptor until after the IRP is completed.

The WSK subsystem allocates the memory for the socket object structure (WSK_SOCKET) for the new socket on behalf of the WSK application. The WSK subsystem deallocates this memory when the socket is closed.

Requirements

Requirement	Value
Minimum supported client	Available in Windows Vista and later versions of the Windows operating systems.
Target Platform	Universal
Header	wsk.h (include Wsk.h)
IRQL	<= DISPATCH_LEVEL