WSHOpenSocket

INT
    WSHOpenSocket(
        IN OUT PINT  AddressFamily,
        IN OUT PINT  SocketType,
        IN OUT PINT  Protocol,
        OUT PUNICODE_STRING  TransportDeviceName,
        OUT PVOID  HelperDllSocketContext,
        OUT PDWORD  NotificationEvents
        );

WSHOpenSocket is called by the Windows Sockets DLL when opening a socket.

Parameter

AddressFamily

On input, propagates the address family specified in the call to socket. WSHOpenSocket resets this to the canonicalized value for the address family.

For example, if this is AF_UNSPEC on input, socket type is SOCK_STREAM, and protocol is IPPROTO_TCP, WSHOpenSocket resets this parameter to AF_INET.

SocketType

On input, propagates the socket type specified in the call to socket. WSHOpenSocket resets this to the canonicalized value for the socket type.

For example, if this is zero on input, address family is AF_INET, and protocol is IPPROTO_TCP, WSHOpenSocket resets this parameter to SOCK_STREAM.

Protocol

On input, this is set to the value specified in the call to socket. WSHOpenSocket resets this to the canonicalized value for the protocol.

For example, if this is zero on input, address family is AF_INET, and socket type is SOCK_STREAM, WSHOpenSocket resets this parameter to IPPROTO_TCP.

TransportDeviceName

Points to a Unicode counted string, specifying the name of the TDI transport that will handle the socket.

HelperDllSocketContext

Points to a variable that the helper DLL sets to a pointer to a context area that the helper DLL allocates. The Windows Sockets DLL treats this as a handle, passing it uninterpreted to the helper DLL in all subsequent calls to WSHXxx functions involving the socket currently being opened. The helper DLL uses its context area to maintain state for tracking operations on the open socket.

NotificationEvents

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 accept function.

WSH_NOTIFY_CONNECT

Call WSHNotify on a successful call to 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 on a failed called to connect occurred.

Return Value

WSHOpenSocket returns zero if the given parameters are valid. Otherwise, it returns a Windows Sockets error code. If its return value is nonzero, the socket or accept call fails and the error is set to the value returned by WSHOpenSocket.

Comments

The Windows Sockets DLL calls WSHOpenSocket whenever it is creating a new socket, either when an application calls socket or when a newly connected socket is being created by the accept function. If the helper DLL exports WSHOpenSocket2, it supersedes WSHOpenSocket.

WSHOpenSocket verifies and canonicalizes the address family, socket type, and protocol parameters so that the Windows Sockets DLL can depend on a unique triple for each type of socket.

WSHOpenSocket also allocates any necessary context structure to track subsequent operations on the open socket, and, through the NotificationEvents parameter, indicates to the Windows Sockets DLL the state-transition events at which the helper DLL does additional processing.

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, WSHOpenSocket2