Windows API Reference

Networking / TCP/IP Services

TCP/IP Networking API

This section provides detailed documentation for the Windows Sockets API (Winsock), which allows applications to use network protocols for communication.

Socket Functions

Functions for creating, managing, and operating sockets.

Function Name Description
socket() Creates a socket that is bound to a specific transport service provider.
bind() Associates a local name (address and port) with a socket.
connect() Establishes a connection to a remote socket.
listen() Puts a socket into a listening state, preparing it to accept incoming connection requests.
accept() Accepts a connection made to a socket that is listening for connections.
send() Sends data on a connected socket.
recv() Receives data from a connected socket.
closesocket() Closes an existing socket.

Address Functions

Functions for manipulating network addresses and names.

Function Name Description
gethostname() Retrieves the standard host name for the current machine.
gethostbyname() Retrieves the address of a host from its name.
getaddrinfo() Provides protocol-independent translation of a host name and service name to a set of socket address structures.
inet_ntoa() Converts an Internet Protocol (IP) address from an Internet network format to a string.

Protocol Functions

Functions for querying and managing network protocols.

Function Name Description
getprotobyname() Retrieves protocol information from a protocol name.
getservbyname() Retrieves service information from a service name and protocol name.

I/O Control

Functions for performing I/O control operations on sockets.

Function Name Description
ioctlsocket() Changes the mode of a socket that is either blocking or non-blocking.
select() Monitors multiple socket descriptors for readiness for read, write, or exception conditions.

Configuration

APIs for network interface configuration and management.

Function Name Description
GetIfAddrs() Retrieves a list of network interface addresses. (Part of IP Helper API)
GetBestRoute() Retrieves the best route to a destination IP address. (Part of IP Helper API)

socket() Function

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


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

Parameters

  • af: The address family. Common values include AF_INET (IPv4) and AF_INET6 (IPv6).
  • type: The socket type. Common values include SOCK_STREAM (TCP) and SOCK_DGRAM (UDP).
  • protocol: The protocol to be used with the socket. Typically IPPROTO_TCP or IPPROTO_UDP.

Return Value

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

bind() Function

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


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

Parameters

  • s: A descriptor identifying an unbound socket.
  • name: A pointer to the socket address structure to which a connection is to be bound.
  • namelen: The length, in bytes, of the socket address structure pointed to by the name parameter.

Return Value

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

connect() Function

Establishes a connection to a remote socket.


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

Parameters

  • s: A descriptor identifying an unconnected socket.
  • name: A pointer to the socket address structure containing the remote address and port to which this socket is to be connected.
  • namelen: The length, in bytes, of the socket address structure pointed to by the name parameter.

Return Value

If the connection is successful, connect returns zero. If the socket is non-blocking and the connection cannot be established immediately, connect returns SOCKET_ERROR, and WSAGetLastError returns WSAEINPROGRESS. If the socket is blocking, and the connection cannot be established, connect returns SOCKET_ERROR, and WSAGetLastError returns a different error code.

listen() Function

Puts a socket into a listening state, preparing it to accept incoming connection requests.


int listen(
  _In_ SOCKET s,
  _In_ int    backlog
);

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, a SOCKET_ERROR value is returned, and a specific error code can be retrieved by calling WSAGetLastError.

accept() Function

Accepts a connection made to a socket that is listening for connections.


SOCKET WSAAPI accept(
  _In_ SOCKET   s,
  _Out_opt_ sockaddr *addr,
  _Inout_opt_ int    *addrlen
);

Parameters

  • s: A descriptor identifying a socket that is prepared for listening.
  • addr: An optional pointer to a buffer that will receive the address of the connecting entity.
  • addrlen: An optional pointer to an integer that contains the size of the buffer pointed to by addr.

Return Value

If no error occurs, accept returns a handle to a new socket that is connected to the specified socket. Otherwise, accept returns INVALID_SOCKET, and a specific error code can be retrieved by calling WSAGetLastError.

send() Function

Sends data on a connected socket.


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

Parameters

  • s: A descriptor identifying a socket.
  • buf: A pointer to the buffer containing the data to be transmitted.
  • len: The number of bytes to send from the buffer pointed to by the buf parameter.
  • flags: Flags that control the transmission.

Return Value

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

recv() Function

Receives data from a connected socket.


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

Parameters

  • s: A descriptor identifying a socket.
  • buf: A pointer to the buffer into which the received data will be copied.
  • len: The maximum number of bytes that can be received.
  • flags: Flags that influence the behavior of the receive operation.

Return Value

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

closesocket() Function

Closes an existing socket.


int closesocket(
  _In_ SOCKET s
);

Parameters

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

Return Value

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

gethostname() Function

Retrieves the standard host name for the current machine.


int gethostname(
  _Out_writes_bytes_(name buflen) char *name,
  _In_ int buflen
);

