Fungsi AddIPAddress (iphlpapi.h)
Fungsi AddIPAddress menambahkan alamat IPv4 yang ditentukan ke adaptor yang ditentukan.
Sintaks
IPHLPAPI_DLL_LINKAGE DWORD AddIPAddress(
[in] IPAddr Address,
[in] IPMask IpMask,
[in] DWORD IfIndex,
[out] PULONG NTEContext,
[out] PULONG NTEInstance
);
Parameter
[in] Address
Alamat IPv4 untuk ditambahkan ke adaptor, dalam bentuk struktur IPAddr .
[in] IpMask
Subnet mask untuk alamat IPv4 yang ditentukan dalam parameter Alamat . Parameter IPMask menggunakan format yang sama dengan struktur IPAddr .
[in] IfIndex
Indeks adaptor untuk menambahkan alamat IPv4.
[out] NTEContext
Penunjuk ke variabel ULONG . Saat pengembalian berhasil, parameter ini menunjuk ke konteks Net Table Entry (NTE) untuk alamat IPv4 yang ditambahkan. Penelepon nantinya dapat menggunakan konteks ini dalam panggilan ke fungsi DeleteIPAddress .
[out] NTEInstance
Penunjuk ke variabel ULONG . Saat pengembalian berhasil, parameter ini menunjuk ke instans NTE untuk alamat IPv4 yang ditambahkan.
Mengembalikan nilai
Jika fungsi berhasil, nilai yang dikembalikan NO_ERROR.
Jika fungsi gagal, nilai yang dikembalikan adalah salah satu kode kesalahan berikut.
| Menampilkan kode | Deskripsi |
|---|---|
|
Adaptor yang ditentukan oleh parameter IfIndex tidak ada. |
|
Alamat IPv4 untuk ditambahkan yang ditentukan dalam parameter Alamat sudah ada. |
|
Kegagalan umum. Kesalahan ini dikembalikan untuk beberapa nilai yang ditentukan dalam parameter Alamat , seperti alamat IPv4 yang biasanya dianggap sebagai alamat siaran. |
|
Pengguna yang mencoba melakukan panggilan fungsi bukan administrator. |
|
Satu atau beberapa parameter tidak valid. Kesalahan ini dikembalikan jika parameter NTEContext atau NTEInstanceADALAH NULL. Kesalahan ini juga dikembalikan ketika alamat IP yang ditentukan dalam parameter Alamat tidak konsisten dengan indeks antarmuka yang ditentukan dalam parameter IfIndex (misalnya, alamat loopback pada antarmuka non-loopback). |
|
Panggilan fungsi tidak didukung pada versi Windows tempat menjalankannya. |
|
Gunakan FormatMessage untuk mendapatkan string pesan untuk kesalahan yang dikembalikan. |
Keterangan
Fungsi AddIPAddress digunakan untuk menambahkan entri alamat IPv4 baru di komputer lokal. Alamat IPv4 yang ditambahkan oleh fungsi AddIPAddress tidak persisten. Alamat IPv4 hanya ada selama objek adaptor ada. Menghidupkan ulang komputer menghancurkan alamat IPv4, seperti halnya mengatur ulang kartu antarmuka jaringan (NIC) secara manual. Selain itu, peristiwa PnP tertentu dapat menghancurkan alamat.
Untuk membuat alamat IPv4 yang berlanjut, metode EnableStatic dari Win32_NetworkAdapterConfiguration Class dalam kontrol Windows Management Instrumentation (WMI) dapat digunakan. Perintah netsh juga dapat digunakan untuk membuat alamat IPv4 persisten.
Untuk informasi selengkapnya, silakan lihat dokumentasi tentang Netsh.exe dalam dokumentasi Windows Sockets.
Pada Windows Server 2003, Windows XP, dan Windows 2000, jika alamat IPv4 dalam parameter Alamat sudah ada di jaringan, fungsi AddIPAddress mengembalikan NO_ERROR dan alamat IPv4 yang ditambahkan adalah 0.0.0.0.
Pada Windows Vista dan yang lebih baru, jika alamat IPv4 yang diteruskan dalam parameter Alamat sudah ada di jaringan, fungsi AddIPAddress mengembalikan NO_ERROR dan alamat IPv4 duplikat ditambahkan dengan anggota IP_DAD_STATE dalam struktur IP_ADAPTER_UNICAST_ADDRESS diatur ke IpDadStateDuplicate.
Alamat IPv4 yang ditambahkan menggunakan fungsi AddIPAddress nantinya dapat dihapus dengan memanggil fungsi DeleteIPAddress yang melewati parameter NTEContext yang dikembalikan oleh fungsi AddIPAddress .
Untuk informasi tentang jenis data IPAddr dan IPMask , lihat Jenis Data Windows. Untuk mengonversi alamat IPv4 antara notasi desimal putus-putus dan format IPAddr , gunakan fungsi inet_addr dan inet_ntoa .
Pada Windows Vista dan yang lebih baru, fungsi CreateUnicastIpAddressEntry dapat digunakan untuk menambahkan entri alamat IPv4 atau IPv6 unicast baru di komputer lokal.
Contoh
Contoh berikut mengambil tabel alamat IP untuk menentukan indeks antarmuka untuk adaptor pertama, lalu menambahkan alamat IP yang ditentukan pada baris perintah ke adaptor pertama. Alamat IP yang ditambahkan kemudian dihapus.
#pragma comment(lib, "iphlpapi.lib")
#pragma comment(lib, "ws2_32.lib")
#include <winsock2.h>
#include <ws2tcpip.h>
#include <iphlpapi.h>
#include <stdio.h>
#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)
{
/* Variables used by GetIpAddrTable */
PMIB_IPADDRTABLE pIPAddrTable;
DWORD dwSize = 0;
DWORD dwRetVal = 0;
IN_ADDR IPAddr;
DWORD ifIndex;
/* IPv4 address and subnet mask we will be adding */
UINT iaIPAddress;
UINT iaIPMask;
/* Variables where handles to the added IP are returned */
ULONG NTEContext = 0;
ULONG NTEInstance = 0;
/* Variables used to return error message */
LPVOID lpMsgBuf;
// Validate the parameters
if (argc != 3) {
printf("usage: %s IPAddress SubnetMask\n", argv[0]);
exit(1);
}
iaIPAddress = inet_addr(argv[1]);
if (iaIPAddress == INADDR_NONE) {
printf("usage: %s IPAddress SubnetMask\n", argv[0]);
exit(1);
}
iaIPMask = inet_addr(argv[2]);
if (iaIPMask == INADDR_NONE) {
printf("usage: %s IPAddress SubnetMask\n", argv[0]);
exit(1);
}
// Before calling AddIPAddress we use GetIpAddrTable to get
// an adapter to which we can add the IP.
pIPAddrTable = (MIB_IPADDRTABLE *) MALLOC(sizeof (MIB_IPADDRTABLE));
if (pIPAddrTable == NULL) {
printf("Error allocating memory needed to call GetIpAddrTable\n");
exit (1);
}
else {
dwSize = 0;
// Make an initial call to GetIpAddrTable to get the
// necessary size into the dwSize variable
if (GetIpAddrTable(pIPAddrTable, &dwSize, 0) ==
ERROR_INSUFFICIENT_BUFFER) {
FREE(pIPAddrTable);
pIPAddrTable = (MIB_IPADDRTABLE *) MALLOC(dwSize);
}
if (pIPAddrTable == NULL) {
printf("Memory allocation failed for GetIpAddrTable\n");
exit(1);
}
}
// Make a second call to GetIpAddrTable to get the
// actual data we want
if ((dwRetVal = GetIpAddrTable(pIPAddrTable, &dwSize, 0)) == NO_ERROR) {
// Save the interface index to use for adding an IP address
ifIndex = pIPAddrTable->table[0].dwIndex;
printf("\n\tInterface Index:\t%ld\n", ifIndex);
IPAddr.S_un.S_addr = (u_long) pIPAddrTable->table[0].dwAddr;
printf("\tIP Address: \t%s (%lu%)\n", inet_ntoa(IPAddr),
pIPAddrTable->table[0].dwAddr);
IPAddr.S_un.S_addr = (u_long) pIPAddrTable->table[0].dwMask;
printf("\tSubnet Mask: \t%s (%lu%)\n", inet_ntoa(IPAddr),
pIPAddrTable->table[0].dwMask);
IPAddr.S_un.S_addr = (u_long) pIPAddrTable->table[0].dwBCastAddr;
printf("\tBroadCast Address:\t%s (%lu%)\n", inet_ntoa(IPAddr),
pIPAddrTable->table[0].dwBCastAddr);
printf("\tReassembly size: \t%lu\n\n",
pIPAddrTable->table[0].dwReasmSize);
} else {
printf("Call to GetIpAddrTable failed with error %d.\n", dwRetVal);
if (pIPAddrTable)
FREE(pIPAddrTable);
exit(1);
}
if (pIPAddrTable) {
FREE(pIPAddrTable);
pIPAddrTable = NULL;
}
if ((dwRetVal = AddIPAddress(iaIPAddress,
iaIPMask,
ifIndex,
&NTEContext, &NTEInstance)) == NO_ERROR) {
printf("\tIPv4 address %s was successfully added.\n", argv[1]);
} else {
printf("AddIPAddress failed with error: %d\n", dwRetVal);
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);
exit(1);
}
}
// Delete the IP we just added using the NTEContext
// variable where the handle was returned
if ((dwRetVal = DeleteIPAddress(NTEContext)) == NO_ERROR) {
printf("\tIPv4 address %s was successfully deleted.\n", argv[1]);
} else {
printf("\tDeleteIPAddress failed with error: %d\n", dwRetVal);
exit(1);
}
exit(0);
}
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 |