WSHOpenSocket2

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

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

Parameters

AddressFamily

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

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

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

Identifies the group to which the socket that is being opened should belong if nonzero. (For more information about socket grouping, see the Win32 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

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 Win32 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

Points 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

Points 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.

Notification Events

Points 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.

Comments

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.

See Also

WSHNotify