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

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 Vista, Windows XP or Windows 2000 Professional.
Server: Requires Windows Server 2008, Windows Server 2003 or Windows 2000 Server.
Header: Include cswsock6.h.
Library: Use cswskav6.lib.

See Also

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

Copyright © 2008 Catalyst Development Corporation. All rights reserved.