Home > Windows > API Reference > Networking > Winsock API Reference

Winsock API Reference

Welcome to the comprehensive API reference for the Windows Sockets (Winsock) interface. Winsock provides a standard interface for network programming on Windows platforms.

This reference covers the functions, structures, constants, and error codes that are essential for developing network-aware applications using TCP/IP, UDP, and other network protocols.

Key Concepts

Winsock enables applications to:

Featured Functions

socket Function

SOCKET socket(INT af, INT type, INT protocol);

Creates a socket that can be used for inter-process communication.

Parameters

  • af: The address family (e.g., AF_INET for IPv4).
  • type: The socket type (e.g., SOCK_STREAM for TCP, SOCK_DGRAM for UDP).
  • protocol: The protocol to use (often 0 to let the system choose based on type).

Return Value

If no error occurs, socket returns a descriptor for the newly created socket. This descriptor is a small integer used in subsequent function calls to refer to this socket. If an error occurs, socket returns INVALID_SOCKET. To get extended error information, call WSAGetLastError.

bind Function

int bind(SOCKET s, const struct sockaddr *name, int namelen);

Associates a local address with a socket. For server applications, this is typically used to bind to a specific IP address and port number.

Parameters

  • s: A descriptor identifying an unbound socket.
  • name: A pointer to a buffer containing the socket address structure for the local binding.
  • namelen: The length, in bytes, of the structure pointed to by the name parameter.

Return Value

If no error occurs, bind returns zero. Otherwise, it returns SOCKET_ERROR, and a specific error code can be retrieved by calling WSAGetLastError.

listen Function

int listen(SOCKET s, int backlog);

Puts a socket into a listening state, preparing it to accept incoming connection requests. This function is typically called on a server socket after the bind function.

Parameters

  • s: A descriptor identifying an unbound socket.
  • backlog: The maximum length of the queue of pending connections.

Return Value

If no error occurs, listen returns zero. Otherwise, it returns SOCKET_ERROR, and a specific error code can be retrieved by calling WSAGetLastError.

accept Function

SOCKET accept(SOCKET s, struct sockaddr *addr, LPINT addrlen);

Extracts the first connection request from the queue of pending connections on a socket and creates a new socket that represents the connection. The original socket s continues to listen for additional connections.

Parameters

  • s: A descriptor identifying a socket that is in a listening state.
  • addr: An optional pointer to a buffer that receives the address of the connecting entity.
  • addrlen: An optional pointer to a parameter that specifies the size, in bytes, of the buffer pointed to by the addr parameter.

Return Value

If no error occurs, accept returns a descriptor for the newly created socket. This descriptor is used to communicate with the client. Otherwise, accept returns INVALID_SOCKET, and a specific error code can be retrieved by calling WSAGetLastError.

connect Function

int connect(SOCKET s, const struct sockaddr *name, int namelen);

Establishes a connection to a specified remote host and port for a socket. For connection-oriented protocols like TCP, this function is used by clients to initiate communication with a server.

Parameters

  • s: A descriptor identifying an unconnected socket.
  • name: A pointer to a buffer containing the socket address structure for the remote host.
  • namelen: The length, in bytes, of the structure pointed to by the name parameter.

Return Value

If the connection is immediately successful, connect returns zero. If the socket is nonblocking and the connection cannot be established immediately, it returns SOCKET_ERROR and WSAGetLastError returns WSAEINPROGRESS. If the socket is blocking and the connection cannot be established immediately, it returns SOCKET_ERROR and WSAGetLastError returns an appropriate error code. If the socket is blocking and the connection fails, it returns SOCKET_ERROR, and WSAGetLastError returns the specific error code.

send Function

int send(SOCKET s, const char *buf, int len, int flags);

Sends data on a socket. The send function can be used with either connection-oriented or connectionless sockets.

Parameters

  • s: A descriptor identifying the socket.
  • buf: A pointer to a buffer containing the data to be transmitted.
  • len: The number of bytes to send from the buffer.
  • flags: Flags that can be used to influence the behavior of the send operation.

