WSHOpenSocket2 function

Article
06/19/2017

[ This function is obsolete for Windows Server 2003, Windows Vista, and later, and is no longer supported. ]

The WSHOpenSocket2 function is called by the MSAFD support DLL in response to an application call to WSASocket.

Syntax

INT WSHOpenSocket2(
  _Inout_ PINT            AddressFamily,
  _Inout_ PINT            SocketType,
  _Inout_ PINT            Protocol,
  _In_    GROUP           Group,
  _In_    DWORD           Flags,
  _Out_   PUNICODE_STRING TransportDeviceName,
  _Out_   PVOID           *HelperDllSocketContext,
  _Out_   PDWORD          NotificationEvents
);

Parameters

AddressFamily [in, out]
On input, points to a variable that is set to the address family as specified in the WSASocket call. On output, the variable should be set to the canonicalized value for the address family.
SocketType [in, out]
On input, points to a variable that is set to the socket type as specified in the WSASocket call. On output, the variable should be set to the canonicalized value for the socket type.
Protocol [in, out]
On input, points to a variable that is set to the protocol as specified in the WSASocket call. On output, the variable should be set to the canonicalized value for the protocol.
Group [in]
Identifies the group to which the socket that is being opened should belong if nonzero. (For more information about socket grouping, see the Microsoft Windows SDK.) Alternatively, this can be one of the following constants to create a new group of sockets.
- SG_UNCONSTRAINED_GROUP
  Create an new unconstrained group of sockets and have this socket become the first member of that group.
- SG_CONSTRAINED_GROUP
  Create a new constrained group of sockets and have this socket become the first member of that group.
MSAFD will handle all group mechanisms. The group number, if specified instead of one of the preceding flags, is provided for informational purposes.
Flags [in]
Specifies attributes for the new socket that is to be created. (For more information about Windows Sockets 2 multipoint and root/leaf sockets, see the Windows SDK.) The following lists valid flags that can be specified:
- WSA_FLAG_OVERLAPPED
  Indicates that a socket capable of handing overlapped I/O should be created. If this flag is set, overlapped I/O can be further utilized on calls to WSASend, WSASendTo, WSARecv, WSARecvFrom and WSAIoctl.
- WSA_FLAG_MULTIPOINT_C_ROOT
  Indicates that the socket should be created as a c_root in a multipoint session.
- WSA_FLAG_MULTIPOINT_C_LEAF
  Indicates that the socket should be created as a c_leaf in a multipoint session.
- WSA_FLAG_MULTIPOINT_D_ROOT
  Indicates that the socket should be created as a d_root in a multipoint session.
- WSA_FLAG_MULTIPOINT_D_LEAD
  Indicates that the socket should be created as a d_leaf in a multipoint session.
TransportDeviceName [out]
Pointer to a buffered Unicode string that specifies the device name of the transport driver that will support this socket type. Storage for the UNICODE_STRING structure is allocated by the caller, and the string initialized with the transport device name, such as \\Device\\Tcp.
HelperDllSocketContext [out]
Pointer to a variable in which WSHOpenSocket2 returns the address of a memory block that can be dynamically allocated. The returned pointer is passed to the helper DLL in all subsequent calls regarding the newly created socket. The helper DLL can use this block of memory to maintain per-socket information.
NotificationEvents [out]
Pointer to a bitmask variable that the helper DLL sets to specify the state-change events for which the Windows Sockets DLL should call the helper DLL's WSHNotify function. A helper DLL can request notifications by setting this variable to a combination (ORed) of the following, as defined in wsahelp.h:
- WSH_NOTIFY_BIND
  Call WSHNotify on a successful call to bind.
- WSH_NOTIFY_LISTEN
  Call WSHNotify on a successful call to listen.
- WSH_NOTIFY_ACCEPT
  Call WSHNotify when a socket handle is being returned from the WSAAccept or accept function.
- WSH_NOTIFY_CONNECT
  Call WSHNotify on a successful call to WSAConnect or connect.
- WSH_NOTIFY_SHUTDOWN_RECEIVE
  Call WSHNotify on a successful call to shutdown for the receive side of the socket.
- WSH_NOTIFY_SHUTDOWN_SEND
  Call WSHNotify on a successful call to shutdown for the send side of the socket.
- WSH_NOTIFY_SHUTDOWN_ALL
  Call WSHNotify on a successful call to shutdown for both sides of the socket.
- WSH_NOTIFY_CLOSE
  Call WSHNotify when the socket is being closed.
- WSH_NOTIFY_CONNECT_ERROR
  Call WSHNotify when a socket fails a call to WSAConnect or connect occurred.

Return value

WSHOpenSocket2 returns zero to indicate a successful creation of a socket. If this function returns a nonzero value, the corresponding call to WSASocket or WSAAccept fails. If so, the helper DLL should return an appropriate Windows Sockets error code as defined in winsock2.h.

Remarks

WSHOpenSocket2 is called by the sockets service provider, such as MSAFD.DLL, to create a new socket. A new socket will be created by a call to WSASocket or by WSAAccept.

The helper DLL should canonicalize and verify the input parameters so that Windows Sockets 2 can rely on a unique triple for each type of socket. The parameters for creating a root or leaf depend on the underlying protocol.

Before it returns control, WSHOpenSocket2 should allocate necessary memory for a socket-specific context structure, set a notification bitmask, and set the name of the transport driver that handles this socket.

A WSH DLL must set NotificationEvents with WSH_NOTIFY_CLOSE if it allocates memory for per-socket context and returns a pointer at HelperDllSocketContext. Otherwise, a memory leak can occur.

Requirements

Target platform	Desktop
Header	Wsahelp.h (include Wsahelp.h)

Share via