WSPListen function
WSPListen establishes a socket to listen for incoming connections.
Syntax
int WSPListen(
_In_ SOCKET s,
_In_ int backlog,
_Out_ LPINT lpErrno
);
Parameters
s [in]
Descriptor that identifies a bound, unconnected socket.backlog [in]
Maximum length to which the queue of pending connections can grow. If set to SOMAXCONN, the SAN service provider should set its pending-connection queue to a reasonable maximum length. If the SAN service provider sets the backlog, there is no standard provision for the switch to determine the backlog.lpErrno [out]
Pointer to a variable that receives the error code.
Return value
Returns zero if successful; otherwise, returns SOCKET_ERROR and, at lpErrno, one of the following error codes:
| Return code | Description |
|---|---|
| WSAENETDOWN | Network subsystem failed. |
| WSAEINVAL | The switch did not previously call the SAN service provider's WSPBind function to bind the socket. |
| WSAEISCONN | Socket is already connected. |
| WSAEMFILE | No more socket descriptors available. |
| WSAENOBUFS | No buffer space available. |
| WSAENOTSOCK | Descriptor is not a socket. |
Note that a SAN service provider does not support the following error codes for WSPListen:
| Return code | Description |
|---|---|
| WSAEADDRINUSE | The Windows Sockets switch, in conjunction with the TCP/IP provider, handles address reuse. |
| WSAEINPROGRESS | The Windows Sockets switch never issues cancel blocking calls to a SAN service provider. |
| WSAEOPNOTSUPP | The socket is the appropriate type (that is, SOCK_STREAM). |
Remarks
The Windows Sockets switch calls a SAN service provider's WSPListen function to set a socket to acknowledge and queue incoming connection requests until the switch accepts them.
To accept incoming connection requests, the switch first calls the SAN service provider's WSPSocket function to create a socket and then calls the SAN service provider's WSPBind function to bind the socket to a local IP address. The switch can bind a socket to either the IP address of one of the network interface cards (NICs) serviced by the SAN service provider or to the wildcard IP address (0.0.0.0). The wildcard IP address implies that the SAN service provider should accept incoming connection requests from all NICs it controls. The switch next calls the WSPListen function to set the socket to passive mode in which the SAN service provider acknowledges and queues incoming connection requests. In this call, the switch specifies the maximum size of the queue. The switch subsequently calls the WSPAccept function to accept connection requests in the queue.
Note Beginning with Windows Vista, the wildcard IP address 0.0.0.0 is not available.
Also beginning with Windows Vista, if the IPAutoconfigurationEnabled registry key is set to a value of 0, automatic IP address assignment is disabled, and no IP address is assigned. In this case, the ipconfig command line tool will not display an IP address. If the key is set to a nonzero value, an IP address is automatically assigned. This key can be located at the following paths in the registry:
HKEY_LOCAL_MACHINE\SYSTEM\Current Control Set\Services\Tcpip\Parameters\IPAutoconfigurationEnabled
HKEY_LOCAL_MACHINE\SYSTEM\Current Control Set\Services\Tcpip\Parameters\Interfaces\GUID\IPAutoconfigurationEnabled
Typically, servers might receive more than one connection request at a time. The Windows Sockets switch on such a server calls the SAN service provider's WSPListen function to queue incoming-connection requests. Remote clients establish connections with those servers. The Windows Sockets switch on such a remote client calls the SAN service provider's WSPConnect function to initiate a connection operation. If a connection request arrives on the server and the SAN service provider's incoming-connection queue is full, the SAN service provider should immediately indicate to the remote client that it refuses the connection request. The SAN service provider on the remote client must then fail its connection operation with the WSAECONNREFUSED error code.
The WSPListen function should continue to function even if socket descriptors are not available. It should accept connections until the queue is emptied. If descriptors become available, a subsequent call to WSPListen or WSPAccept refills the queue to the current or most recent backlog, if possible, and resumes listening for incoming connections.
The switch can call the WSPListen function more than once on the same socket. Doing so updates the current backlog for the listening socket. If the number of incoming connection requests in the queue exceeds the specified maximum size for the queue, the SAN service provider resets and drops excess connection requests.
Note The SAN service provider silently limits the maximum size of the queue of incoming connection requests to a reasonable value. If the switch passes an invalid value for this maximum queue size, the SAN service provider replaces the invalid value with the nearest valid value. There is no standard provision that the switch can use to determine the actual maximum queue size that the SAN service provider uses.
Requirements
Target platform |
Desktop |
Version |
Requires Windows Sockets version 2.0. |
Header |
Ws2spi.h (include Ws2spi.h) |
See also