Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
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.
Beachten SiePIO_APC_ROUTINE_DEFINED definiert werden müssen, 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:
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 |