AddIPAddress-Funktion (iphlpapi.h)
Die AddIPAddress-Funktion fügt dem angegebenen Adapter die angegebene IPv4-Adresse hinzu.
Syntax
IPHLPAPI_DLL_LINKAGE DWORD AddIPAddress(
[in] IPAddr Address,
[in] IPMask IpMask,
[in] DWORD IfIndex,
[out] PULONG NTEContext,
[out] PULONG NTEInstance
);
Parameter
[in] Address
Die IPv4-Adresse, die dem Adapter in Form einer IPAddr-Struktur hinzugefügt werden soll.
[in] IpMask
Die Subnetzmaske für die im Address-Parameter angegebene IPv4-Adresse. Der IPMask-Parameter verwendet das gleiche Format wie eine IPAddr-Struktur .
[in] IfIndex
Der Index des Adapters, auf dem die IPv4-Adresse hinzugefügt werden soll.
[out] NTEContext
Ein Zeiger auf eine ULONG-Variable . Bei erfolgreicher Rückgabe zeigt dieser Parameter auf den NTE-Kontext (Net Table Entry) für die hinzugefügte IPv4-Adresse. Der Aufrufer kann diesen Kontext später in einem Aufruf der DeleteIPAddress-Funktion verwenden.
[out] NTEInstance
Ein Zeiger auf eine ULONG-Variable . Bei erfolgreicher Rückgabe verweist dieser Parameter auf die NTE-instance für die hinzugefügte IPv4-Adresse.
Rückgabewert
Wenn die Funktion erfolgreich ist, wird der Rückgabewert NO_ERROR.
Wenn die Funktion fehlschlägt, ist der Rückgabewert einer der folgenden Fehlercodes.
| Rückgabecode | Beschreibung |
|---|---|
|
Der vom IfIndex-Parameter angegebene Adapter ist nicht vorhanden. |
|
Die hinzuzufügende IPv4-Adresse, die im Address-Parameter angegeben ist, ist bereits vorhanden. |
|
Ein allgemeiner Fehler. Dieser Fehler wird für einige Werte zurückgegeben, die im Address-Parameter angegeben sind, z. B. für eine IPv4-Adresse, die normalerweise als Broadcastadresse betrachtet wird. |
|
Der Benutzer, der versucht, den Funktionsaufruf zu tätigen, ist kein Administrator. |
|
Mindestens einer der Parameter ist ungültig. Dieser Fehler wird zurückgegeben, wenn die Parameter NTEContext oder NTEInstanceNULL sind. Dieser Fehler wird auch zurückgegeben, wenn die im Address-Parameter angegebene IP-Adresse mit dem im IfIndex-Parameter angegebenen Schnittstellenindex inkonsistent ist (z. B. eine Loopbackadresse auf einer Nicht-Loopback-Schnittstelle). |
|
Der Funktionsaufruf wird in der Windows-Version, unter der er ausgeführt wurde, nicht unterstützt. |
|
Verwenden Sie FormatMessage , um die Meldungszeichenfolge für den zurückgegebenen Fehler abzurufen. |
Hinweise
Die AddIPAddress-Funktion wird verwendet, um einen neuen IPv4-Adresseintrag auf einem lokalen Computer hinzuzufügen. Die von der AddIPAddress-Funktion hinzugefügte IPv4-Adresse ist nicht persistent. Die IPv4-Adresse ist nur solange vorhanden, wie das Adapterobjekt vorhanden ist. Durch einen Neustart des Computers wird die IPv4-Adresse zerstört, ebenso wie das manuelle Zurücksetzen der Netzwerkschnittstelle Karte (NIC). Außerdem können bestimmte PnP-Ereignisse die Adresse zerstören.
Um eine IPv4-Adresse zu erstellen, die beibehalten wird, kann die EnableStatic-Methode der Win32_NetworkAdapterConfiguration-Klasse in den WMI-Steuerelementen (Windows Management Instrumentation) verwendet werden. Die netsh-Befehle können auch verwendet werden, um eine persistente IPv4-Adresse zu erstellen.
Weitere Informationen finden Sie in der Dokumentation zu Netsh.exe in der Windows Sockets-Dokumentation.
Wenn die IPv4-Adresse im Address-Parameter unter Windows Server 2003, Windows XP und Windows 2000 bereits im Netzwerk vorhanden ist, gibt die AddIPAddress-FunktionNO_ERROR zurück, und die hinzugefügte IPv4-Adresse ist 0.0.0.0.
Wenn die im Parameter Address übergebene IPv4-Adresse unter Windows Vista und höher bereits im Netzwerk vorhanden ist, gibt die AddIPAddress-FunktionNO_ERROR zurück, und die doppelte IPv4-Adresse wird mit dem IP_DAD_STATE-Member in der IP_ADAPTER_UNICAST_ADDRESS-Struktur hinzugefügt, die auf IpDadStateDuplicate festgelegt ist.
Eine IPv4-Adresse, die mithilfe der AddIPAddress-Funktion hinzugefügt wird, kann später gelöscht werden, indem die DeleteIPAddress-Funktion aufgerufen wird, indem der NTEContext-Parameter übergeben wird, der von der AddIPAddress-Funktion zurückgegeben wird.
Informationen zu den Datentypen IPAddr und IPMask finden Sie unter Windows-Datentypen. Um eine IPv4-Adresse zwischen gepunkteter Dezimalschreibweise und IPAddr-Format zu konvertieren, verwenden Sie die Funktionen inet_addr und inet_ntoa .
Unter Windows Vista und höher kann die CreateUnicastIpAddressEntry-Funktion verwendet werden, um einen neuen Unicast-IPv4- oder IPv6-Adresseintrag auf einem lokalen Computer hinzuzufügen.
Beispiele
Im folgenden Beispiel wird die IP-Adresstabelle abgerufen, um den Schnittstellenindex für den ersten Adapter zu bestimmen. Anschließend wird dem ersten Adapter die in der Befehlszeile angegebene IP-Adresse hinzugefügt. Die hinzugefügte IP-Adresse wird dann gelöscht.
#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);
}
Anforderungen
| Unterstützte Mindestversion (Client) | Windows 2000 Professional [nur Desktop-Apps] |
| Unterstützte Mindestversion (Server) | Windows 2000 Server [nur Desktop-Apps] |
| Zielplattform | Windows |
| Kopfzeile | iphlpapi.h |
| Bibliothek | Iphlpapi.lib |
| DLL | Iphlpapi.dll |