Microsoft Windows CE 3.0  

listen

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.

This function prepares a socket to listen for incoming connections.

int
listen
(
SOCKET
s
,
int
backlog
);

Parameters

s
[in] Descriptor that identifies a bound, unconnected socket.
backlog
[in] Maximum length of the queue of pending connections. If this value is SOMAXCONN, then the underlying service provider responsible for socket swill set the backlog to a maximum reasonable value. There is no standard provision to find out the actual backlog value.

Return Values

Zero indicates success. SOCKET_ERROR indicates failure. To get a specific error value, call WSAGetLastError.

As in 4.3BSD, illegal values (less than 1 or greater than 5) are replaced by the nearest valid value.

Remarks

For Infrared Sockets (IrSock), this function has the following additional requirements and behaviors:

  • The Af_irda.h file must be explicitly included.
  • The WSAENETDOWN return value is not supported.
  • The backlogparameter is currently limited (silently) to 2.

    To accept connections, a socket is first created with the socketfunction and bound to a local address with the bindfunction, a backlog for incoming connections is specified with listen, and then the connections are accepted with the acceptfunction. Sockets that are connection oriented, those of type SOCK_STREAM for example, are used with listen. The socket sis put into "passive'' mode where incoming connection requests are acknowledged and queued pending acceptance by the process.

    The listenfunction 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, listenattempts to continue to function. If descriptors become available, a later call to listenor acceptwill refill the queue to the current or most recent "backlog'', if possible, and resume listening for incoming connections.

    An application can call listenmore 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.

    Requirements

    Runs on Versions Defined in Include Link to
    Windows CE OS 1.0 and later Winsock.h    
    Note   This API is part of the complete Windows CE OS package as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM) and some devices may not support this API.

    See Also

    accept, bind, connect, socket, WSAStartup