Domain Name System (DNS) Functions

This section details the Windows Sockets API functions for querying and managing Domain Name System (DNS) records. These functions enable applications to resolve hostnames to IP addresses, retrieve MX records, and perform other DNS-related operations.

Core Concepts

DNS is a hierarchical and decentralized naming system for computers, services, or any resource connected to the Internet or a private network. It translates human-readable domain names into the numerical IP addresses needed for locating and identifying computer services and devices.

Key Functions

GetAddrInfo

The GetAddrInfo function is the modern, recommended way to resolve a network hostname or service name to a list of socket address structures. It supports both IPv4 and IPv6 protocols and provides more flexibility than older functions like gethostbyname.

Syntax:

int GetAddrInfo(
      const char *nodename,
      const char *servname,
      const ADDRINFOA *hints,
      ADDRINFOA **res
    );

Parameters:

  • nodename: The name of the host to resolve.
  • servname: The name of the service to resolve.
  • hints: A pointer to an ADDRINFOA structure that specifies criteria for the returned address structures.
  • res: A pointer to a linked list of ADDRINFOA structures, each containing an address structure for the specified host and service.

Return Value:

On success, returns 0. On failure, returns a Windows Sockets error code.

See Also: FreeAddrInfo, ADDRINFOA Structure

GetHostByName (Deprecated)

The GetHostByName function retrieves information about a host on the network by its name. While functional, it is largely superseded by GetAddrInfo due to its limitations with IPv6 and error handling.

Syntax:

HOSTENT *gethostbyname(
      const char *name
    );

Parameters:

  • name: The hostname to resolve.

Return Value:

On success, returns a pointer to a HOSTENT structure. On failure, returns NULL. Use WSAGetLastError to get specific error information.

See Also: HOSTENT Structure, WSAGetLastError

GetHostByAddress (Deprecated)

The GetHostByAddress function retrieves information about a host on the network by its IP address. Similar to GetHostByName, it is largely superseded by GetAddrInfo.

Syntax:

HOSTENT *gethostbyaddress(
      const char *addr,
      int len,
      int type
    );

Parameters:

  • addr: A pointer to the IP address.
  • len: The length, in bytes, of the address.
  • type: The address type (e.g., AF_INET for IPv4).

Return Value:

On success, returns a pointer to a HOSTENT structure. On failure, returns NULL. Use WSAGetLastError to get specific error information.

See Also: HOSTENT Structure, WSAGetLastError

Related Structures

Structure Name Description
ADDRINFOA Specifies criteria for address resolution and returns address information.
HOSTENT Contains information about a host, including its name and IP addresses.
SOCKADDR_IN Stores a socket address for IPv4.
SOCKADDR_IN6 Stores a socket address for IPv6.

Error Handling

When DNS functions fail, they typically return a non-zero error code or a NULL pointer. The WSAGetLastError function should be called to retrieve the specific error code, which can then be used to consult the Windows Sockets Error Codes documentation for more details.