IcmpSendEcho-Funktion (icmpapi.h)
Die IcmpSendEcho-Funktion sendet eine IPv4-ICMP-Echoanforderung und gibt alle Echoantwortantworten zurück. Der Aufruf gibt zurück, wenn das Timeout abgelaufen ist oder der Antwortpuffer gefüllt ist.
Syntax
IPHLPAPI_DLL_LINKAGE DWORD IcmpSendEcho(
[in] HANDLE IcmpHandle,
[in] IPAddr DestinationAddress,
[in] LPVOID RequestData,
[in] WORD RequestSize,
[in, optional] PIP_OPTION_INFORMATION RequestOptions,
[out] LPVOID ReplyBuffer,
[in] DWORD ReplySize,
[in] DWORD Timeout
);
Parameter
[in] IcmpHandle
Das geöffnete Handle, das von der IcmpCreateFile-Funktion zurückgegeben wird.
[in] DestinationAddress
Die IPv4-Zieladresse der Echoanforderung in Form einer IPAddr-Struktur .
[in] RequestData
Ein Zeiger auf einen Puffer, der Daten enthält, die in der Anforderung gesendet werden sollen.
[in] RequestSize
Die Größe des Anforderungsdatenpuffers in Bytes, auf den der RequestData-Parameter verweist.
[in, optional] RequestOptions
Ein Zeiger auf die IP-Headeroptionen für die Anforderung in Form einer IP_OPTION_INFORMATION-Struktur . Auf einer 64-Bit-Plattform hat dieser Parameter das Format für eine IP_OPTION_INFORMATION32-Struktur .
Dieser Parameter kann NULL sein, wenn keine IP-Headeroptionen angegeben werden müssen.
[out] ReplyBuffer
Ein Puffer, der alle Antworten auf die Echoanforderung enthält. Bei der Rückgabe enthält der Puffer ein Array von ICMP_ECHO_REPLY Strukturen, gefolgt von den Optionen und Daten für die Antworten. Der Puffer sollte groß genug sein, um mindestens eine ICMP_ECHO_REPLY-Struktur plus RequestSize-Datenbytes zu enthalten.
[in] ReplySize
Die zugeordnete Größe des Antwortpuffers in Bytes. Der Puffer sollte groß genug sein, um mindestens eine ICMP_ECHO_REPLY-Struktur plus RequestSize-Datenbytes zu enthalten.
Dieser Puffer sollte auch groß genug sein, um auch 8 weitere Bytes an Daten zu enthalten (die Größe einer ICMP-Fehlermeldung).
[in] Timeout
Die Zeit in Millisekunden, um auf Antworten zu warten.
Rückgabewert
Die IcmpSendEcho-Funktion gibt die Anzahl der ICMP_ECHO_REPLY strukturen zurück, die im ReplyBuffer gespeichert sind. Die status jeder Antwort ist in der -Struktur enthalten. Wenn der Rückgabewert null ist, rufen Sie GetLastError auf, um weitere Fehlerinformationen zu erhalten.
Wenn die Funktion fehlschlägt, kann der von GetLastError zurückgegebene erweiterte Fehlercode einer der folgenden Werte sein.
| Rückgabecode | Beschreibung |
|---|---|
|
Der an einen Systemaufruf weitergegebene Datenbereich ist zu klein. Dieser Fehler wird zurückgegeben, wenn der ReplySize-Parameter angibt, dass der Puffer, auf den der ReplyBuffer-Parameter verweist, zu klein ist. |
|
Es wurde ein ungültiger Parameter an die Funktion übergeben. Dieser Fehler wird zurückgegeben, wenn der IcmpHandle-Parameter ein ungültiges Handle enthält. Dieser Fehler kann auch zurückgegeben werden, wenn der ReplySize-Parameter einen Wert angibt, der kleiner als die Größe einer ICMP_ECHO_REPLY-Struktur ist. |
|
Es ist nicht genügend Arbeitsspeicher verfügbar, um den Vorgang abzuschließen. |
|
Die Anforderung wird nicht unterstützt. Dieser Fehler wird zurückgegeben, wenn sich kein IPv4-Stapel auf dem lokalen Computer befindet. |
|
Die Größe des im ReplySize-Parameter angegebenen ReplyBuffer war zu klein. |
|
Verwenden Sie FormatMessage , um die Meldungszeichenfolge für den zurückgegebenen Fehler abzurufen. |
Hinweise
Die IcmpSendEcho-Funktion sendet eine ICMP-Echoanforderung an die angegebene Adresse und gibt die Anzahl der empfangenen und in ReplyBuffer gespeicherten Antworten zurück. Die IcmpSendEcho-Funktion ist eine synchrone Funktion und gibt nach dem Warten auf die im Timeout-Parameter für eine Antwort angegebene Zeit zurück. Wenn der Rückgabewert null ist, rufen Sie GetLastError für erweiterte Fehlerinformationen auf.
Die Funktionen IcmpSendEcho2 und IcmpSendEcho2Ex sind eine erweiterte Version von IcmpSendEcho , die den asynchronen Betrieb unterstützt. Die IcmpSendEcho2Ex-Funktion ermöglicht auch die Angabe der Quell-IP-Adresse. Dieses Feature ist auf Computern mit mehreren Netzwerkschnittstellen nützlich.
Verwenden Sie für IPv6 die Funktionen Icmp6CreateFile, Icmp6SendEcho2 und Icmp6ParseReplies .
Die IcmpSendEcho-Funktion wird aus dem Icmp.dll unter Windows 2000 exportiert. Die IcmpSendEcho-Funktion wird aus dem Iphlpapi.dll unter Windows XP und höher exportiert. Die Windows-Versionsprüfung wird für die Verwendung dieser Funktion nicht empfohlen. Anwendungen, die Portabilität mit dieser Funktion in Windows 2000, Windows XP, Windows Server 2003 und höher erfordern, sollten weder statisch mit der Datei Icmp.lib noch mit der Datei Iphlpapi.lib verknüpft werden. Stattdessen sollte die Anwendung überprüfen, ob IcmpSendEcho im Iphlpapi.dll mit Aufrufen von LoadLibrary und GetProcAddress vorhanden ist. Andernfalls sollte die Anwendung überprüfen, ob IcmpSendEcho im Icmp.dll mit Aufrufen von LoadLibrary und GetProcAddress vorhanden ist.
Beachten Sie, dass die include-Direktive für die Headerdatei Iphlpapi.h vor der Headerdatei Icmpapi.h platziert werden muss.
Beispiele
Im folgenden Beispiel wird eine ICMP-Echoanforderung an die in der Befehlszeile angegebene IP-Adresse gesendet und die von der ersten Antwort empfangenen Informationen ausgegeben.
#include <winsock2.h>
#include <iphlpapi.h>
#include <icmpapi.h>
#include <stdio.h>
#pragma comment(lib, "iphlpapi.lib")
#pragma comment(lib, "ws2_32.lib")
int __cdecl main(int argc, char **argv) {
// Declare and initialize variables
HANDLE hIcmpFile;
unsigned long ipaddr = INADDR_NONE;
DWORD dwRetVal = 0;
char SendData[32] = "Data Buffer";
LPVOID ReplyBuffer = NULL;
DWORD ReplySize = 0;
// Validate the parameters
if (argc != 2) {
printf("usage: %s IP address\n", argv[0]);
return 1;
}
ipaddr = inet_addr(argv[1]);
if (ipaddr == INADDR_NONE) {
printf("usage: %s IP address\n", argv[0]);
return 1;
}
hIcmpFile = IcmpCreateFile();
if (hIcmpFile == INVALID_HANDLE_VALUE) {
printf("\tUnable to open handle.\n");
printf("IcmpCreatefile returned error: %ld\n", GetLastError() );
return 1;
}
ReplySize = sizeof(ICMP_ECHO_REPLY) + sizeof(SendData);
ReplyBuffer = (VOID*) malloc(ReplySize);
if (ReplyBuffer == NULL) {
printf("\tUnable to allocate memory\n");
return 1;
}
dwRetVal = IcmpSendEcho(hIcmpFile, ipaddr, SendData, sizeof(SendData),
NULL, ReplyBuffer, ReplySize, 1000);
if (dwRetVal != 0) {
PICMP_ECHO_REPLY pEchoReply = (PICMP_ECHO_REPLY)ReplyBuffer;
struct in_addr ReplyAddr;
ReplyAddr.S_un.S_addr = pEchoReply->Address;
printf("\tSent icmp message to %s\n", argv[1]);
if (dwRetVal > 1) {
printf("\tReceived %ld icmp message responses\n", dwRetVal);
printf("\tInformation from the first response:\n");
}
else {
printf("\tReceived %ld icmp message response\n", dwRetVal);
printf("\tInformation from this response:\n");
}
printf("\t Received from %s\n", inet_ntoa( ReplyAddr ) );
printf("\t Status = %ld\n",
pEchoReply->Status);
printf("\t Roundtrip time = %ld milliseconds\n",
pEchoReply->RoundTripTime);
}
else {
printf("\tCall to IcmpSendEcho failed.\n");
printf("\tIcmpSendEcho returned error: %ld\n", GetLastError() );
return 1;
}
return 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 | icmpapi.h |
| Bibliothek | Iphlpapi.lib |
| DLL | Iphlpapi.dll unter Windows Server 2008, Windows Vista, Windows Server 2003 und Windows XP; Icmp.dll unter Windows 2000 Server und Windows 2000 Professional |