Fungsi GetAdaptersAddresses (iphlpapi.h)
Fungsi GetAdaptersAddresses mengambil alamat yang terkait dengan adaptor di komputer lokal.
Sintaks
IPHLPAPI_DLL_LINKAGE ULONG GetAdaptersAddresses(
[in] ULONG Family,
[in] ULONG Flags,
[in] PVOID Reserved,
[in, out] PIP_ADAPTER_ADDRESSES AdapterAddresses,
[in, out] PULONG SizePointer
);
Parameter
[in] Family
Keluarga alamat alamat yang akan diambil. Parameter ini harus menjadi salah satu nilai berikut.
[in] Flags
Jenis alamat yang akan diambil. Nilai yang mungkin ditentukan dalam file header Iptypes.h . Perhatikan bahwa file header Iptypes.h secara otomatis disertakan dalam Iphlpapi.h, dan tidak boleh digunakan secara langsung.
Parameter ini adalah kombinasi dari nilai berikut. Jika parameter ini nol, maka alamat IP unicast, anycast, dan multicast akan dikembalikan.
[in] Reserved
Parameter ini saat ini tidak digunakan, tetapi dicadangkan untuk penggunaan sistem di masa mendatang. Aplikasi panggilan harus melewati NULL untuk parameter ini.
[in, out] AdapterAddresses
Penunjuk ke buffer yang berisi daftar tertaut struktur IP_ADAPTER_ADDRESSES pada pengembalian yang berhasil.
[in, out] SizePointer
Penunjuk ke variabel yang menentukan ukuran buffer yang diacu oleh AdapterAddresses.
Menampilkan nilai
Jika fungsi berhasil, nilai yang dikembalikan ERROR_SUCCESS (didefinisikan ke nilai yang sama dengan NO_ERROR).
Jika fungsi gagal, nilai yang dikembalikan adalah salah satu kode kesalahan berikut.
| Menampilkan kode | Deskripsi |
|---|---|
|
Alamat belum dikaitkan dengan titik akhir jaringan. Informasi sewa DHCP tersedia. |
|
Ukuran buffer yang ditunjukkan oleh parameter SizePointer terlalu kecil untuk menyimpan informasi adaptor atau parameter AdapterAddresses adalah NULL. Parameter SizePointer mengembalikan titik ke ukuran buffer yang diperlukan untuk menyimpan informasi adaptor. |
|
Salah satu parameter tidak valid. Kesalahan ini dikembalikan untuk salah satu kondisi berikut: parameter SizePointer adalah NULL, parameter Alamat tidak AF_INET, AF_INET6, atau AF_UNSPEC, atau informasi alamat untuk parameter yang diminta lebih besar dari ULONG_MAX. |
|
Sumber daya memori tidak cukup tersedia untuk menyelesaikan operasi. |
|
Tidak ada alamat yang ditemukan untuk parameter yang diminta. |
|
Gunakan FormatMessage untuk mendapatkan string pesan untuk kesalahan yang dikembalikan. |
Keterangan
The
Fungsi GetAdaptersAddresses dapat mengambil informasi untuk alamat IPv4 dan IPv6.
Alamat dikembalikan sebagai daftar tertaut struktur IP_ADAPTER_ADDRESSES dalam buffer yang ditujukkan oleh parameter AdapterAddresses . Aplikasi yang memanggil fungsi GetAdaptersAddresses harus mengalokasikan jumlah memori yang diperlukan untuk mengembalikan struktur IP_ADAPTER_ADDRESSES yang diarahkan oleh parameter AdapterAddresses . Ketika struktur yang dikembalikan ini tidak lagi diperlukan, aplikasi harus membebaskan memori yang dialokasikan. Ini dapat dicapai dengan memanggil fungsi HeapAlloc untuk mengalokasikan memori dan kemudian memanggil fungsi HeapFree untuk membebaskan memori yang dialokasikan, seperti yang ditunjukkan dalam kode contoh. Alokasi memori lain dan fungsi bebas dapat digunakan selama keluarga fungsi yang sama digunakan untuk alokasi dan fungsi bebas.
GetAdaptersAddresses hanya diimplementasikan sebagai panggilan fungsi sinkron. Fungsi GetAdaptersAddresses memerlukan sejumlah besar sumber daya dan waktu jaringan untuk diselesaikan karena semua tabel antarmuka jaringan tingkat rendah harus dilalui.
Salah satu metode yang dapat digunakan untuk menentukan memori yang diperlukan untuk mengembalikan struktur IP_ADAPTER_ADDRESSES yang ditunjukkan oleh parameter AdapterAddresses adalah meneruskan ukuran buffer yang terlalu kecil seperti yang ditunjukkan dalam parameter SizePointer pada panggilan pertama ke fungsi GetAdaptersAddresses , sehingga fungsi akan gagal dengan ERROR_BUFFER_OVERFLOW. Saat nilai yang dikembalikan ERROR_BUFFER_OVERFLOW, parameter SizePointer mengembalikan poin ke ukuran buffer yang diperlukan untuk menyimpan informasi adaptor. Perhatikan bahwa ukuran buffer yang diperlukan untuk struktur IP_ADAPTER_ADDRESSES yang ditunjukkan oleh parameter AdapterAddresses berubah antara panggilan berikutnya ke fungsi GetAdaptersAddresses jika alamat adaptor ditambahkan atau dihapus. Namun, metode penggunaan fungsi GetAdaptersAddresses ini sangat tidak disarankan. Metode ini mengharuskan memanggil fungsi GetAdaptersAddresses beberapa kali.
Metode yang direkomendasikan untuk memanggil fungsi GetAdaptersAddresses adalah dengan mengalokasikan buffer kerja 15KB sebelumnya yang ditujukkan oleh parameter AdapterAddresses . Pada komputer biasa, ini secara dramatis mengurangi kemungkinan fungsi GetAdaptersAddresses mengembalikan ERROR_BUFFER_OVERFLOW, yang akan memerlukan pemanggilan fungsi GetAdaptersAddresses beberapa kali. Contoh kode mengilustrasikan metode penggunaan ini.
Dalam versi sebelum Windows 10, urutan munculnya adaptor dalam daftar yang dikembalikan oleh fungsi ini dapat dikontrol dari folder Koneksi Jaringan: pilih item menu Pengaturan Tingkat Lanjut dari menu Tingkat Lanjut. Dimulai dengan Windows 10, urutan munculnya adaptor dalam daftar ditentukan oleh metrik rute IPv4 atau IPv6.
Jika GAA_FLAG_INCLUDE_ALL_INTERFACES diatur, maka semua adaptor NDIS akan diambil bahkan alamat yang terkait dengan adaptor yang tidak terikat ke keluarga alamat yang ditentukan dalam parameter Keluarga . Ketika bendera ini tidak diatur, maka hanya alamat yang terikat ke adaptor yang diaktifkan untuk keluarga alamat yang ditentukan dalam parameter Keluarga yang dikembalikan.
Ukuran struktur IP_ADAPTER_ADDRESSES diubah pada Windows XP dengan Paket Layanan 1 (SP1) dan yang lebih baru. Beberapa anggota tambahan ditambahkan ke struktur ini. Ukuran struktur IP_ADAPTER_ADDRESSES juga diubah pada Windows Vista dan yang lebih baru. Sejumlah anggota tambahan ditambahkan ke struktur ini. Ukuran struktur IP_ADAPTER_ADDRESSES juga berubah pada Windows Vista dengan Paket Layanan 1 (SP1)dan yang lebih baru dan diWindows Server 2008 dan yang lebih baru. Satu anggota tambahan ditambahkan ke struktur ini. Anggota Panjang struktur IP_ADAPTER_ADDRESSES yang dikembalikan dalam daftar struktur yang ditautkan dalam buffer yang ditujukkan oleh parameter AdapterAddresses harus digunakan untuk menentukan versi struktur IP_ADAPTER_ADDRESSES mana yang sedang digunakan.
Fungsi GetIpAddrTable mengambil tabel pemetaan alamat antarmuka–ke–IPv4 di komputer lokal dan mengembalikan informasi ini dalam struktur MIB_IPADDRTABLE .
Pada Platform Software Development Kit (SDK) yang dirilis untuk Windows Server 2003 dan yang lebih lama, nilai pengembalian untuk fungsi GetAdaptersAddresses didefinisikan sebagai DWORD, bukan ULONG.
Struktur SOCKET_ADDRESS digunakan dalam struktur IP_ADAPTER_ADDRESSES yang ditujukkan oleh parameter AdapterAddresses . Pada Kit Pengembangan Perangkat Lunak (SDK) Microsoft Windows yang dirilis untuk Windows Vista dan yang lebih baru, organisasi file header telah berubah dan struktur SOCKET_ADDRESS didefinisikan dalam file header Ws2def.h yang secara otomatis disertakan oleh file header Winsock2.h . Pada Platform SDK yang dirilis untuk Windows Server 2003 dan Windows XP, struktur SOCKET_ADDRESS dideklarasikan dalam file header Winsock2.h . Untuk menggunakan struktur IP_ADAPTER_ADDRESSES , file header Winsock2.h harus disertakan sebelum file header Iphlpapi.h .
Contoh
Contoh ini mengambil struktur IP_ADAPTER_ADDRESSES untuk adaptor yang terkait dengan sistem dan mencetak beberapa anggota untuk setiap antarmuka adapter.
#include <winsock2.h>
#include <iphlpapi.h>
#include <stdio.h>
#include <stdlib.h>
// Link with Iphlpapi.lib
#pragma comment(lib, "IPHLPAPI.lib")
#define WORKING_BUFFER_SIZE 15000
#define MAX_TRIES 3
#define MALLOC(x) HeapAlloc(GetProcessHeap(), 0, (x))
#define FREE(x) HeapFree(GetProcessHeap(), 0, (x))
/* Note: could also use malloc() and free() */
int __cdecl main(int argc, char **argv)
{
/* Declare and initialize variables */
DWORD dwRetVal = 0;
unsigned int i = 0;
// Set the flags to pass to GetAdaptersAddresses
ULONG flags = GAA_FLAG_INCLUDE_PREFIX;
// default to unspecified address family (both)
ULONG family = AF_UNSPEC;
LPVOID lpMsgBuf = NULL;
PIP_ADAPTER_ADDRESSES pAddresses = NULL;
ULONG outBufLen = 0;
ULONG Iterations = 0;
PIP_ADAPTER_ADDRESSES pCurrAddresses = NULL;
PIP_ADAPTER_UNICAST_ADDRESS pUnicast = NULL;
PIP_ADAPTER_ANYCAST_ADDRESS pAnycast = NULL;
PIP_ADAPTER_MULTICAST_ADDRESS pMulticast = NULL;
IP_ADAPTER_DNS_SERVER_ADDRESS *pDnServer = NULL;
IP_ADAPTER_PREFIX *pPrefix = NULL;
if (argc != 2) {
printf(" Usage: getadapteraddresses family\n");
printf(" getadapteraddresses 4 (for IPv4)\n");
printf(" getadapteraddresses 6 (for IPv6)\n");
printf(" getadapteraddresses A (for both IPv4 and IPv6)\n");
exit(1);
}
if (atoi(argv[1]) == 4)
family = AF_INET;
else if (atoi(argv[1]) == 6)
family = AF_INET6;
printf("Calling GetAdaptersAddresses function with family = ");
if (family == AF_INET)
printf("AF_INET\n");
if (family == AF_INET6)
printf("AF_INET6\n");
if (family == AF_UNSPEC)
printf("AF_UNSPEC\n\n");
// Allocate a 15 KB buffer to start with.
outBufLen = WORKING_BUFFER_SIZE;
do {
pAddresses = (IP_ADAPTER_ADDRESSES *) MALLOC(outBufLen);
if (pAddresses == NULL) {
printf
("Memory allocation failed for IP_ADAPTER_ADDRESSES struct\n");
exit(1);
}
dwRetVal =
GetAdaptersAddresses(family, flags, NULL, pAddresses, &outBufLen);
if (dwRetVal == ERROR_BUFFER_OVERFLOW) {
FREE(pAddresses);
pAddresses = NULL;
} else {
break;
}
Iterations++;
} while ((dwRetVal == ERROR_BUFFER_OVERFLOW) && (Iterations < MAX_TRIES));
if (dwRetVal == NO_ERROR) {
// If successful, output some information from the data we received
pCurrAddresses = pAddresses;
while (pCurrAddresses) {
printf("\tLength of the IP_ADAPTER_ADDRESS struct: %ld\n",
pCurrAddresses->Length);
printf("\tIfIndex (IPv4 interface): %u\n", pCurrAddresses->IfIndex);
printf("\tAdapter name: %s\n", pCurrAddresses->AdapterName);
pUnicast = pCurrAddresses->FirstUnicastAddress;
if (pUnicast != NULL) {
for (i = 0; pUnicast != NULL; i++)
pUnicast = pUnicast->Next;
printf("\tNumber of Unicast Addresses: %d\n", i);
} else
printf("\tNo Unicast Addresses\n");
pAnycast = pCurrAddresses->FirstAnycastAddress;
if (pAnycast) {
for (i = 0; pAnycast != NULL; i++)
pAnycast = pAnycast->Next;
printf("\tNumber of Anycast Addresses: %d\n", i);
} else
printf("\tNo Anycast Addresses\n");
pMulticast = pCurrAddresses->FirstMulticastAddress;
if (pMulticast) {
for (i = 0; pMulticast != NULL; i++)
pMulticast = pMulticast->Next;
printf("\tNumber of Multicast Addresses: %d\n", i);
} else
printf("\tNo Multicast Addresses\n");
pDnServer = pCurrAddresses->FirstDnsServerAddress;
if (pDnServer) {
for (i = 0; pDnServer != NULL; i++)
pDnServer = pDnServer->Next;
printf("\tNumber of DNS Server Addresses: %d\n", i);
} else
printf("\tNo DNS Server Addresses\n");
printf("\tDNS Suffix: %wS\n", pCurrAddresses->DnsSuffix);
printf("\tDescription: %wS\n", pCurrAddresses->Description);
printf("\tFriendly name: %wS\n", pCurrAddresses->FriendlyName);
if (pCurrAddresses->PhysicalAddressLength != 0) {
printf("\tPhysical address: ");
for (i = 0; i < (int) pCurrAddresses->PhysicalAddressLength;
i++) {
if (i == (pCurrAddresses->PhysicalAddressLength - 1))
printf("%.2X\n",
(int) pCurrAddresses->PhysicalAddress[i]);
else
printf("%.2X-",
(int) pCurrAddresses->PhysicalAddress[i]);
}
}
printf("\tFlags: %ld\n", pCurrAddresses->Flags);
printf("\tMtu: %lu\n", pCurrAddresses->Mtu);
printf("\tIfType: %ld\n", pCurrAddresses->IfType);
printf("\tOperStatus: %ld\n", pCurrAddresses->OperStatus);
printf("\tIpv6IfIndex (IPv6 interface): %u\n",
pCurrAddresses->Ipv6IfIndex);
printf("\tZoneIndices (hex): ");
for (i = 0; i < 16; i++)
printf("%lx ", pCurrAddresses->ZoneIndices[i]);
printf("\n");
printf("\tTransmit link speed: %I64u\n", pCurrAddresses->TransmitLinkSpeed);
printf("\tReceive link speed: %I64u\n", pCurrAddresses->ReceiveLinkSpeed);
pPrefix = pCurrAddresses->FirstPrefix;
if (pPrefix) {
for (i = 0; pPrefix != NULL; i++)
pPrefix = pPrefix->Next;
printf("\tNumber of IP Adapter Prefix entries: %d\n", i);
} else
printf("\tNumber of IP Adapter Prefix entries: 0\n");
printf("\n");
pCurrAddresses = pCurrAddresses->Next;
}
} else {
printf("Call to GetAdaptersAddresses failed with error: %d\n",
dwRetVal);
if (dwRetVal == ERROR_NO_DATA)
printf("\tNo addresses were found for the requested parameters\n");
else {
if (FormatMessage(FORMAT_MESSAGE_ALLOCATE_BUFFER |
FORMAT_MESSAGE_FROM_SYSTEM | FORMAT_MESSAGE_IGNORE_INSERTS,
NULL, dwRetVal, MAKELANGID(LANG_NEUTRAL, SUBLANG_DEFAULT),
// Default language
(LPTSTR) & lpMsgBuf, 0, NULL)) {
printf("\tError: %s", lpMsgBuf);
LocalFree(lpMsgBuf);
if (pAddresses)
FREE(pAddresses);
exit(1);
}
}
}
if (pAddresses) {
FREE(pAddresses);
}
return 0;
}
Persyaratan
| Klien minimum yang didukung | Windows XP [aplikasi desktop | Aplikasi UWP] |
| Server minimum yang didukung | Windows Server 2003 [aplikasi desktop | Aplikasi UWP] |
| Target Platform | Windows |
| Header | iphlpapi.h |
| Pustaka | Iphlpapi.lib |
| DLL | Iphlpapi.dll |