IcmpSendEcho2Ex-Funktion (icmpapi.h)
Die IcmpSendEcho2Ex-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-Antworten.
Syntax
IPHLPAPI_DLL_LINKAGE DWORD IcmpSendEcho2Ex(
[in] HANDLE IcmpHandle,
[in, optional] HANDLE Event,
[in, optional] PIO_APC_ROUTINE ApcRoutine,
[in, optional] PVOID ApcContext,
[in] IPAddr SourceAddress,
[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
Ein geöffnetes Handle, das von der ICMPCreateFile-Funktion zurückgegeben wird.
[in, optional] Event
Ein Ereignis, das 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 ICMP-Antwort eingeht. PIO_APC_ROUTINE_DEFINED muss definiert werden, um zu erzwingen, dass der Datentyp für diesen Parameter PIO_APC_ROUTINE und nicht FARPROC.
[in, optional] ApcContext
Ein optionaler Parameter, der an die im ApcRoutine-Parameter angegebene Rückrufroutine übergeben wird, wenn eine ICMP-Antwort eingeht oder ein Fehler auftritt.
[in] SourceAddress
Die IPv4-Quelladresse, an der die Echoanforderung ausstellen soll. Diese Adresse ist in Form einer IPAddr-Struktur .
[in] DestinationAddress
Die IPv4-Zieladresse für die Echoanforderung. Diese Adresse ist 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 . Auf einer 64-Bit-Plattform befindet sich dieser Parameter in der Form für eine IP_OPTION_INFORMATION32-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 plus RequestSize-Datenbytes aufzunehmen.
Dieser Puffer sollte auch groß genug sein, um auch 8 weitere Bytes an Daten (die Größe einer ICMP-Fehlermeldung) plus Speicherplatz für eine IO_STATUS_BLOCK-Struktur aufzunehmen.
[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 aufzunehmen.
Dieser Puffer sollte auch groß genug sein, um auch 8 weitere Bytes an Daten (die Größe einer ICMP-Fehlermeldung) plus Speicherplatz für eine IO_STATUS_BLOCK-Struktur aufzunehmen.
[in] Timeout
Die Zeit in Millisekunden, um auf Antworten zu warten.
Rückgabewert
Beim synchronen Aufruf gibt die IcmpSendEcho2Ex-Funktion die Anzahl der empfangenen und in ReplyBuffer gespeicherten Antworten zurück. Wenn der Rückgabewert 0 ist, rufen Sie GetLastError für erweiterte Fehlerinformationen auf.
Beim asynchronen Aufruf gibt die IcmpSendEcho2Ex-Funktion ERROR_IO_PENDING zurück, 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 GetLastError für erweiterte Fehlerinformationen auf.
Wenn die Funktion fehlschlägt, kann der von GetLastError zurückgegebene erweiterte Fehlercode einer der folgenden Werte sein.
| Rückgabecode | Beschreibung |
|---|---|
|
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. |
|
Der Vorgang wird ausgeführt. Dieser Wert wird durch einen erfolgreichen asynchronen Aufruf von IcmpSendEcho2Ex zurückgegeben und ist kein Hinweis auf einen Fehler. |
|
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 auf dem lokalen Computer kein IPv4-Stapel befindet. |
|
Die Im ReplySize-Parameter angegebene Größe des ReplyBuffer war zu klein. |
|
Verwenden Sie FormatMessage , um die Nachrichtenzeichenfolge für den zurückgegebenen Fehler abzurufen. |
Hinweise
Die IcmpSendEcho2Ex-Funktion ist unter Windows Server 2008 und höher verfügbar.
Die IcmpSendEcho2Ex-Funktion ist eine erweiterte Version der IcmpSendEcho2-Funktion , mit der der Benutzer die IPv4-Quelladresse angeben kann, für die die ICMP-Anforderung ausgeführt werden soll. Die IcmpSendEcho2Ex-Funktion ist nützlich, wenn ein Computer über mehrere Netzwerkschnittstellen verfügt.
Die IcmpSendEcho2Ex-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 GetLastError für erweiterte Fehlerinformationen auf.
Die IcmpSendEcho2Ex-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 IcmpSendEcho2Ex-Funktion asynchron aufgerufen. Das im Ereignisparameter angegebene Ereignis wird immer dann signalisiert, wenn eine ICMP-Antwort eingeht. Verwenden Sie die CreateEvent-Funktion , um dieses Ereignisobjekt zu erstellen.
Wenn der ApcRoutine-Parameter angegeben wird, wird die IcmpSendEcho2Ex-Funktion asynchron aufgerufen. Der ApcRoutine-Parameter sollte auf eine benutzerdefinierte Rückruffunktion verweisen. Die im ApcRoutine-Parameter angegebene Rückruffunktion wird immer dann 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 immer dann signalisiert, wenn eine ICMP-Antwort eingeht, aber die im ApcRoutine-Parameter angegebene Rückruffunktion wird ignoriert.
Jede Anwendung, die die IcmpSendEcho2Ex-Funktion asynchron mit dem ApcRoutine-Parameter 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 IcmpSendEcho2Ex-Funktion aufruft. Wenn sich die Rückruffunktion in einer separaten DLL befindet, sollte die DLL geladen werden, bevor die IcmpSendEcho2Ex-Funktion aufgerufen wird.
Verwenden Sie für IPv6 die Funktionen Icmp6CreateFile, Icmp6SendEcho2 und Icmp6ParseReplies .
Beachten Sie, dass die include-Anweisung für die Headerdatei Iphlpapi.h vor der Headerdatei Icmpapi.h platziert werden muss.
Anforderungen
| Unterstützte Mindestversion (Client) | Windows Vista mit SP1 [nur Desktop-Apps] |
| Unterstützte Mindestversion (Server) | Windows Server 2008 [nur Desktop-Apps] |
| Zielplattform | Windows |
| Kopfzeile | icmpapi.h |
| Bibliothek | Iphlpapi.lib |
| DLL | Iphlpapi.dll |