WSHOpenSocket function

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

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

Syntax

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

Parameters

• AddressFamily [in, out]
  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 [in, out]
  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 [in, out]
  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 [out]
  Pointer to a Unicode counted string, specifying the name of the TDI transport that will handle the socket.

• HelperDllSocketContext [out]
  Pointer 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 [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 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.

Remarks

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.

Requirements

See also

WSHNotify

WSHOpenSocket2

Send comments about this topic to Microsoft