Winsock API Reference

The Windows Sockets API (Winsock) is an application programming interface (API) for the Microsoft Windows Sockets protocol specification. Winsock provides access to the networking services available on a client or server machine. It supports both TCP/IP and IPX/SPX protocols, although TCP/IP is the most common protocol used with Winsock.

Getting Started

To use Winsock, you typically need to perform the following steps:

  1. Initialize the Winsock DLL using the WSAStartup function.
  2. Create a socket using the socket function.
  3. Establish a connection or bind to a port.
  4. Send and receive data using functions like send, recv, sendto, and recvfrom.
  5. Clean up resources using closesocket and call WSACleanup when done.

Core Functions

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

int WSAStartup(WORD wVersion, LPWSADATA lpWSAData);

wVersion
The Winsock version requested by the calling application.
lpWSAData
A pointer to a WSADATA structure that receives details about the Winsock implementation.

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 TCP, SOCK_DGRAM for UDP).
protocol
The protocol (usually 0 to let the system choose).

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

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

int listen(SOCKET s, int backlog);

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

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

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

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

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

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

s
The socket descriptor.
buf
A pointer to the buffer containing the data to be sent.
len
The number of bytes to send.
flags
Flags that control the behavior of the send operation.

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

s
The socket descriptor.
buf
A pointer to the buffer that will receive the data.
len
The maximum number of bytes to receive.
flags
Flags that control the behavior of the receive operation.

int closesocket(SOCKET s);

s
The socket descriptor to close.

int WSACleanup(void);

Deinitializes the Winsock DLL.

Data Types

Key data types used in Winsock include:

  • SOCKET: An opaque handle representing a socket.
  • SOCKADDR: A generic socket address structure.
  • SOCKADDR_IN: A specific structure for IPv4 addresses and ports.
  • WSADATA: Structure containing details about the Winsock implementation.
  • LPWSADATA: Pointer to a WSADATA structure.
  • LPSTR, LPCTSTR, etc.: Standard Windows string pointer types.

Structures

SOCKADDR_IN

Used to specify an IPv4 endpoint for a socket.

typedef struct sockaddr_in {
    short int sin_family;         // Address family (AF_INET)
    unsigned short int sin_port;  // Port number
    struct in_addr sin_addr;      // IP address
    char sin_zero[8];             // Reserved for padding
} SOCKADDR_IN, *PSOCKADDR_IN, *LPSOCKADDR_IN;

WSADATA

Contains information about the Winsock implementation.

typedef struct WSAData {
    WORD           wVersion;
    WORD           wHighVersion;
    char           szDescription[WSADESCRIPTION_LEN + 1];
    char           szSystemStatus[WSASYS_STATUS_LEN + 1];
    unsigned short iMaxSockets;
    unsigned short iMaxUdpDg;
    char FAR *     lpVendorInfo;
} WSADATA, *LPWSADATA;

Error Handling

Winsock functions return specific error codes on failure. The WSAGetLastError() function can be used to retrieve the most recent error code.

Common error codes include:

  • WSAEINTR: A blocking operation was interrupted by a call to WSACancelAsyncSelect or a blocking call was cancelled.
  • WSAECONNRESET: An established connection was aborted by the software on your host machine.
  • WSAETIMEDOUT: A connection attempt failed because the connected party did not respond after a period of time.
  • WSAEWOULDBLOCK: Nonblocking socket operation could not be completed immediately.

Advanced Topics

Refer to the respective sections for detailed information.