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.
| Rückgabecode | Beschreibung |
|---|---|
| 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_IO_PENDING | Der Vorgang wird ausgeführt. Dieser Wert wird durch einen erfolgreichen asynchronen Aufruf von IcmpSendEcho2 zurückgegeben und ist kein Hinweis auf einen Fehler. |
| 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 auf dem lokalen Computer kein IPv4-Stapel befindet. |
| IP_BUF_TOO_SMALL | Die Im ReplySize-Parameter angegebene Größe des ReplyBuffer war zu klein. |
| Andere | Verwenden Sie FormatMessage , um die Nachrichtenzeichenfolge für den zurückgegebenen Fehler abzurufen. |
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.
Hinweis
PIO_APC_ROUTINE_DEFINED müssen definiert werden, bevor die Headerdatei "Icmpapi.h " enthalten ist.
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:
| Parameter | BESCHREIBUNG |
|---|---|
| IN PVOID ApcContext | Der AppContext-Parameter , der an die IcmpSendEcho2-Funktion übergeben wird. Dieser Parameter kann von der Anwendung verwendet werden, um die IcmpSendEcho2-Anforderung zu identifizieren, auf die die Rückruffunktion reagiert. |
| IN PIO_STATUS_BLOCK IoStatusBlock | Ein Zeiger auf eine IO_STATUS_BLOCK. Diese Variable enthält die endgültige Vervollständigung status und Informationen zum Vorgang. Die Anzahl der tatsächlich empfangenen Bytes in der Antwort wird im Member Information der IO_STATUS_BLOCK-Struktur zurückgegeben. Die IO_STATUS_BLOCK-Struktur ist in der Wdm.h Headerdatei definiert. |
| IN ULONG Reserviert | Dieser Parameter ist reserviert. |
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
| Anforderung | Wert |
|---|---|
| Unterstützte Mindestversion (Client) | Windows 2000 Professional [Desktop-Apps | UWP-Apps] |
| Unterstützte Mindestversion (Server) | Windows 2000 Server [Desktop-Apps | UWP-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 |