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