Windows API Documentation

Network Management API

This section details the functions, structures, and concepts related to managing network resources and configurations within the Windows operating system using the Win32 API.

Core Concepts

Understanding network management involves several key areas:

• Network Protocols: Interaction with various network protocols supported by Windows.
• Network Adapters: Managing network interface controllers (NICs).
• Network Services: Configuring and controlling network services like DNS, DHCP, and firewalls.
• Remote Access: Handling connections and configurations for remote access technologies.
• IP Addressing and Routing: Programmatically managing IP addresses, subnets, and routing tables.

Key Functions

The following functions are central to network management tasks:

• GetAdaptersInfo: Retrieves information about network adapters.
• GetIpAddrProperties: Retrieves IP address properties for a given adapter.
• SetIpAddress: Configures an IP address on a network adapter (requires elevated privileges).
• GetHostByName: Resolves a hostname to an IP address.
• GetHostByAddr: Resolves an IP address to a hostname.
• SendARP: Sends an ARP request to resolve an IP address to a physical address.
• DnsCallbackDnsProxy: Callback function for DNS proxy operations.
• EnumNetworkDrivers: Enumerates network drivers.

Related Structures

These structures are often used in conjunction with the network management functions:

• IP_ADAPTER_INFO: Contains information about a network adapter.
• IP_ADDR_STRING: Represents an IP address string.
• IP_MASK: Represents an IP subnet mask.
• HOSTENT: Contains information about a host.

Function: GetAdaptersInfo

Prototype:

ULONG GetAdaptersInfo(
  PIP_ADAPTER_INFO pAdapterInfo,
  PULONG pOutBufLen
);

Description: Retrieves detailed information about network adapters installed on the local computer.

Parameters:

• pAdapterInfo: Pointer to a buffer that receives an IP_ADAPTER_INFO structure.
• pOutBufLen: Pointer to a ULONG variable that specifies the size of the buffer pointed to by pAdapterInfo. If the buffer is not large enough, the function returns ERROR_BUFFER_OVERFLOW and sets this variable to the required buffer size.

Return Value: If the function succeeds, the return value is NO_ERROR. If the buffer is not large enough, the return value is ERROR_BUFFER_OVERFLOW. Otherwise, the return value is one of the system error codes.

Function: GetIpAddrProperties

Prototype:

DWORD GetIpAddrProperties(
  NET_IFINDEX           InterfaceIndex,
  PIP_ADAPTER_ADDRESSES *AdapterAddresses
);

Description: Retrieves IP address properties for a specified network interface.

Parameters:

• InterfaceIndex: The index of the network interface.
• AdapterAddresses: Pointer to a pointer that receives the address of an array of IP_ADAPTER_ADDRESSES structures.

Return Value: Returns NO_ERROR if successful, otherwise an error code.

Structure: IP_ADAPTER_INFO

Definition:

typedef struct _IP_ADAPTER_INFO {
    struct _IP_ADAPTER_INFO *Next;
    CHAR                    AdapterName[NDIS_MAX_ADAPTER_NAME_LENGTH + 4];
    CHAR                    Description[NDIS_MAX_ADAPTER_DESCRIPTION_LENGTH + 4];
    UINT                    AddressLength;
    BYTE                    Address[NDIS_MAX_ADDRESS_LENGTH];
    UINT                    Index;
    UINT                    Type;
    UINT                    DhcpEnabled;
    IP_ADDR_STRING          IpAddress;
    IP_MASK                 SubnetMask;
    IP_ADDR_STRING          BroadcastAddress;
} IP_ADAPTER_INFO, *PIP_ADAPTER_INFO;

Members: Contains details like adapter name, description, MAC address, IP address, subnet mask, and DHCP status.

Function: GetHostByName

Prototype:

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

Description: Retrieves the host information corresponding to the host name specified.

Parameters:

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

Return Value: If successful, returns a pointer to a hostent structure. If not successful, it returns NULL. The h_errno variable can be checked for specific error codes.

Structure: HOSTENT

Definition:

struct hostent {
    char FAR *  h_name;      /* Official name of the host. */
    char FAR ** h_aliases;   /* A NULL-terminated array of alternate names, if any. */
    short       h_addrtype;  /* The type of the address. */
    short       h_length;    /* The length, in bytes, of the address. */
    char FAR ** h_addr_list; /* A NULL-terminated array of network addresses for the host. */
};

Members: Stores the canonical hostname, aliases, address type (e.g., AF_INET for IPv4), address length, and a list of IP addresses.

Function: SendARP

Prototype:

ULONG SendARP(
  IPAddr   DestIP,
  IPAddr   srcIP,
  PIP_ADDR_LONG pMacAddr,
  PIP_ADDR_LONG pIpAddr
);

Description: Resolves an IP address to its corresponding physical address (MAC address) using ARP.

Parameters:

• DestIP: The destination IP address.
• srcIP: The source IP address (optional, can be 0).
• pMacAddr: Pointer to a buffer that receives the physical address.
• pIpAddr: Pointer to a buffer that receives the IP address corresponding to the physical address (usually the same as DestIP).

Return Value: Returns NO_ERROR if successful, or an appropriate error code.