SendARP-Funktion (iphlpapi.h)
Die SendARP-Funktion sendet eine ARP-Anforderung (Address Resolution Protocol), um die physische Adresse abzurufen, die der angegebenen IPv4-Zieladresse entspricht.
Syntax
IPHLPAPI_DLL_LINKAGE DWORD SendARP(
[in] IPAddr DestIP,
[in] IPAddr SrcIP,
[out] PVOID pMacAddr,
[in, out] PULONG PhyAddrLen
);
Parameter
[in] DestIP
Die IPv4-Zieladresse in Form einer IPAddr-Struktur . Die ARP-Anforderung versucht, die physische Adresse abzurufen, die dieser IPv4-Adresse entspricht.
[in] SrcIP
Die IPv4-Quelladresse des Absenders in Form einer IPAddr-Struktur . Dieser Parameter ist optional und wird verwendet, um die Schnittstelle auszuwählen, über die die Anforderung für den ARP-Eintrag gesendet werden soll. Der Aufrufer kann null angeben, die der INADDR_ANY IPv4-Adresse für diesen Parameter entspricht.
[out] pMacAddr
Ein Zeiger auf ein Array von ULONG-Variablen . Dieses Array muss über mindestens zwei ULONG-Elemente verfügen, um eine physische Adresse des Ethernet- oder Tokenrings zu enthalten. Die ersten sechs Bytes dieses Arrays erhalten die physische Adresse, die der durch den DestIP-Parameter angegebenen IPv4-Adresse entspricht.
[in, out] PhyAddrLen
Bei der Eingabe ein Zeiger auf einen ULONG-Wert , der die maximale Puffergröße in Bytes angibt, hat die Anwendung für den Empfang der physischen Adresse oder mac-Adresse reserviert. Die Puffergröße sollte mindestens 6 Bytes für eine physische Adresse eines Ethernet- oder Tokenrings betragen.
Der pMacAddr-Parameter zeigt auf den Puffer, auf den die physische Adresse empfangen werden soll.
Bei erfolgreicher Ausgabe zeigt dieser Parameter auf einen Wert, der die Anzahl der Bytes angibt, die in den Puffer geschrieben werden, auf den der pMacAddr verweist.
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 Netzwerkname wurde nicht gefunden.“ Dieser Fehler wird unter Windows Vista und später zurückgegeben, wenn keine ARP-Antwort auf die SendARP-Anforderung empfangen wurde. Dieser Fehler tritt auf, wenn die IPv4-Zieladresse nicht erreicht werden konnte, weil sie sich nicht im selben Subnetz befindet oder der Zielcomputer nicht ausgeführt wird. |
|
Der Dateiname ist zu lang. Dieser Fehler wird unter Windows Vista zurückgegeben, wenn der ULONG-Wert , auf den der PhyAddrLen-Parameter verweist, kleiner als 6 ist, die größe, die zum Speichern einer vollständigen physischen Adresse erforderlich ist. |
|
Ein an das System angeschlossenes Gerät funktioniert nicht. Dieser Fehler wird unter Windows Server 2003 und früher zurückgegeben, wenn keine ARP-Antwort auf die SendARP-Anforderung empfangen wurde. Dieser Fehler kann auftreten, wenn die IPv4-Zieladresse nicht erreicht werden konnte, weil sie sich nicht im selben Subnetz befindet oder der Zielcomputer nicht ausgeführt wird. |
|
Einer der Parameter ist ungültig. Dieser Fehler wird unter Windows Server 2003 und früher zurückgegeben, wenn der pMacAddr - oder PhyAddrLen-Parameter ein NULL-Zeiger ist. |
|
Der angegebene Benutzerpuffer ist für den angeforderten Vorgang ungültig. Dieser Fehler wird unter Windows Server 2003 und früher zurückgegeben, wenn der ULONG-Wert , auf den der PhyAddrLen-Parameter verweist, null ist. |
|
Element wurde nicht gefunden. Dieser Fehler wird unter Windows Vista zurückgegeben, wenn der SrcIp-Parameter keine IPv4-Quelladresse auf einer Schnittstelle auf dem lokalen Computer oder die INADDR_ANY IP-Adresse (eine IPv4-Adresse von 0.0.0.0) angibt. |
|
Die SendARP-Funktion wird vom Betriebssystem, das auf dem lokalen Computer ausgeführt wird, nicht unterstützt. |
|
Wenn die Funktion fehlschlägt, verwenden Sie FormatMessage , um die Nachrichtenzeichenfolge für den zurückgegebenen Fehler abzurufen. |
Hinweise
Die SendARP-Funktion wird verwendet, um die physische Hardwareadresse (manchmal auch als MAC-Adresse bezeichnet) anzufordern, die einer angegebenen IPv4-Zieladresse entspricht. Wenn die angeforderten Informationen nicht in der ARP-Tabelle auf dem lokalen Computer enthalten sind, bewirkt die SendARP-Funktion , dass eine ARP-Anforderung gesendet wird, um die physische Adresse abzurufen. Wenn die Funktion erfolgreich ist, wird die physische Adresse, die der angegebenen IPv4-Zieladresse entspricht, in dem Array zurückgegeben, auf das vom pMacAddr-Parameter verwiesen wird.
Die physische Adresse einer IPv4-Adresse ist nur verfügbar, wenn sich die IPv4-Zieladresse im lokalen Subnetz befindet (die IPv4-Adresse kann direkt ohne Router erreicht werden). Die SendARP-Funktion schlägt fehl, wenn sich die IPv4-Zieladresse nicht im lokalen Subnetz befindet.
Wenn die SendARP-Funktion unter Windows Vista und höher erfolgreich ist, wird die ARP-Tabelle auf dem lokalen Computer mit den Ergebnissen aktualisiert. Wenn die SendARP-Funktion unter Windows Server 2003 und früher erfolgreich ist, ist die ARP-Tabelle auf dem lokalen Computer nicht betroffen.
Die SendARP-Funktion unter Windows Vista und später gibt andere Fehlerrückgabewerte als die SendARP-Funktion unter Windows Server 2003 und früher zurück.
Unter Windows Vista und höher verursacht ein NULL-Zeiger , der als pMacAddr - oder PhyAddrLen-Parameter an die SendARP-Funktion übergeben wird, eine Zugriffsverletzung, und die Anwendung wird beendet. Wenn unter Windows Vista und höher ein Fehler auftritt und ERROR_BAD_NET_NAME, ERROR_BUFFER_OVERFLOW oder ERROR_NOT_FOUND zurückgegeben wird, wird der ULONG-Wert , auf den der PhyAddrLen-Parameter verweist, auf 0 festgelegt. Wenn der ULONG-Wert , auf den der PhyAddrLen-Parameter verweist, unter Windows Vista und höher kleiner als 6 ist, gibt die SendARP-FunktionERROR_BUFFER_OVERFLOW zurück, die angibt, dass der Puffer zum Empfangen der physischen Adresse zu klein ist. Wenn der SrcIp-Parameter eine IPv4-Adresse angibt, die keine Schnittstelle auf dem lokalen Computer ist, gibt die SendARP-Funktion unter Windows Vista und höher ERROR_NOT_FOUND zurück.
Unter Windows Server 2003 und früher gibt ein NULL-Zeiger , der als pMacAddr - oder PhyAddrLen-Parameter an die SendARP-Funktion übergeben wurde , ERROR_INVALID_PARAMETER zurück. Wenn unter Windows Server 2003 und früher ein Fehler auftritt und ERROR_GEN_FAILURE oder ERROR_INVALID_USER_BUFFER zurückgegeben wird, wird der ULONG-Wert , auf den der PhyAddrLen-Parameter verweist, auf null festgelegt. Wenn der ULONG-Wert , auf den der PhyAddrLen-Parameter verweist, unter Windows Server 2003 und früher kleiner als 6 ist, gibt die SendARP-Funktion keinen Fehler zurück, sondern nur einen Teil der Hardwareadresse im Array zurück, auf das der pMacAddr-Parameter verweist. Wenn also der Wert, auf den der PhyAddrLen-Parameter verweist, 4 ist, werden nur die ersten 4 Bytes der Hardwareadresse in dem Array zurückgegeben, auf das der pMacAddr-Parameter verweist. Wenn der SrcIp-Parameter eine IPv4-Adresse angibt, die keine Schnittstelle auf dem lokalen Computer ist, ignoriert die SendARP-Funktion unter Windows Server 2003 und früher den SrcIp-Parameter und verwendet eine IPv4-Adresse auf dem lokalen Computer für die IPv4-Quelladresse.
Die GetIpNetTable-Funktion ruft die ARP-Tabelle auf dem lokalen Computer ab, die IPv4-Adressen physischen Adressen zuordnet.
Die CreateIpNetEntry-Funktion erstellt einen ARP-Eintrag in der ARP-Tabelle auf dem lokalen Computer.
Die DeleteIpNetEntry-Funktion löscht einen ARP-Eintrag aus der ARP-Tabelle auf dem lokalen Computer.
Die SetIpNetEntry-Funktion ändert einen vorhandenen ARP-Eintrag in der ARP-Tabelle auf dem lokalen Computer.
Die FlushIpNetTable-Funktion löscht alle ARP-Einträge für die angegebene Schnittstelle aus der ARP-Tabelle auf dem lokalen Computer.
Unter Windows Vista und höher kann die Funktion ResolveIpNetEntry2 verwendet werden, um die SendARP-Funktion zu ersetzen. Eine ARP-Anforderung wird gesendet, wenn das Adresselement der MIB_IPNET_ROW2-Struktur , das an die ResolveIpNetEntry2-Funktion übergeben wird, eine IPv4-Adresse ist.
Unter Windows Vista kann eine neue Gruppe von Funktionen verwendet werden, um auf die ARP-Tabelleneinträge zuzugreifen, sie zu ändern und zu löschen, wenn das Adresselement der MIB_IPNET_ROW2 Struktur, die an diese Funktionen übergeben wird, eine IPv4-Adresse ist. Zu den neuen Funktionen gehören: GetIpNetTable2, CreateIpNetEntry2, DeleteIpNetEntry2, FlushIpNetTable2 und SetIpNetEntry2.
Informationen zum IPAddr-Datentyp finden Sie unter Windows-Datentypen. Um eine IP-Adresse zwischen gepunkteter Dezimalschreibweise und IPAddr-Format zu konvertieren, verwenden Sie die Funktionen inet_addr und inet_ntoa .
Beispiele
Der folgende Code veranschaulicht, wie Sie die Hardware- oder MAC-Adresse abrufen, die einer angegebenen IPv4-Adresse zugeordnet ist.
#ifndef WIN32_LEAN_AND_MEAN
#define WIN32_LEAN_AND_MEAN
#endif
#include <winsock2.h>
#include <iphlpapi.h>
#include <stdio.h>
#include <stdlib.h>
#pragma comment(lib, "iphlpapi.lib")
#pragma comment(lib, "ws2_32.lib")
void usage(char *pname)
{
printf("Usage: %s [options] ip-address\n", pname);
printf("\t -h \t\thelp\n");
printf("\t -l length \tMAC physical address length to set\n");
printf("\t -s src-ip \tsource IP address\n");
exit(1);
}
int __cdecl main(int argc, char **argv)
{
DWORD dwRetVal;
IPAddr DestIp = 0;
IPAddr SrcIp = 0; /* default for src ip */
ULONG MacAddr[2]; /* for 6-byte hardware addresses */
ULONG PhysAddrLen = 6; /* default to length of six bytes */
char *DestIpString = NULL;
char *SrcIpString = NULL;
BYTE *bPhysAddr;
unsigned int i;
if (argc > 1) {
for (i = 1; i < (unsigned int) argc; i++) {
if ((argv[i][0] == '-') || (argv[i][0] == '/')) {
switch (tolower(argv[i][1])) {
case 'l':
PhysAddrLen = (ULONG) atol(argv[++i]);
break;
case 's':
SrcIpString = argv[++i];
SrcIp = inet_addr(SrcIpString);
break;
case 'h':
default:
usage(argv[0]);
break;
} /* end switch */
} else
DestIpString = argv[i];
} /* end for */
} else
usage(argv[0]);
if (DestIpString == NULL || DestIpString[0] == '\0')
usage(argv[0]);
DestIp = inet_addr(DestIpString);
memset(&MacAddr, 0xff, sizeof (MacAddr));
printf("Sending ARP request for IP address: %s\n", DestIpString);
dwRetVal = SendARP(DestIp, SrcIp, &MacAddr, &PhysAddrLen);
if (dwRetVal == NO_ERROR) {
bPhysAddr = (BYTE *) & MacAddr;
if (PhysAddrLen) {
for (i = 0; i < (int) PhysAddrLen; i++) {
if (i == (PhysAddrLen - 1))
printf("%.2X\n", (int) bPhysAddr[i]);
else
printf("%.2X-", (int) bPhysAddr[i]);
}
} else
printf
("Warning: SendArp completed successfully, but returned length=0\n");
} else {
printf("Error: SendArp failed with error: %d", dwRetVal);
switch (dwRetVal) {
case ERROR_GEN_FAILURE:
printf(" (ERROR_GEN_FAILURE)\n");
break;
case ERROR_INVALID_PARAMETER:
printf(" (ERROR_INVALID_PARAMETER)\n");
break;
case ERROR_INVALID_USER_BUFFER:
printf(" (ERROR_INVALID_USER_BUFFER)\n");
break;
case ERROR_BAD_NET_NAME:
printf(" (ERROR_GEN_FAILURE)\n");
break;
case ERROR_BUFFER_OVERFLOW:
printf(" (ERROR_BUFFER_OVERFLOW)\n");
break;
case ERROR_NOT_FOUND:
printf(" (ERROR_NOT_FOUND)\n");
break;
default:
printf("\n");
break;
}
}
return 0;
}
Anforderungen
| Anforderung | Wert |
|---|---|
| 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 |