| |
| SOCKET Listen( |
| |
LPCTSTR lpszLocalAddress, |
|
| |
UINT nLocalPort, |
|
| |
UINT nBacklog, |
|
| |
DWORD dwOptions |
|
| ); |
The Listen method creates a listening socket and specifies
the maximum number of connection requests that will be queued.
This method has been deprecated and is included for
backwards compatibility. Use the CInternetServer
class to create a server application.
Parameters
- lpszLocalAddress
- A null-terminated string which specifies the local
IP address that the socket should be bound to. If this parameter is
NULL or points to an empty string, a client may establish a
connection using any valid network interface configured on the
local system. If an address is specified, then a client may only
establish a connection with the system using that address.
- nLocalPort
- The local port number that the socket should be bound to. This
value must be greater than zero.
Port numbers less than 1024 are considered reserved ports and may
require that the process execute with administrative privileges
and/or require changes to the default firewall rules to permit
inbound connections.
- nBacklog
- The maximum length of queue of pending connections. On Windows
workstations, the maximum backlog value is 5. On Windows servers,
the maximum value is 200.
- dwOptions
- An unsigned integer used to specify one or more socket
options. The following values are recognized:
| Value |
Description |
| INET_OPTION_NONE |
No option specified. If the address and port number are in
use by another application or a closed socket which was
listening on this port is still in the TIME_WAIT state, the
function will fail. |
| INET_OPTION_REUSEADDRESS |
This option enables a server application to listen for
connections using the specified address and port number even if
they were in use recently. This is typically used to enable an
application to close the listening socket and immediately reopen
it without getting an error that the address is in use. |
| INET_OPTION_EXCLUSIVE |
This option specifies the local address and port number
is for the exclusive use by the current process, preventing
another application from forcibly binding to the same address.
If another process has already bound a socket to the address
provided by the caller, this function will fail. |
| INET_OPTION_NOINHERIT |
This option prevents the socket handle from being inherited
by child processes created by the application. Using this option
can mitigate situations in which a child process does not close
the handle, leaving it open after the parent process has
disconnected from the server. |
Return Value
If the method succeeds, the return value is a handle to the
socket. If the method fails, the return value is INVALID_SOCKET. To
get extended error information, call GetLastError.
Remarks
To listen for connections on any suitable IPv4 interface, specify
the special dotted-quad address "0.0.0.0". You can accept
connections from clients using either IPv4 or IPv6 on the same socket by
specifying the special IPv6 address "::0", however this is only
supported on Windows 7 and Windows Server 2008 R2 or later platforms. If
no local address is specified, then the server will only listen for
connections from clients using IPv4. This behavior is by design for
backwards compatibility with systems that do not have an IPv6 TCP/IP
stack installed.
If the INET_OPTION_REUSEADDRESS option is not specified, an error may
be returned if a listening socket was recently created for the same
local address and port number. By default, once a listening socket is
closed there is a period of time that all applications must wait
before the address can be reused (this is called the TIME_WAIT
state). The actual amount of time depends on the operating system and
configuration parameters, but is typically two to four minutes.
Specifying this option enables an application to immediately re-use a
local address and port number that was previously in use. Note that
this does not permit more than one server to bind to the same
address.
If the INET_OPTION_EXCLUSIVE option is specified, the local address
and port number cannot be used by another process until the listening
socket is closed. This can prevent another application from forcibly
binding to the same listening address as your server. This option can
be useful in determining whether or not another process is already
bound to the address you wish to use, but it may also prevent your
server application from restarting immediately, regardless if the
INET_OPTION_REUSEADDRESS option has also been specified.
If an IPv6 address is specified as the local address, the system
must have an IPv6 stack installed and configured, otherwise the
method will fail.
Requirements
Minimum Desktop Platform: Windows 7 Service Pack 1
Minimum Server Platform: Windows Server 2008 R2 Service Pack 1
Header File: cswsock11.h
Import Library: cswskv11.lib
Unicode: Implemented as Unicode and ANSI versions
See Also
Accept,
DisableEvents,
EnableEvents,
Reject
|
|