Microsoft Docs

Winsock API Reference

This section provides detailed documentation for the Windows Sockets API (Winsock), a programming interface that allows applications to communicate over a network. Winsock is Microsoft's implementation of the Berkeley Sockets API, providing a standardized way for Windows applications to access network services.

Introduction

The Windows Sockets API (Winsock) is a set of C language functions that enable Windows-based applications to communicate over a network. It supports both TCP/IP and other networking protocols. Winsock is essential for developing network-aware applications, including web servers, clients, email programs, and more.

Core Concepts

• Sockets: An endpoint for communication, represented by a socket descriptor (an integer handle).
• Address Families: Specifies the network protocol family (e.g., AF_INET for IPv4, AF_INET6 for IPv6).
• Socket Types: Defines the communication semantics (e.g., SOCK_STREAM for connection-oriented, SOCK_DGRAM for connectionless).
• Protocols: The specific protocol to use within an address family and socket type (e.g., IPPROTO_TCP, IPPROTO_UDP).
• Ports: A numerical identifier used in conjunction with an IP address to distinguish between different processes on a host.
• IP Addresses: Unique identifiers for devices on a network.

Functions

The Winsock API includes a comprehensive set of functions for network programming. These functions can be categorized as follows:

Address Resolution

• getaddrinfo: Resolves a node name and service name to a set of socket address structures.
• freeaddrinfo: Frees address information returned by getaddrinfo.
• gethostbyaddr: Retrieves host information by IP address.
• gethostbyname: Retrieves host information by name.
• getservbyname: Retrieves service information by name.
• getservbyport: Retrieves service information by port number.

Connection-Oriented Protocols (e.g., TCP)

• socket: Creates a socket.
• bind: Associates a local address and port with a socket.
• listen: Places a socket in a listening state for incoming connection requests.
• accept: Accepts an incoming connection request on a listening socket.
• connect: Establishes a connection to a remote socket.
• send: Sends data on a connected socket.
• recv: Receives data from a connected socket.
• sendto: Sends data to a specific address.
• recvfrom: Receives data from a specific address.
• disconnect: Gracefully closes a connection.

Connectionless Protocols (e.g., UDP)

• socket: Creates a socket.
• bind: Associates a local address and port with a socket.
• sendto: Sends datagrams to a specified destination address.
• recvfrom: Receives datagrams from a specified source address.

Error Handling

• WSAGetLastError: Retrieves the last Windows Sockets error code.
• WSASetLastError: Sets the last Windows Sockets error code.

General Socket Operations

• closesocket: Closes an existing socket.
• ioctlsocket: Controls the I/O mode of a socket.
• setsockopt: Sets socket options.
• getsockopt: Retrieves socket options.
• getsockname: Retrieves the local name of a socket.
• getpeername: Retrieves the name of the remote peer.

I/O Multiplexing

• select: Monitors multiple socket descriptors for readiness.
• WSAEventSelect: Associates an event object with a socket for network events.
• WSAEnumNetworkEvents: Enumerates network events for a socket.

Network Management

• gethostname: Retrieves the standard host name.
• getdomainname: Retrieves the current domain name.

Protocol-Specific Controls

• WSAIoctl: Performs a range of control operations on sockets.

Security

• WSAStartup: Initializes the Winsock DLL.
• WSACleanup: Terminates the use of the Winsock DLL.

Service Providers

• WSAEnumProtocols: Enumerates the available protocols.

Transport Data Transfer

• sendmsg: Sends data using a message structure (extended).
• recvmsg: Receives data using a message structure (extended).

Structures

Key structures used in Winsock programming:

Constants

Important constants and macros used in Winsock:

• Address Family Constants: AF_UNSPEC, AF_INET, AF_INET6.
• Socket Type Constants: SOCK_STREAM, SOCK_DGRAM.
• Protocol Constants: IPPROTO_TCP, IPPROTO_UDP.
• Socket Option Constants: SO_BROADCAST, SO_REUSEADDR, SO_RCVTIMEO, SO_SNDTIMEO.
• INVALID_SOCKET: Value indicating an invalid socket handle.
• SOCKET_ERROR: General error return value.

Error Codes

Common Winsock error codes returned by WSAGetLastError:

• WSAEINTR: A blocking operation was interrupted.
• WSAENOTSOCK: An operation was attempted on something that is not a socket.
• WSAECONNRESET: Connection reset by peer.
• WSAETIMEDOUT: Connection timed out.
• WSAEWOULDBLOCK: Operation would block.
• WSAECONNABORTED: Software caused connection abort.
• WSAEADDRINUSE: Address already in use.

For a comprehensive list, refer to the Windows Sockets Error Codes page.

Tutorials and Samples

Explore practical examples and tutorials to learn how to use Winsock effectively:

• TCP Client Sample
• UDP Server Sample
• Getting Started with Winsock