Windows Sockets 2 API Reference

This section provides detailed documentation for the Windows Sockets 2 API, a robust and flexible networking API for Windows operating systems.

Introduction to Winsock

Winsock (Windows Sockets API) provides a standard interface for network programming. Winsock 2 extends the original Winsock specification with features like Quality of Service (QoS) support, protocol-independent naming, and multithreaded capabilities.

Core Concepts

Sockets and Socket Types
Address Families (AF_INET, AF_INET6)
Protocols (TCP, UDP)
Data Structures (SOCKADDR, WSABUF)
Error Handling

Commonly Used Functions

The following are some of the most frequently used functions within the Winsock 2 API:

`socket()`

Creates a socket that is bound to a specific transport service provider.

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

af: The address family specification. Use AF_INET or AF_INET6.
type: The socket type specification. Use SOCK_STREAM for TCP or SOCK_DGRAM for UDP.
protocol: The protocol to be used with the socket. Usually 0 to let the system choose the default.

Return Value: If no error occurs, socket() returns a descriptor for the newly created socket. Otherwise, a value of INVALID_SOCKET is returned, and a specific error code can be retrieved by calling WSAGetLastError().

`bind()`

Associates a local name (address and port) with a socket.

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

s: Descriptor identifying an unbound socket.
name: Pointer to a sockaddr structure that specifies the address and port to assign to the socket.
namelen: Length, in bytes, of the name structure.

Return Value: If no error occurs, bind() returns zero. Otherwise, a value of SOCKET_ERROR is returned, and a specific error code can be retrieved by calling WSAGetLastError().

`connect()`

Establishes a connection to a remote socket.

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

s: Descriptor identifying an unconnected socket.
name: Pointer to a sockaddr structure that contains the remote address and port to which this socket will be connected.
namelen: Length, in bytes, of the name structure.

Return Value: If no error occurs, connect() returns zero. For non-blocking sockets, a return value of WSAEINPROGRESS indicates that the connection is in progress. Otherwise, a value of SOCKET_ERROR is returned, and a specific error code can be retrieved by calling WSAGetLastError().

`send()`

Sends data on a connected socket.

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

s: Descriptor identifying a connected socket.
buf: Pointer to a buffer containing the data to be transmitted.
len: The number of bytes to send from the buffer.
flags: Flags that influence the transmission.

Return Value: If no error occurs, send() returns the number of bytes sent. Otherwise, a value of SOCKET_ERROR is returned, and a specific error code can be retrieved by calling WSAGetLastError().

`recv()`

Receives data from a connected socket.

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

s: Descriptor identifying a connected socket.
buf: Pointer to the buffer that will receive the incoming data.
len: The maximum number of bytes to receive.
flags: Flags that influence the reception.

Return Value: If no error occurs, recv() returns the number of bytes received. If the connection has been gracefully closed, the return value is zero. Otherwise, a value of SOCKET_ERROR is returned, and a specific error code can be retrieved by calling WSAGetLastError().

Other Important Functions and Features

listen(): Marks a socket as listening for incoming connections.
accept(): Accepts a connection on a socket.
gethostname(): Retrieves the standard hostname for the local computer.
getaddrinfo(): Protocol-independent address resolution.
getnameinfo(): Protocol-independent name resolution.
WSAStartup(): Initializes the Winsock library.
WSACleanup(): Terminates the use of the Winsock library.
Quality of Service (QoS) features
Layered Service Providers (LSPs)

Note: Always call WSAStartup() before using any other Winsock functions and WSACleanup() when you are finished.

Important: Error codes returned by Winsock functions are specific and should be interpreted using WSAGetLastError().

Microsoft Docs