IcmpSendEcho2-Funktion (icmpapi.h)

Die IcmpSendEcho2-Funktion sendet eine IPv4 ICMP-Echoanforderung und gibt entweder sofort zurück (wenn Event oder ApcRoutine nicht NULL ist) oder nach dem angegebenen Timeout zurück. Der ReplyBuffer enthält ggf. die ICMP-Echoantworten.

Syntax

IPHLPAPI_DLL_LINKAGE DWORD IcmpSendEcho2(
  [in]           HANDLE                 IcmpHandle,
  [in, optional] HANDLE                 Event,
  [in, optional] PIO_APC_ROUTINE        ApcRoutine,
  [in, optional] PVOID                  ApcContext,
  [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, optional] Event

Ein Ereignis, das (höchstens einmal) signalisiert werden soll, wenn eine ICMP-Antwort eintrifft. Wenn dieser Parameter angegeben ist, ist ein Handle für ein gültiges Ereignisobjekt erforderlich. Verwenden Sie die Funktion CreateEvent oder CreateEventEx , um dieses Ereignisobjekt zu erstellen.

Weitere Informationen zur Verwendung von Ereignissen finden Sie unter Ereignisobjekte.

[in, optional] ApcRoutine

Die Routine, die aufgerufen wird, wenn sich der aufrufende Thread in einem warnbaren Thread befindet und eine ICMPv4-Antwort eingeht. PIO_APC_ROUTINE_DEFINED müssen definiert werden, damit der Datentyp für diesen Parameter PIO_APC_ROUTINE statt FARPROC wird.

[in, optional] ApcContext

Ein optionaler Parameter, der an die Rückrufroutine übergeben wird, die im ApcRoutine-Parameter (höchstens einmal) angegeben ist, wenn eine ICMP-Antwort eingeht oder ein Fehler auftritt.

[in] DestinationAddress

Das IPv4-Ziel 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 die der RequestData-Parameter verweist.

[in, optional] RequestOptions

Ein Zeiger auf die IP-Headeroptionen für die Anforderung in Form einer IP_OPTION_INFORMATION-Struktur .

Dieser Parameter kann NULL sein, wenn keine IP-Headeroptionen angegeben werden müssen.

[out] ReplyBuffer

Ein Zeiger auf einen Puffer, der alle Antworten auf die Anforderung enthält. Nach der Rückgabe enthält der Puffer ein Array von ICMP_ECHO_REPLY Strukturen gefolgt von Optionen und Daten.

Der Puffer muss groß genug sein, um mindestens eine ICMP_ECHO_REPLY-Struktur zu enthalten, plus RequestSize-Datenbytes sowie weitere 8 Bytes Daten (die Größe einer ICMP-Fehlermeldung).

[in] ReplySize

Die zugeordnete Größe des Antwortpuffers in Bytes.

Der Puffer muss groß genug sein, um mindestens eine ICMP_ECHO_REPLY-Struktur zu enthalten, plus RequestSize-Datenbytes sowie weitere 8 Bytes Daten (die Größe einer ICMP-Fehlermeldung).

[in] Timeout

Die Zeit in Millisekunden, um auf Antworten zu warten.

Rückgabewert

Beim synchronen Aufruf gibt die IcmpSendEcho2-Funktion die Anzahl der empfangenen und in ReplyBuffer gespeicherten Antworten zurück. Wenn der Rückgabewert 0 ist, rufen Sie für erweiterte Fehlerinformationen GetLastError auf.

Beim asynchronen Aufruf gibt die IcmpSendEcho2-Funktion null zurück. Ein nachfolgender Aufruf von GetLastError gibt erweiterten Fehlercode zurück, ERROR_IO_PENDING , um anzugeben, dass der Vorgang ausgeführt wird. Die Ergebnisse können später abgerufen werden, wenn das im Ereignisparameter angegebene Ereignis oder die Rückruffunktion im ApcRoutine-Parameter aufgerufen wird.

Wenn der Rückgabewert 0 ist, rufen Sie für erweiterte Fehlerinformationen GetLastError auf.

Wenn die Funktion fehlschlägt, kann der von GetLastError zurückgegebene erweiterte Fehlercode einer der folgenden Werte sein.

Hinweise

Die IcmpSendEcho2-Funktion wird synchron aufgerufen, wenn die Parameter ApcRoutine oder EventNULL sind. Wenn der Rückgabewert synchron aufgerufen wird, enthält der Rückgabewert die Anzahl der empfangenen und gespeicherten Antworten in ReplyBuffer , nachdem auf die im Timeout-Parameter angegebene Zeit gewartet wurde. Wenn der Rückgabewert 0 ist, rufen Sie für erweiterte Fehlerinformationen GetLastError auf.

Die IcmpSendEcho2-Funktion wird asynchron aufgerufen, wenn entweder die Parameter ApcRoutine oder Event angegeben werden. Beim asynchronen Aufruf sind die Parameter ReplyBuffer und ReplySize erforderlich, um die Antwort zu akzeptieren. ICMP-Antwortdaten werden in den bereitgestellten ReplyBuffer kopiert, und die Anwendung wird signalisiert (wenn der Event-Parameter angegeben ist) oder die Rückruffunktion aufgerufen (wenn der ApcRoutine-Parameter angegeben ist). Die Anwendung muss die Daten analysieren, auf die vom ReplyBuffer-Parameter mit der IcmpParseReplies-Funktion verwiesen wird.

Wenn der Event-Parameter angegeben wird, wird die IcmpSendEcho2-Funktion asynchron aufgerufen. Das im Ereignisparameter angegebene Ereignis wird (höchstens einmal) signalisiert, wenn eine ICMP-Antwort eingeht. Verwenden Sie die Funktion CreateEvent oder CreateEventEx , um dieses Ereignisobjekt zu erstellen.

Wenn der ApcRoutine-Parameter angegeben wird, wird die IcmpSendEcho2-Funktion asynchron aufgerufen. Der ApcRoutine-Parameter sollte auf eine benutzerdefinierte Rückruffunktion verweisen. Die im ApcRoutine-Parameter angegebene Rückruffunktion wird (höchstens einmal) aufgerufen, wenn eine ICMP-Antwort eingeht. Der Aufruf der Rückruffunktion, die im Parameter ApcRoutine angegeben ist, wird serialisiert.

Wenn sowohl der Event - als auch der ApcRoutine-Parameter angegeben sind, wird das im Event-Parameter angegebene Ereignis (höchstens einmal) signalisiert, wenn eine ICMP-Antwort eingeht, aber die im Parameter ApcRoutine angegebene Rückruffunktion wird ignoriert.

Jede Anwendung, die die IcmpSendEcho2-Funktion asynchron mit dem Parameter ApcRoutine aufruft, muss PIO_APC_ROUTINE_DEFINED definieren, um den Datentyp für den ApcRoutine-Parameter anstelle von FARPROC auf PIO_APC_ROUTINE zu erzwingen.

Die Rückruffunktion, auf die die ApcRoutine verweist, muss als Funktion des Typs VOID mit der folgenden Syntax definiert werden:

typedef
VOID WINAPI
(*PIO_APC_ROUTINE) (
    IN PVOID ApcContext,
    IN PIO_STATUS_BLOCK IoStatusBlock,
    IN ULONG Reserved
    );

Zu den Parametern, die an die Rückruffunktion übergeben werden, gehören Folgendes:

Die im ApcRoutine-Parameter angegebene Rückruffunktion muss im selben Prozess implementiert werden wie die Anwendung, die die IcmpSendEcho2-Funktion aufruft . Wenn sich die Rückruffunktion in einer separaten DLL befindet, sollte die DLL geladen werden, bevor die IcmpSendEcho2-Funktion aufgerufen wird.

Die IcmpSendEcho2-Funktion wird aus Iphlpapi.dllexportiert.

Verwenden Sie für IPv6 die Funktionen Icmp6CreateFile, Icmp6SendEcho2 und Icmp6ParseReplies .

Die include-Anweisung für die Iphlpapi.h Headerdatei muss vor der -Anweisung für die Icmpapi.h Headerdatei platziert werden.

Beispiel

Im folgenden Beispiel wird die IcmpSendEcho2-Funktion synchron aufgerufen. Das Beispiel sendet eine ICMP-Echoanforderung an die IP-Adresse, die in der Befehlszeile angegeben ist, und gibt die informationen aus der ersten Antwort aus.

#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;
    DWORD dwError = 0;
    char SendData[] = "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;
    }

    // Allocate space for a single reply.
    ReplySize = sizeof (ICMP_ECHO_REPLY) + sizeof (SendData) + 8;
    ReplyBuffer = (VOID *) malloc(ReplySize);
    if (ReplyBuffer == NULL) {
        printf("\tUnable to allocate memory for reply buffer\n");
        return 1;
    }

    dwRetVal = IcmpSendEcho2(hIcmpFile, NULL, NULL, NULL,
                             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  ", pEchoReply->Status);
        switch (pEchoReply->Status) {
        case IP_DEST_HOST_UNREACHABLE:
            printf("(Destination host was unreachable)\n");
            break;
        case IP_DEST_NET_UNREACHABLE:
            printf("(Destination Network was unreachable)\n");
            break;
        case IP_REQ_TIMED_OUT:
            printf("(Request timed out)\n");
            break;
        default:
            printf("\n");
            break;
        }

        printf("\t  Roundtrip time = %ld milliseconds\n",
               pEchoReply->RoundTripTime);
    } else {
        printf("Call to IcmpSendEcho2 failed.\n");
        dwError = GetLastError();
        switch (dwError) {
        case IP_BUF_TOO_SMALL:
            printf("\tReplyBufferSize too small\n");
            break;
        case IP_REQ_TIMED_OUT:
            printf("\tRequest timed out\n");
            break;
        default:
            printf("\tExtended error returned: %ld\n", dwError);
            break;
        }
        return 1;
    }
    return 0;
}

Anforderungen

Weitere Informationen

• CreateEvent
• CreateEventEx
• Ereignisobjekte
• GetLastError
• ICMP_ECHO_REPLY
• IP_OPTION_INFORMATION
• IP_OPTION_INFORMATION32
• IPAddr
• Icmp6CreateFile
• Icmp6ParseReplies
• Icmp6SendEcho2
• IcmpCloseHandle
• IcmpCreateFile
• IcmpParseReplies
• IcmpSendEcho
• IcmpSendEcho2Ex