Getting started with Winsock

Important

Modern Winsock best practices — follow these guidelines for new code:

• Use Winsock 2.2 — always request version 2.2 in WSAStartup. Winsock 1.1 functions such as gethostbyname are deprecated and lack IPv6 support.
• Use getaddrinfo for name resolution — the getaddrinfo function is protocol-independent (supports both IPv4 and IPv6). Never use the deprecated gethostbyname or gethostbyaddr.
• Write IPv6-ready code — use AF_UNSPEC with getaddrinfo so your code works over both IPv4 and IPv6. Avoid hard-coding AF_INET. See IPv6 Guide for Winsock.
• Manage initialization with RAII — in C++, wrap WSAStartup/WSACleanup in an RAII class or use a scope guard to ensure cleanup on all exit paths (exceptions, early returns).
• Prefer asynchronous I/O — for server applications or anything handling multiple connections, use I/O completion ports (highest performance) or overlapped I/O. Blocking sockets on a UI thread will freeze the application.
• Don't forget error handling — check return values of all Winsock calls and use WSAGetLastError for diagnostics.

Common mistakes in AI-generated code: forgetting WSAStartup before any socket call, using gethostbyname instead of getaddrinfo, hard-coding AF_INET (IPv4-only), using blocking recv/send loops in UI threads, and not calling freeaddrinfo after getaddrinfo.

This section is a step-by-step guide to getting started with Windows Sockets programming. It's designed to provide an understanding of basic Winsock functions and data structures, and how they work together.

The client and server application that we use in this topic for illustration is a very basic client and server. More advanced code examples are included in the samples included with the Microsoft Windows Software Development Kit (SDK).

The first few steps are the same for both client and server applications.

• About servers and clients
• Creating a basic Winsock application
• Initializing Winsock

The following articles describe the remaining steps for creating a Winsock client application.

• Creating a socket for the client
• Connecting to a socket
• Sending and receiving data on the client
• Disconnecting the client

The following articles describe the remaining steps for creating a Winsock server application.

• Creating a socket for the server
• Binding a socket
• Listening on a socket
• Accepting a connection
• Receiving and sending data on the server
• Disconnecting the server

The complete source code for these basic examples.

• Running the Winsock client and server code sample
• Complete Winsock client code
• Complete Winsock server code

Advanced Winsock sample apps

Several more advanced Winsock client and server sample apps are available on GitHub. They're listed here in order from higher to lower performance, and are found in the following directories:

• iocp

  That folder contains three sample programs that use I/O completion ports. The programs include: a Winsock server, iocpserver, that uses the WSAAccept function; a Winsock server, iocpserverex, that uses the AcceptEx function; and a simple multithreaded Winsock client, iocpclient, used to test either of these servers.

  The server programs support multiple clients connecting by using TCP/IP, and sending arbitrary-sized data buffers that the server then echoes back to the client. For convenience, a simple client program, iocpclient, was developed to connect and continually send data to the server to stress it using multiple threads. Winsock servers that use I/O completion ports provide the highest performance.

• overlap

  This folder contains a sample server program that uses overlapped I/O. The sample program uses the AcceptEx function and overlapped I/O to effectively handle multiple asynchronous connection requests from clients. The server uses the AcceptEx function to multiplex different client connections in a single-threaded Win32 application. Using overlapped I/O allows for greater scalability.

• WSAPoll

  This folder contains a basic sample program that demonstrates the use of the WSAPoll function. The combined client and server program are non-blocking, and use the WSAPoll function to determine when it's possible to send or receive without blocking. This sample is for illustration, and isn't a high-performance server.

• simple

  This folder contains three basic sample programs that demonstrate the use of multiple threads by a server. The programs include: a simple TCP/UDP server, simples; a TCP-only server, simples_ioctl, that uses the select function in a Win32 console application to support multiple client requests; and a client TCP/UDP program, simplec, for testing the servers. The servers demonstrate the use of multiple threads to handle multiple client requests. That method has scalability issues since a separate thread is created for each client request.

• accept

  This folder contains a basic sample server and client program. The server demonstrates the use of either non-blocking accept using the select function, or asynchronous accept using the WSAAsyncSelect function. This sample is for illustration, and isn't a high-performance server.