Winsock API

Overview

Winsock allows applications to communicate over a network using socket descriptors. These descriptors are similar to file handles and are used to represent network connections.

Key concepts in Winsock include:

• Sockets: An endpoint for communication.
• Protocols: Such as TCP (Transmission Control Protocol) for reliable, connection-oriented communication, and UDP (User Datagram Protocol) for faster, connectionless communication.
• Address Families: Specifies the protocol family (e.g., AF_INET for IPv4).
• Socket Types: Defines the communication semantics (e.g., SOCK_STREAM for TCP, SOCK_DGRAM for UDP).

Core Functions

The Winsock API provides a rich set of functions for network programming. Here are some of the most fundamental ones:

• WSAStartup
• WSACleanup
• socket
• bind
• listen
• accept
• connect
• send
• recv
• closesocket

Key Function Details

WSAStartup

Initializes the Winsock DLL. This function must be called before any other Winsock functions can be used.

int WSAStartup(
  WORD                 wVersionRequired,
  LPWSADATA            lpWSAData
);

• wVersionRequired: The highest version of the Winsock API that the calling application can use.
• lpWSAData: A pointer to a WSADATA structure that receives details about the Winsock implementation.

WSACleanup

Terminates the use of the Winsock DLL. This function is called to clean up resources used by Winsock.

int WSACleanup();

socket

Creates a socket that is used to listen for incoming connection requests or to connect to a remote host.

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

• af: The address family (e.g., AF_INET for IPv4).
• type: The socket type (e.g., SOCK_STREAM for stream sockets, SOCK_DGRAM for datagram sockets).
• protocol: The protocol to be used (e.g., IPPROTO_TCP, IPPROTO_UDP).

bind

Associates a local address with a socket.

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

• s: The socket descriptor.
• name: A pointer to a sockaddr structure specifying the local address and port.
• namelen: The length of the address structure.

listen

Places a socket in a state where it can passively accept incoming connection requests.

int listen(
  SOCKET s,
  int    backlog
);

• s: The socket descriptor.
• backlog: The maximum length of the queue of pending connections.

accept

Accepts a connection from a remote host on a listening socket.

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

• s: The listening socket descriptor.
• addr: A pointer to a sockaddr structure that will receive the address of the connecting client.
• addrlen: A pointer to the size of the address structure.

connect

Establishes a connection to a remote socket.

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

• s: The socket descriptor.
• name: A pointer to a sockaddr structure specifying the remote address and port.
• namelen: The length of the address structure.

send

Sends data on a connected socket or an unconnected socket.

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

• s: The socket descriptor.
• buf: A pointer to a buffer containing the data to be sent.
• len: The number of bytes to send.
• flags: Options for sending data.

recv

Receives data from a connected socket or an unconnected socket.

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

• s: The socket descriptor.
• buf: A pointer to a buffer that will receive the data.
• len: The maximum number of bytes to receive.
• flags: Options for receiving data.

closesocket

Closes an existing socket.

int closesocket(
  SOCKET s
);

• s: The socket descriptor to close.

Error Handling

Winsock functions return specific error codes upon failure. The WSAGetLastError() function retrieves the most recent error code.

int errorCode = WSAGetLastError();

Common error codes include:

• WSAEINTR: A blocking operation was interrupted.
• WSAECONNRESET: Connection reset by peer.
• WSAETIMEDOUT: Connection timed out.
• WSAENOTCONN: Socket is not connected.