IcmpSendEcho2Ex-Funktion (icmpapi.h)

Artikel
08/24/2023

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
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 IcmpSendEcho2Ex 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 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:

Parameter	BESCHREIBUNG
IN PVOID ApcContext	Der ApcContext-Parameter , der an die IcmpSendEcho2Ex-Funktion übergeben wird. Dieser Parameter kann von der Anwendung verwendet werden, um die IcmpSendEcho2Ex-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 Headerdatei Wdm.h 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 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