Freigeben über


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
ERROR_INSUFFICIENT_BUFFER
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.
ERROR_INVALID_PARAMETER
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.
ERROR_NOT_ENOUGH_MEMORY
Es ist nicht genügend Arbeitsspeicher verfügbar, um den Vorgang abzuschließen.
ERROR_NOT_SUPPORTED
Die Anforderung wird nicht unterstützt. Dieser Fehler wird zurückgegeben, wenn sich kein IPv4-Stapel auf dem lokalen Computer befindet.
IP_BUF_TOO_SMALL
Die Größe des im ReplySize-Parameter angegebenen ReplyBuffer war zu klein.
Andere
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

Weitere Informationen

GetLastError

ICMP_ECHO_REPLY

IPAddr

IP_OPTION_INFORMATION

IP_OPTION_INFORMATION32

Icmp6CreateFile

Icmp6ParseReplies

Icmp6SendEcho2

IcmpCloseHandle

IcmpCreateFile

IcmpParseReplies

IcmpSendEcho2

IcmpSendEcho2Ex