Return Value

If no error occurs, send returns the total number of bytes sent, which may be less than the number of bytes requested. If the socket is in nonblocking mode and the requested send cannot be completed immediately, send returns SOCKET_ERROR and WSAGetLastError returns WSAEWOULDBLOCK. Otherwise, send returns SOCKET_ERROR, and a specific error code can be retrieved by calling WSAGetLastError.

recv Function

int recv(SOCKET s, char *buf, int len, int flags);

Receives data from a connected socket or a bound connectionless socket. The recv function is used to read data from a socket.

Parameters

  • s: A descriptor identifying the socket.
  • buf: A pointer to the buffer that will receive the incoming data.
  • len: The size, in bytes, of the buffer pointed to by the buf parameter.
  • flags: Flags that can be used to influence the behavior of the receive operation.

Return Value

If no error occurs, recv returns the number of bytes received, which can be less than the number of bytes requested. If the calling process has issued a blocking IOCTL_WINSOCK_SET_NONBLOCKING call for the socket and the receive operation would block, recv returns SOCKET_ERROR and WSAGetLastError returns WSAEWOULDBLOCK. If the socket has been gracefully closed, the return value is zero. Otherwise, recv returns SOCKET_ERROR, and a specific error code can be retrieved by calling WSAGetLastError.

closesocket Function

int closesocket(SOCKET s);

Closes an existing socket. This function is used to release the resources associated with a socket.

Parameters

  • s: A descriptor identifying the socket to be closed.

Return Value

If no error occurs, closesocket returns zero. Otherwise, it returns SOCKET_ERROR, and a specific error code can be retrieved by calling WSAGetLastError.

WS2_32.DLL

The primary DLL for Winsock programming is WS2_32.DLL. You must explicitly link to this DLL or dynamically load its functions.

// Example of linking (C/C++):
            #pragma comment(lib, "ws2_32.lib")

            // Example of initializing Winsock:
            WSADATA wsaData;
            int iResult = WSAStartup(MAKEWORD(2, 2), &wsaData);
            if (iResult != 0) {
                printf("WSAStartup failed: %d\n", iResult);
                return 1;
            }

            // ... socket operations ...

            WSACleanup();

ioctlsocket Function

int ioctlsocket(SOCKET s, long cmd, u_long *argp);

Controls the mode of a socket's underlying network service.

Parameters

  • s: A descriptor identifying the socket.
  • cmd: The control command to perform. Common commands include FIONBIO for non-blocking mode.
  • argp: A pointer to the argument for the command. For FIONBIO, a non-zero value enables non-blocking mode, and zero disables it.

Return Value

If no error occurs, ioctlsocket returns zero. Otherwise, it returns SOCKET_ERROR, and a specific error code can be retrieved by calling WSAGetLastError.

getaddrinfo Function

INT getaddrinfo(PCSTR pServiceName, PCSTR pHostName, const ADDRINFOA *pHints, PADDRINFOA *ppResult);

The getaddrinfo function is a modern, protocol-independent name resolution function that is used to translate a node name and a service name into a socket address structure.

Parameters

  • pServiceName: The service name or port number.
  • pHostName: The host name or IP address.
  • pHints: A pointer to an ADDRINFOA structure that specifies criteria for the returned address structures.
  • ppResult: A pointer to a pointer to a linked list of ADDRINFOA structures that contains a set of socket address structures and address family information suitable for use with the connect, bind, or sendto function.

Return Value

If the function succeeds, it returns zero. If the function fails, the return value is a nonzero error code as defined in Winsock2.h. For IPv4, the error code WSAHOST_NOT_FOUND indicates that the name does not have a valid IP address. For IPv6, the error code WSAHOST_NOT_FOUND indicates that the name does not have a valid IPv6 address.

Remarks

It is recommended to use getaddrinfo and freeaddrinfo for new applications instead of the older Winsock 1.1 functions like gethostbyname and gethostbyaddr.

© 2023 Microsoft Corporation. All rights reserved.