Fungsi GetInterfaceInfo (iphlpapi.h)

Artikel
08/24/2023

Fungsi GetInterfaceInfo mendapatkan daftar adaptor antarmuka jaringan dengan IPv4 diaktifkan pada sistem lokal.

Sintaks

IPHLPAPI_DLL_LINKAGE DWORD GetInterfaceInfo(
  [out]     PIP_INTERFACE_INFO pIfTable,
  [in, out] PULONG             dwOutBufLen
);

Parameter

[out] pIfTable

Penunjuk ke buffer yang menentukan struktur IP_INTERFACE_INFO yang menerima daftar adaptor. Buffer ini harus dialokasikan oleh pemanggil.

[in, out] dwOutBufLen

Penunjuk ke variabel DWORD yang menentukan ukuran buffer yang diacu oleh parameter pIfTable untuk menerima struktur IP_INTERFACE_INFO . Jika ukuran ini tidak cukup untuk menyimpan informasi antarmuka IPv4, GetInterfaceInfo mengisi variabel ini dengan ukuran yang diperlukan, dan mengembalikan kode kesalahan ERROR_INSUFFICIENT_BUFFER.

Nilai kembali

Jika fungsi berhasil, nilai yang dikembalikan adalah NO_ERROR.

Jika fungsi gagal, nilai yang dikembalikan adalah salah satu kode kesalahan berikut.

Menampilkan kode	Deskripsi
ERROR_INSUFFICIENT_BUFFER	Buffer untuk menerima informasi adaptor IPv4 terlalu kecil. Nilai ini dikembalikan jika parameter dwOutBufLen menunjukkan bahwa buffer yang diarahkan oleh parameter pIfTable terlalu kecil untuk mengambil informasi antarmuka IPv4. Ukuran yang diperlukan dikembalikan dalam variabel DWORD yang diarahkan oleh parameter dwOutBufLen .
ERROR_INVALID_PARAMETER	Parameter yang tidak valid diteruskan ke fungsi. Kesalahan ini dikembalikan jika parameter dwOutBufLenADALAH NULL, atau GetInterfaceInfo tidak dapat menulis ke memori yang diarahkan oleh parameter dwOutBufLen .
ERROR_NO_DATA	Tidak ada adaptor jaringan yang diaktifkan untuk IPv4 pada sistem lokal. Nilai ini juga dikembalikan jika semua adaptor jaringan pada sistem lokal dinonaktifkan.
ERROR_NOT_SUPPORTED	Fungsi ini tidak didukung pada sistem operasi yang digunakan pada sistem lokal.
Lainnya	Gunakan FormatMessage untuk mendapatkan string pesan untuk kesalahan yang dikembalikan.

Keterangan

Fungsi GetInterfaceInfo khusus untuk adaptor jaringan dengan IPv4 diaktifkan. Fungsi mengembalikan struktur IP_INTERFACE_INFO yang ditujukkan oleh parameter pIfTable yang berisi jumlah adaptor jaringan dengan IPv4 diaktifkan pada sistem lokal dan array struktur IP_ADAPTER_INDEX_MAP dengan informasi pada setiap adaptor jaringan dengan IPv4 diaktifkan. Struktur IP_INTERFACE_INFO yang dikembalikan oleh GetInterfaceInfo berisi setidaknya satu struktur IP_ADAPTER_INDEX_MAP meskipun anggota NumAdapters dari struktur IP_INTERFACE_INFO menunjukkan bahwa tidak ada adaptor jaringan dengan IPv4 yang diaktifkan. Ketika anggota NumAdapters dari struktur IP_INTERFACE_INFO yang dikembalikan oleh GetInterfaceInfo adalah nol, nilai anggota struktur IP_ADAPTER_INDEX_MAP tunggal yang dikembalikan dalam struktur IP_INTERFACE_INFO tidak terdefinisi.

Jika fungsi GetInterfaceInfo dipanggil dengan buffer yang terlalu kecil untuk mengambil informasi antarmuka IPv4 (parameter dwOutBufLen menunjukkan bahwa buffer yang ditunjukkan oleh parameter pIfTable terlalu kecil), fungsi mengembalikan ERROR_INSUFFICIENT_BUFFER. Ukuran yang diperlukan dikembalikan dalam variabel DWORD yang diarahkan oleh parameter dwOutBufLen .

