Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

This function establishes a socket to listen for incoming connections.

Syntax 

int WSPListen(
  SOCKET 
s,
  int 
backlog,
  LPINT 
lpErrno 
);

Parameters

s

[in] Descriptor identifying a bound, unconnected socket.

backlog

[in] Maximum length to which the queue of pending connections can grow. If this value is SOMAXCONN, then the service provider should set the backlog to a maximum "reasonable" value. There is no standard provision to find out the actual backlog value.

lpErrno

[out] Pointer to the error code.

Return Value

If no error occurs, this function returns zero. Otherwise, a value of SOCKET_ERROR is returned, and a specific error code is available in lpErrno.

The following table shows the possible error codes.

Error value Description

WSAENETDOWN

Network subsystem has failed.

WSAEADDRINUSE

Socket's local address is already in use and the socket was not marked to allow address reuse with SO_REUSEADDR. This error usually occurs at the time of bind, but could be delayed until this function if the bindwas to a partially wildcard address (involving ADDR_ANY) and if a specific address needs to be committed at the time of this function.

WSAEINPROGRESS

Function is invoked when a callback is in progress.

WSAEINVAL

Socket has not been bound with WSPBind.

WSAEISCONN

Socket is already connected.

WSAEMFILE

No more socket descriptors are available.

WSAENOBUFS

No buffer space is available.

WSAENOTSOCK

Descriptor is not a socket.

WSAEOPNOTSUPP

Referenced socket is not of a type that supports the WSPListenoperation.

Remarks

To accept connections, a socket is first created with WSPSocketbound to a local address with WSPBind, a backlog for incoming connections is specified with WSPListen, and then the connections are accepted with WSPAccept. WSPListenapplies only to sockets that are connection oriented (for example, SOCK_STREAM). The socket sis put into passive mode where incoming connection requests are acknowledged and queued pending acceptance by the Windows Sockets SPI client.

This function is typically used by servers that could have more than one connection request at a time. If a connection request arrives with the queue full, the client will receive an error with an indication of WSAECONNREFUSED.

This function should continue to function rationally when there are no available descriptors. It should accept connections until the queue is emptied. If descriptors become available, a later call to WSPListenor WSPAcceptwill refill the queue to the current or most recent backlog, if possible, and resume listening for incoming connections.

A Windows Sockets SPI client can call this function more than once on the same socket. This has the effect of updating the current backlog for the listening socket. Should there be more pending connections than the new backlogvalue, the excess pending connections will be reset and dropped.

Compatibility

backlogis limited (silently) to a reasonable value as determined by the service provider. Illegal values are replaced by the nearest legal value. There is no standard provision to find out the actual backlog value.

Requirements

Header ws2spi.h
Library Ws2.lib
Windows Embedded CE Windows CE .NET 4.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also