listen (Windows Embedded CE 6.0)
1/6/2010
This function places a socket at a state where it is listening for an incoming connection.
Syntax
int listen(
SOCKET s,
int backlog
);
Parameters
- s
[in] Descriptor identifying a bound, unconnected socket.
- backlog
[in] Maximum length of the queue of pending connections. If backlog is set to SOMAXCONN, the underlying service provider responsible for socket s will set the backlog to a maximum reasonable value. There is no standard provision to obtain the actual backlog value.
Return Value
If no error occurs, this function returns zero. If an error occurs, a value of SOCKET_ERROR is returned, and a specific error code can be retrieved by calling WSAGetLastError.
The following table shows a list of possible error codes.
| Error code | Description |
|---|---|
WSANOTINITIALISED |
A successful WSAStartup call must occur before using this function. |
WSAENETDOWN |
The network subsystem has failed. |
WSAEADDRINUSE |
The 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 during execution of the bind (Windows Sockets) function, but it could be delayed until the listen function if the bind was to a partially wildcard address (involving ADDR_ANY) and if a specific address needs to be committed at the time of the listen function. |
WSAEINPROGRESS |
A blocking Winsock call is in progress, or the service provider is still processing a callback function. |
WSAEINVAL |
The socket has not been bound with bind. |
WSAEISCONN |
The socket is already connected. |
WSAEMFILE |
No more socket descriptors are available. |
WSAENOBUFS |
No buffer space is available. |
WSAENOTSOCK |
The descriptor is not a socket. |
WSAEOPNOTSUPP |
The referenced socket is not of a type that supports the listen operation. |
Remarks
To accept connections, a socket is first created with the socket (Windows Sockets) function and bound to a local address with the bind (Windows Sockets) function, a backlog for incoming connections is specified with listen, and the connections are accepted with the accept (Windows Sockets) function. Sockets that are connection-oriented, those of type SOCK_STREAM for example, are used with listen. Socket s is put into passive mode where incoming connection requests are acknowledged and queued pending acceptance by the process.
The listen function is typically used by servers that can have more than one connection request at a time. If a connection request arrives and the queue is full, the client will receive an error with an indication of WSAECONNREFUSED.
If there are no available socket descriptors, listen attempts to continue to function. If descriptors become available, a later call to listen or accept will refill the queue to the current or most recent backlog, if possible, and resume listening for incoming connections.
Notes for IrDA Sockets
The Af_irda.h header file must be explicitly included.
For more inforamtion about IrDA support in Windows Embedded CE, see Infrared Communications.
Notes for Bluetooth
An RFCOMM Winsock server calls listen to put RFCOMM into a mode in which it will accept connections on the channel. The backlog value for RFCOMM would be 0. Calling listen does not advertise the service in the SDP database.
Compatibility
The backlog parameter is limited (silently) to a reasonable value as determined by the underlying 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 | winsock2.h |
| Library | Ws2.lib |
| Windows Embedded CE | Windows CE 1.0 and later |
See Also
Reference
accept (Windows Sockets)
bind (Windows Sockets)
connect (Windows Sockets)
socket (Windows Sockets)
WSAGetLastError
WSAStartup