Parameters

  • name: A buffer to receive the null-terminated host name.
  • buflen: The size, in bytes, of the buffer pointed to by the name parameter.

Return Value

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

gethostbyname() Function

Retrieves the address of a host from its name. (Deprecated)

Note: For new development, it is recommended to use getaddrinfo.


struct hostent *gethostbyname(
  _In_ const char *name
);

Parameters

  • name: A pointer to a null-terminated string that contains the name of the host.

Return Value

If successful, gethostbyname returns a pointer to a hostent structure. Otherwise, it returns NULL. The caller should free the returned structure by calling free.

getaddrinfo() Function

Provides protocol-independent translation of a host name and service name to a set of socket address structures.


INT getaddrinfo(
  PCSTR              nodename,
  PCSTR              servicename,
  const ADDRINFOA    *hints,
  PADDRINFOA         *result
);

Parameters

  • nodename: The hostname or network address to resolve.
  • servicename: The service name or port number.
  • hints: A pointer to an ADDRINFOA structure that specifies criteria for the application.
  • result: A pointer to a linked list of ADDRINFOA structures that contains information about the specified host and service.

Return Value

On success, getaddrinfo returns NO_ERROR. On failure, it returns a non-zero error code.

inet_ntoa() Function

Converts an Internet Protocol (IP) address from an Internet network format to a string.


char *inet_ntoa(
  _In_ struct in_addr in
);

Parameters

  • in: An in_addr structure containing an IPv4 address in network byte order.

Return Value

If no error occurs, inet_ntoa returns a pointer to a character string that represents the IP address in decimal dot notation. Otherwise, NULL is returned.

getprotobyname() Function

Retrieves protocol information from a protocol name.


struct protoent *getprotobyname(
  _In_ const char *name
);

Parameters

  • name: A pointer to a null-terminated string that contains the protocol name.

Return Value

If successful, getprotobyname returns a pointer to a protoent structure. Otherwise, it returns NULL.

getservbyname() Function

Retrieves service information from a service name and protocol name.


struct servent *getservbyname(
  _In_ const char *name,
  _In_opt_ const char *proto
);

Parameters

  • name: A pointer to a null-terminated string containing the service name.
  • proto: An optional pointer to a null-terminated string containing the protocol name.

Return Value

If successful, getservbyname returns a pointer to a servent structure. Otherwise, it returns NULL.

ioctlsocket() Function

Changes the mode of a socket that is either blocking or non-blocking.


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

Parameters

  • s: A descriptor identifying the socket.
  • cmd: The control code for the operation. Use FIONBIO to set non-blocking mode.
  • argp: A pointer to the argument for the operation. For FIONBIO, a non-zero value means non-blocking, and zero means blocking.

Return Value

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

select() Function

Monitors multiple socket descriptors for readiness for read, write, or exception conditions.


int select(
  _In_ int          nfds,
  _Inout_opt_ fd_set *readfds,
  _Inout_opt_ fd_set *writefds,
  _Inout_opt_ fd_set *exceptfds,
  _In_opt_ const struct timeval *timeout
);

Parameters

  • nfds: The highest-numbered file descriptor in any of the sets, plus one.
  • readfds: A pointer to a set of socket descriptors to be checked for readability.
  • writefds: A pointer to a set of socket descriptors to be checked for writability.
  • exceptfds: A pointer to a set of socket descriptors to be checked for pending exceptions.
  • timeout: A pointer to a timeval structure that specifies the time interval to wait for a descriptor to become ready.

Return Value

If select returns successfully, it returns the total number of file descriptors contained in the selected sets that are ready. If the timeout expires before any file descriptors are ready, select returns 0. If an error occurs, it returns SOCKET_ERROR, and a specific error code can be retrieved by calling WSAGetLastError.

GetIfAddrs() Function

Retrieves a list of network interface addresses. (Part of IP Helper API)


DWORD GetIfAddrs(
  _Out_ PIP_INTERFACE_INFO *IfTable
);

Parameters

  • IfTable: A pointer to a buffer that receives a IP_INTERFACE_INFO structure, which contains an array of IP_INTERFACE_INFO structures.

Return Value

If the function succeeds, the return value is ERROR_SUCCESS. If the function fails, the return value is one of the system error codes.

GetBestRoute() Function

Retrieves the best route to a destination IP address. (Part of IP Helper API)


DWORD GetBestRoute(
  _In_ DWORD                  DestinationAddress,
  _In_ DWORD                  SourceAddress,
  _Out_ MIB_IPFORWARDROW     *Route
);

Parameters

  • DestinationAddress: The destination IP address for which to find the best route.
  • SourceAddress: The source IP address for which to find the best route.
  • Route: A pointer to a MIB_IPFORWARDROW structure that receives information about the best route.

Return Value

If the function succeeds, the return value is ERROR_SUCCESS. If the function fails, the return value is one of the system error codes.