Windows Sockets API Reference

This section provides detailed reference information for the Windows Sockets API (Winsock), which enables applications to create network-aware programs using a standard socket interface.

Core Socket Functions

`socket()`

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

Syntax

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

Parameters

Name	Description
`af`	The address family (e.g., AF_INET for IPv4, AF_INET6 for IPv6).
`type`	The socket type (e.g., SOCK_STREAM for a reliable, connection-oriented socket, SOCK_DGRAM for a connectionless datagram socket).
`protocol`	The protocol to be used (usually 0 to let the system choose the default protocol for the specified address family and socket type).

Return Value

If no error occurs, socket returns a descriptor for the newly created socket. Otherwise, it returns INVALID_SOCKET, and a specific error code can be retrieved by calling WSAGetLastError.

`bind()`

Associates a local address with a socket.

Syntax

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

Parameters

Name	Description
`s`	Descriptor identifying the unbound socket.
`name`	Pointer to a socket address structure that specifies the address and port to assign to the bound socket.
`namelen`	Length of the socket address 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.

`connect()`

Establishes a connection to a specified remote socket.

Syntax

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

Parameters

Name	Description
`s`	Socket descriptor that identifies an unbound socket.
`name`	Pointer to a socket address structure that specifies the remote address and port to which this socket is to be connected.
`namelen`	Length of the socket address structure.

Return Value

If no error occurs, connect returns zero. For a nonblocking socket, a return value of EINPROGRESS indicates that the connection is in progress. Otherwise, it returns SOCKET_ERROR, and a specific error code can be retrieved by calling WSAGetLastError.

`send()`

Sends data on a connected socket.

Syntax

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

Parameters

Name	Description
`s`	Socket descriptor that identifies a connected socket.
`buf`	Pointer to a buffer containing the data to be sent.
`len`	Number of bytes to send from the buffer pointed to by `buf`.
`flags`	Flags used to specify how data is sent.

Return Value

If no error occurs, send returns the total number of bytes sent, which may be less than the number specified by len. If a socket is not connected, send returns SOCKET_ERROR and WSAGetLastError returns WSAENOTCONN. If an error occurs, send returns SOCKET_ERROR, and a specific error code can be retrieved by calling WSAGetLastError.

`recv()`

Receives data from a connected socket.

Syntax

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

Parameters

Name	Description
`s`	Socket descriptor that identifies a connected socket.
`buf`	Buffer to receive incoming data.
`len`	Maximum number of bytes to receive.
`flags`	Flags that can be used to modify the behavior of the receive operation.

Return Value

If no error occurs, recv returns the number of bytes received, which may be less than the number requested. If the calling process has no incoming data at this time, the return value is zero. If a socket is datagram-oriented, and the data is of a size larger than the buffer specified by len, recv will return only the contents of the buffer. If no data is received, the connection has been closed, or an error occurs, recv returns SOCKET_ERROR, and a specific error code can be retrieved by calling WSAGetLastError.

`closesocket()`

Closes an existing socket.

Syntax

int closesocket(SOCKET s);

Parameters

Name	Description
`s`	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.

Key Socket Structures

`sockaddr`

The sockaddr structure is a generic socket address structure used by various socket functions.

Definition

                            
                                struct sockaddr {

                                    u_short sa_family;             // Address family

                                    char    sa_data[14];           // Up to 14 bytes of direct socket address data

                                };

For specific address families, more specialized structures like sockaddr_in (for IPv4) and sockaddr_in6 (for IPv6) are used.

`sockaddr_in`

The sockaddr_in structure specifies an IPv4 socket address.

Definition

                            
                                struct sockaddr_in {

                                    short int          sin_family;  // AF_INET

                                    unsigned short int sin_port;    // Port number

                                    struct in_addr     sin_addr;    // IP address

                                    char               sin_zero[8]; // Not used

                                };

Important Constants

Address Families

                            
                                #define AF_INET     2  // IPv4

                                #define AF_INET6    23 // IPv6

                                #define AF_UNSPEC   0  // Unspecified address family

Socket Types

                            
                                #define SOCK_STREAM     1  // Sequenced, reliable, two-way, connection-based byte streams.

                                #define SOCK_DGRAM      2  // Datagrams (connectionless, unreliable messages of fixed maximum length).

Socket States/Errors

                            
                                #define INVALID_SOCKET  (SOCKET)(~0)

                                #define SOCKET_ERROR    (-1)