WSAConnectByName() and WSAConnectByList()

G’Day, my name is Brad Williamson, a Software Design Engineer with the Windows Networking Developer Platform (WNDP) group here at Microsoft. I am going to talk about two APIs that were introduced in Windows Vista Beta 2 to simplify the process of connecting to another connection-oriented socket application.

By far, one of the most common scenarios in sockets programming is to connect to a remote address after resolving the hostname. To do this, you first call getaddrinfo() to resolve a hostname. Then, for each address, you create a socket, bind to that socket, and call connect(),WSAConnect(), or ConnectEx(). This process continues until the connection succeeds or the address list has been exhausted. With IPv6 becoming more prevalent, the address list that you have to traverse will be large.

Furthermore, if you have a machine with multiple interfaces (whether that be multiple NICs and/or multiple IP addresses on the same NIC), you may want to determine which interface best suits the destination address, and then bind appropriately.

As you will agree, the process of connecting optimally to a destination connection-oriented socket requires a lot of code.

With Windows Vista, this process is simplified with the introduction of two new Winsock APIs: WSAConnectByName() and WSAConnectByList().

WSAConnectByName() establishes a connection to another application, using an optimal source and destination address pair, given a specified socket, host and port. Given a socket s, host name and port (or a well known service name); WSAConnectByName() will connect to the destination. If successful, WSAConnectByName() will return the local address which socket s is bound to, and the remote address connected to.

LPSTR nodename,
LPSTR servicename,
LPDWORD LocalAddressLength,
LPSOCKADDR LocalAddress,
LPDWORD RemoteAddressLength,
LPSOCKADDR RemoteAddress,
const struct timeval* timeout,
In addition to WSAConnectByName(), we have introduced WSAConnectByList() which establishes a connection to one of the addresses specified in the SocketAddressList structure.
LPDWORD LocalAddressLength,
LPSOCKADDR LocalAddress,
LPDWORD RemoteAddressLength,
LPSOCKADDR RemoteAddress,
const struct timeval* timeout,

By using WSAConnectByName() and WSAConnectByList():

  1. For WSAConnectByName(), your application is transparent to the name resolution. The list of remote addresses that we attempt to connect to is determined by the socket type passed in. This also includes dual-mode sockets (supporting IPv4 and IPv6) where the socket option IPV6_V6ONLY has been set to FALSE.
  2. Your application does not have to optimize the address list to determine which interface you should bind to.
  3. Eliminates the need for your application to include code to minimize the time of the connecting.
Having said this, here are two caveats to using these APIs:

  1. Connection-oriented mode is only supported, and
  2. Overlapped I/O is not supported. These APIs will block even if the socket is in non-blocking mode. Update: We will support Overlapped I/O in a future release.

More information about these new APIs can be found in:


So, when writing your next Winsock based application using Windows Vista, be sure to try out WSAConnectByName() and WSAConnectByList(). Please let us know if you have any questions, comments or suggestions.

–Brad Williamson

Comments (7)

  1. denis bider says:

    What’s that about these APIs not supporting overlapped I/O? That makes these otherwise very promising APIs totally useless for asynchronous applications – implying most professionally written applications. 🙁

  2. Hi Denis,

    Thanks for your feedback.  In a future version of the OS, we will support overlapped I/O for both WSAConnectByName() and WSAConnectByList().


    –Brad Williamson

  3. Skywing says:

    Lack of overlapped I/O is a showstopper for me using these APIs.

  4. Skywing says:

    Lack of overlapped I/O is a showstopper for me even considering using these in my applications – these APIs are "dead on arrival" as far as I am concerned unfortunately.

  5. Nigel Horne says:

    I get winsock related link errors, what .lib do I need to link with?

  6. Hi,

    You need to link with ws2_32.lib which is included in the new Windows Vista PSDK, available at:



  7. Neil says:

    Can I get you to turn back the page a decade.  I have an application that communicates UDP using "winsock.h" in VC6.

    We are noticing recent communication headaches.  I have a therory about the cause.  Other programs that communicate are newer and are using "ws2_32".  Under heavy traffic our application starts to really suffer.

    I think the partner applications, using ws2_32, are causing our winsock application to be at the end of line.  Until recently Win98 was a supported platform.  Reliability is crucial, so any help to solve this is appreciated.

    I would greatly appreciate any suggestions