Cara yang benar untuk menggunakan fungsi GetInterfaceInfo adalah dengan memanggil fungsi ini dua kali. Dalam panggilan pertama, berikan penunjuk NULL di parameter pIfTable dan nol dalam variabel yang diarahkan oleh parameter dwOutBufLen . Panggilan akan gagal dengan ERROR_INSUFFICIENT_BUFFER dan ukuran yang diperlukan untuk buffer ini dikembalikan dalam variabel DWORD yang diarahkan oleh parameter dwOutBufLen . Buffer kemudian dapat dialokasikan dari ukuran yang diperlukan menggunakan nilai yang ditunjukkan oleh dwOutBufLen. Kemudian fungsi GetInterfaceInfo dapat dipanggil untuk kedua kalinya dengan penunjuk ke buffer ini diteruskan dalam parameter pIfTable dan panjang buffer yang diatur ke ukuran buffer ini.

Fungsi GetAdaptersInfo dan GetInterfaceInfo tidak mengembalikan informasi tentang antarmuka loopback. Informasi tentang antarmuka loopback dikembalikan oleh fungsi GetIpAddrTable .

Pada Windows Vista dan yang lebih baru, anggota Nama struktur IP_ADAPTER_INDEX_MAP yang dikembalikan dalam struktur IP_INTERFACE_INFO mungkin merupakan string Unicode GUID untuk antarmuka jaringan (string dimulai dengan karakter '{').

Contoh

Contoh berikut mengambil daftar adaptor jaringan dengan IPv4 diaktifkan pada sistem lokal dan mencetak berbagai properti adaptor jaringan pertama.

#include <winsock2.h>
#include <ws2ipdef.h>
#include <iphlpapi.h>
#include <stdio.h>

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

#define MALLOC(x) HeapAlloc(GetProcessHeap(), 0, (x)) 
#define FREE(x) HeapFree(GetProcessHeap(), 0, (x))

/* Note: could also use malloc() and free() */

int main()
{

// Declare and initialize variables
    PIP_INTERFACE_INFO pInfo = NULL;
    ULONG ulOutBufLen = 0;

    DWORD dwRetVal = 0;
    int iReturn = 1;

    int i;

// Make an initial call to GetInterfaceInfo to get
// the necessary size in the ulOutBufLen variable
    dwRetVal = GetInterfaceInfo(NULL, &ulOutBufLen);
    if (dwRetVal == ERROR_INSUFFICIENT_BUFFER) {
        pInfo = (IP_INTERFACE_INFO *) MALLOC(ulOutBufLen);
        if (pInfo == NULL) {
            printf
                ("Unable to allocate memory needed to call GetInterfaceInfo\n");
            return 1;
        }
    }
// Make a second call to GetInterfaceInfo to get
// the actual data we need
    dwRetVal = GetInterfaceInfo(pInfo, &ulOutBufLen);
    if (dwRetVal == NO_ERROR) {
        printf("Number of Adapters: %ld\n\n", pInfo->NumAdapters);
        for (i = 0; i < pInfo->NumAdapters; i++) {
            printf("Adapter Index[%d]: %ld\n", i,
                   pInfo->Adapter[i].Index);
            printf("Adapter Name[%d]: %ws\n\n", i,
                   pInfo->Adapter[i].Name);
        }
        iReturn = 0;
    } else if (dwRetVal == ERROR_NO_DATA) {
        printf
            ("There are no network adapters with IPv4 enabled on the local system\n");
        iReturn = 0;
    } else {
        printf("GetInterfaceInfo failed with error: %d\n", dwRetVal);
        iReturn = 1;
    }

    FREE(pInfo);
    return (iReturn);
}

Persyaratan


Klien minimum yang didukung	Windows 2000 Professional [hanya aplikasi desktop]
Server minimum yang didukung	Windows 2000 Server [hanya aplikasi desktop]
Target Platform	Windows
Header	iphlpapi.h
Pustaka	Iphlpapi.lib
DLL	Iphlpapi.dll