SOCKET WINAPI InetListen(
	LPCTSTR lpszLocalAddress,
	UINT nLocalPort
);

The InetListen function creates a passive socket used to listen for connections from a client application.

Parameters

lpszLocalAddress

A pointer to 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.

Return Value

If the function succeeds, the return value is a socket handle. If the function fails, the return value is INVALID_SOCKET. To get extended error information, call InetGetLastError.

Remarks

In most cases, the dwAddress parameter should be specified with a value of zero. On a multi-homed system, this will enable the server to accept connections on any appropriately configured network adapter. If you wish to restrict inbound connections to a specific IP address, use the InetGetAddress function to convert an address string in dotted notation to an integer value suitable for this parameter.

The socket option INET_OPTION_REUSEADDR is enabled by default when calling the InetListen function. This allows an application to re-use a local address and port number when creating the listening socket. If this behavior is not desired, use the InetListenEx function instead.

If an IPv6 address is specified as the local address, the system must have an IPv6 stack installed and configured, otherwise the function will fail.

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 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.

After the listening socket has been created, the application should then call the InetAccept function to wait for a client to establish a connection. For servers that need to handle multiple simultaneous client connections, it is recommended that the asynchronous functions be used.

To enable asynchronous event notification, use the InetEnableEvents function.

Example

SOCKET hServer = INVALID_SOCKET;
LPCTSTR lpszAddress = "192.168.0.48";

// Accept connections from clients that connect to
// address 192.168.0.48 on port 7000

hServer = InetListen(lpszAddress, 7000);
if (hServer == INVALID_SOCKET)
{
    DWORD dwError;
    TCHAR szError[256];

    dwError = InetGetLastError();
    InetGetErrorString(dwError, szError, 256);

    MessageBox(NULL, szError, NULL, MB_OK|MB_TASKMODAL);
    return;
}

Requirements

Client: Requires Windows 7, Windows Vista or Windows XP.
Server: Requires Windows Server 2008 or Windows Server 2003.
Header: Include cswsock7.h.
Library: Use cswskav7.lib.

See Also

InetAccept, InetAsyncAccept, InetAsyncListen, InetGetAddress, InetEnableEvents, InetInitialize, InetListenEx, InetReject

Copyright © 2012 Catalyst Development Corporation. All rights reserved.