[Networking] GetAdaptersAddresses function (iphlpapi.h)

GetAdaptersAddresses 함수는 로컬 컴퓨터의 네트워크 어댑터에 대한 정보를 검색하는 데 사용되는 Windows API 함수다. 이 함수는 IPv4 및 IPv6 주소와 기타 어댑터 관련 정보를 포함한 포괄적인 세부 정보를 제공한다. 이 함수는 IPv6 및 추가 어댑터 정보를 지원해 GetAdaptersInfo에 비해 더 현대적이고 다양한 기능을 제공하기에 이전 함수인 GetAdaptersInfo에 비해 선호된다. 이 함수는 반환되는 대량의 데이터를 처리하기 위해 적절한 버퍼 관리가 필요하므로 최신 네트워크 애플리케이션에 더 유연하고 미래 지향적이다.

ULONG GetAdaptersAddresses(
  ULONG                 Family,
  ULONG                 Flags,
  PVOID                 Reserved,
  PIP_ADAPTER_ADDRESSES AdapterAddresses,
  PULONG                SizePointer
);

1. 매개변수
   1. Family (IN parameter)
      
      1. 타입: ULONG
      2. 설명
         : 주소 패밀리를 지정한다. IPv4의 경우 AF_INET, IPv6의 경우 AF_INET6, IPv4와 IPv6 모두의 경우 AF_UNSPEC이 될 수 있다.
   2. Flags
      1. 타입: ULONG
      2. 설명
         : 함수의 동작을 수정하는 플래그의 조합이다. 많이 사용되는 플래그는 아래와 같다.
         
         1. GAA_FLAG_SKIP_UNICAST : unicast 주소를 건너뛴다.
         2. GAA_FLAG_SKIP_ANYCAST : anycast 주소를 건너뛴다.
         3. GAA_FLAG_SKIP_MULTICAST : multicast 주소를 건너뛴다.
         4. GAA_FLAG_SKIP_DNS_SERVER : DNS 서버 주소를 건너뛴다.
         5. GAA_FLAG_INCLUDE_PREFIX : 접두사 정보를 포함한다.
   3. Reserved (IN parameter)
      1. 타입: PVOID
      2. 설명
         : 향후 사용을 위해 예약됐고(reserved), 반드시 NULL로 설정해야 한다.
   4. AdapterAddresses (OUT parameter)
      
      1. 타입: PIP_ADAPTER_ADDRESSES
      2. 설명
         : 어댑터 주소를 수신하는 버퍼에 대한 포인터다. 이 버퍼는 호출자가 할당해야 한다.
   5. SizePointer (INOUT parameter)
      1. 타입: PULONG
      2. 설명
         : 입력 시 이 매개변수는 AdapterAddresses가 가리키는 버퍼의 크기를 지정한다. 출력 시에는 제공된 버퍼가 너무 작으면 필요한 버퍼 크기를 받는다.
2. 반환 값
   : 이 함수는 함수 호출 상태를 나타내는 ULONG을 반환한다. 가능한 반환 값은 아래와 같다.
   1. NO_ERROR
      : 함수가 성공했다
   2. ERROR_BUFFER_OVERFLOW
      : 어댑터 주소가 가리키는 버퍼가 너무 작아서 반환된 데이터를 담을 수 없다. 필요한 버퍼 크기는 SizePointer로 반환된다.
   3. 기타 오류 코드는 Windows API 문서에 정의되어 있다.
3. 사용 예시
   : 아래는 GetAdaptersAddresses를 사용해 네트워크 어댑터 세부 정보를 검생하는 방법의 예시다.

#include <iostream>
#include <Windows.h>
#include <iphlpapi.h>
#include <vector>
#include <string>

#pragma comment(lib, "IPHLPAPI.lib")

struct NetworkInterface {
    std::string adapterName;
    std::string description;
    std::string macAddress;
};

std::vector<NetworkInterface> getNetworkInterfaces() {
    std::vector<NetworkInterface> interfaces;
    ULONG bufferSize = 0;

    // Initial call to determine the required buffer size
    GetAdaptersAddresses(AF_UNSPEC, 0, nullptr, nullptr, &bufferSize);

    // Allocate the required buffer
    IP_ADAPTER_ADDRESSES* adapterAddresses = (IP_ADAPTER_ADDRESSES*)malloc(bufferSize);

    // Call to get the actual adapter addresses
    if (GetAdaptersAddresses(AF_UNSPEC, 0, nullptr, adapterAddresses, &bufferSize) == NO_ERROR) {
        IP_ADAPTER_ADDRESSES* adapter = adapterAddresses;
        while (adapter) {
            NetworkInterface iface;
            iface.adapterName = adapter->AdapterName;
            iface.description = adapter->Description;

            char macAddr[18];
            snprintf(macAddr, sizeof(macAddr), "%02X:%02X:%02X:%02X:%02X:%02X",
                     adapter->PhysicalAddress[0], adapter->PhysicalAddress[1],
                     adapter->PhysicalAddress[2], adapter->PhysicalAddress[3],
                     adapter->PhysicalAddress[4], adapter->PhysicalAddress[5]);
            iface.macAddress = macAddr;

            interfaces.push_back(iface);
            adapter = adapter->Next;
        }
    } else {
        std::cerr << "GetAdaptersAddresses failed." << std::endl;
    }

    // Clean up
    free(adapterAddresses);
    return interfaces;
}

int main() {
    std::vector<NetworkInterface> interfaces = getNetworkInterfaces();
    for (const auto& iface : interfaces) {
        std::cout << "Adapter Name: " << iface.adapterName << ", Description: " << iface.description
                  << ", MAC: " << iface.macAddress << std::endl;
    }
    return 0;
}

 

1. headers 포함
   1. #include <Windows.h> : Windows API 함수용
   2. #include <iphlpapi.h> : IP helper 함수용
2. IP helper 라이브러리 링크
   : #pragma comment(lib, "IPHLPAP.lib") : IP helper API 라이브러리 연결
   
   
3. 네트워크 인터페이스 구조체 정의
   : 네트워크 인터페이스의 어댑터 이름, 설명, MAC address를 저장하는 구조체
   
   
4. getNetworkInterfaces 구현
   1. 초기 버퍼 크기
      : 필요한 버퍼 크기를 결정하려면 어댑터 주소에 nullptr을 사용해 GetAdaptersAddresses를 호출한다. 필요한 크기는 buffersSize로 반환된다.
   2. 버퍼 할당
      : 어댑터 주소에 필요한 크기의 버퍼를 할당한다.
   3. 어댑터 주소 검색
      : 할당된 버퍼를 사용해 GetAdaptersAddresses를 다시 호출한다. 이 함수는 버퍼를 어댑터 정보로 채운다.
   4. 데이터 추출 및 포맷
      : 연결된 어댑터 목록을 반복하고, MAC address의 주소 형식을 지정하고, 정보를 NetworkInterface 구조의 벡터에 저장한다.
5. 정리
   : 어댑터 주소에 할당된 메모리를 비운다
   
   
6. Main 함수
   : getNetworkInterfaces를 호출해 네트워크 인터페이스 리스트를 검색하고 세부 정보를 프린트한다.

 

 

참고

- https://learn.microsoft.com/en-us/windows/win32/api/iphlpapi/nf-iphlpapi-getadaptersaddresses