GetAdaptersAddresses Function

Retrieves the adapter addresses associated with the local computer.

Syntax

IPHLPAPI_API DWORD GetAdaptersAddresses(
    ULONG Family,
    ULONG Flags,
    PVOID Reserved,
    PIP_ADAPTER_ADDRESSES pAdapterAddresses,
    PULONG SizePointer
);
            

Parameters

• Family
  The family of addresses to retrieve. Possible values are:
  • AF_UNSPEC
  • AF_INET
  • AF_INET6
• Flags
  Flags that control the retrieval of adapter addresses. See Adapter Address Flags for details.
• Reserved
  Reserved for future use. Must be zero.
• pAdapterAddresses
  A pointer to a buffer that receives a linked list of IP_ADAPTER_ADDRESSES structures.
• SizePointer
  On input, a pointer to a ULONG variable that specifies the size, in bytes, of the buffer pointed to by pAdapterAddresses.
  On output, if the buffer is not large enough to hold the returned adapter addresses, this parameter receives the required buffer size, in bytes.

Return Value

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is one of the following error codes.

Remarks

This function is used to retrieve information about the network adapters on the local computer. The information is returned as a linked list of IP_ADAPTER_ADDRESSES structures.

The Family parameter specifies the address family to retrieve. AF_UNSPEC retrieves all address families.

The Flags parameter can be used to filter the results. For example, it can be used to retrieve only active adapters or to include IP addresses.

The pAdapterAddresses parameter points to a buffer that will be filled with the adapter information. If the buffer is too small, the function will return ERROR_BUFFER_OVERFLOW and the required buffer size will be returned in SizePointer.

Example

// Example code snippet - Placeholder for actual C++ code
#include <windows.h>
#include <iphlpapi.h>
#include <stdio.h>
#pragma comment(lib, "iphlpapi.lib")

int main() {
    ULONG family = AF_UNSPEC;
    ULONG flags = GAA_FLAG_INCLUDE_PREFIX;
    PIP_ADAPTER_ADDRESSES pAddresses = NULL;
    ULONG size = 0;
    DWORD dwRetVal = 0;

    // Make an initial call to GetAdaptersAddresses to get the necessary size
    dwRetVal = GetAdaptersAddresses(family, flags, NULL, pAddresses, &size);

    if (dwRetVal == ERROR_BUFFER_OVERFLOW) {
        // Allocate memory for the buffer
        pAddresses = (PIP_ADAPTER_ADDRESSES) malloc(size);
        if (pAddresses == NULL) {
            printf("Error allocating memory needed to get adapter addresses\n");
            return 1;
        }
    } else if (dwRetVal != ERROR_SUCCESS) {
        printf("Error getting adapter addresses: %lu\n", dwRetVal);
        return 1;
    }

    // Call GetAdaptersAddresses again with the allocated buffer
    dwRetVal = GetAdaptersAddresses(family, flags, NULL, pAddresses, &size);

    if (dwRetVal == ERROR_SUCCESS) {
        PIP_ADAPTER_ADDRESSES pCurrAddresses = pAddresses;
        while (pCurrAddresses) {
            printf("Adapter Name: %ws\n", pCurrAddresses->FriendlyName);
            // Process other adapter details as needed
            pCurrAddresses = pCurrAddresses->Next;
        }
    } else {
        printf("Error getting adapter addresses with allocated buffer: %lu\n", dwRetVal);
    }

    if (pAddresses) {
        free(pAddresses);
    }

    return 0;
}
            

Requirements