Icmp6SendEcho2-Funktion (icmpapi.h)
Die Icmp6SendEcho2-Funktion sendet eine IPv6 ICMPv6-Echoanforderung und gibt entweder sofort (wenn Event oder ApcRoutine ungleich NULL ist) oder nach dem angegebenen Timeout zurück. Der ReplyBuffer enthält ggf. die IPv6-ICMPv6-Echoantwort.
Syntax
IPHLPAPI_DLL_LINKAGE DWORD Icmp6SendEcho2(
[in] HANDLE IcmpHandle,
[in, optional] HANDLE Event,
[in, optional] PIO_APC_ROUTINE ApcRoutine,
[in, optional] PVOID ApcContext,
[in] sockaddr_in6 *SourceAddress,
[in] sockaddr_in6 *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 Icmp6CreateFile zurückgegeben wird.
[in, optional] Event
Ein Ereignis, das beim Eintreffen einer ICMPv6-Antwort signalisiert werden soll. Wenn dieser Parameter angegeben ist, ist ein Handle für ein gültiges Ereignisobjekt erforderlich. Verwenden Sie die CreateEvent- oder CreateEventEx-Funktion , 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 warnungsfähigen Thread befindet und eine ICMPv6-Antwort eingeht. Unter Windows Vista und höher muss PIO_APC_ROUTINE_DEFINED definiert werden, um zu erzwingen, dass der Datentyp für diesen Parameter PIO_APC_ROUTINE statt FARPROC.
Unter Windows Server 2003 und Windows XP darf PIO_APC_ROUTINE_DEFINED nicht definiert werden, um den Datentyp für diesen Parameter in FARPROC zu erzwingen.
[in, optional] ApcContext
Ein optionaler Parameter, der an die im ApcRoutine-Parameter angegebene Rückrufroutine übergeben wird, wenn eine ICMPv6-Antwort eingeht oder ein Fehler auftritt.
[in] SourceAddress
Die IPv6-Quelladresse, für die die Echoanforderung in Form einer sockaddr-Struktur ausgeführt werden soll.
[in] DestinationAddress
Die IPv6-Zieladresse der Echoanforderung in Form einer sockaddr-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 den der RequestData-Parameter verweist.
[in, optional] RequestOptions
Ein Zeiger auf die IPv6-Headeroptionen für die Anforderung in Form einer IP_OPTION_INFORMATION-Struktur . Auf einer 64-Bit-Plattform hat dieser Parameter das Format 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 Antworten auf die Anforderung enthält. Bei der Rückgabe enthält der Puffer eine ICMPV6_ECHO_REPLY-Struktur gefolgt vom Nachrichtentext aus den ICMPv6-Echoantwortdaten. Der Puffer muss groß genug sein, um mindestens eine ICMPV6_ECHO_REPLY Struktur zuzüglich der im RequestSize-Parameter angegebenen Anzahl von Daten zu enthalten. Dieser Puffer sollte auch groß genug sein, um auch 8 weitere Bytes an Daten (die Größe einer ICMP-Fehlermeldung) zu enthalten, plus Platz für eine IO_STATUS_BLOCK-Struktur .
[in] ReplySize
Die Größe des Antwortpuffers in Bytes, auf den der ReplyBuffer-Parameter verweist. Dieser Puffer sollte groß genug sein, um mindestens eine ICMPV6_ECHO_REPLY-Struktur plus RequestSize-Datenbytes zu enthalten. Dieser Puffer sollte auch groß genug sein, um auch 8 weitere Bytes an Daten (die Größe einer ICMP-Fehlermeldung) zu enthalten, plus Platz für eine IO_STATUS_BLOCK-Struktur .
[in] Timeout
Die Zeit in Millisekunden, um auf Antworten zu warten. Dieser Parameter wird nur verwendet, wenn die Icmp6SendEcho2-Funktion synchron aufgerufen wird. Daher wird dieser Parameter nicht verwendet, wenn weder der ApcRoutine- noch der Event-Parameter NULL sind.
Rückgabewert
Gibt bei synchronem Aufruf die Anzahl der Antworten zurück, die in ReplyBuffer empfangen und gespeichert werden.
Gibt bei asynchronem Aufruf an, dass der Vorgang ausgeführt wird, indem ERROR_IO_PENDING zurückgegeben wird. Sie können das Ergebnis mit der Anzahl der Antworten später abrufen, wenn das im Event-Parameter angegebene Ereignis signalisiert oder wenn die Rückruffunktion im ApcRoutine-Parameter aufgerufen wird.
Wenn der (synchrone oder asynchrone) Number-of-Replies-Wert 0 (null) 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 |
|---|---|
|
Die Funktion wird auf diesem System nicht unterstützt. |
|
Der an einen Systemaufruf weitergegebene Datenbereich ist zu klein. Dieser Fehler wird zurückgegeben, wenn der ReplySize-Parameter angibt, dass der Puffer, auf den der ReplyBuffer-Parameter verweist, zu klein ist. |
|
Einer der Parameter ist ungültig. Dieser Fehler wird zurückgegeben, wenn der IcmpHandle-Parameter ein ungültiges Handle enthält. |
|
Der Vorgang wird ausgeführt. Dieser Wert wird von einem erfolgreichen asynchronen Aufruf von Icmp6SendEcho2 zurückgegeben und ist kein Hinweis auf einen Fehler. |
|
Für die Verarbeitung dieses Befehls ist nicht genügend Arbeitsspeicher verfügbar. |
|
Die Anforderung wird nicht unterstützt. Dieser Fehler wird zurückgegeben, wenn sich kein IPv6-Stapel auf dem lokalen Computer befindet. |
|
Die Größe des im ReplySize-Parameter angegebenen ReplyBuffer war zu klein. |
|
Verwenden Sie FormatMessage , um die Meldungszeichenfolge für den zurückgegebenen Fehler abzurufen. |
Hinweise
Die Icmp6SendEcho2-Funktion wird synchron aufgerufen, wenn die Parameter ApcRoutine oder EventNULL sind. Bei synchronem Aufruf enthält der Rückgabewert die Anzahl der empfangenen und in ReplyBuffer gespeicherten Antworten, nachdem sie auf die im Timeout-Parameter angegebene Zeit gewartet haben. Wenn der Rückgabewert null ist, rufen Sie GetLastError für erweiterte Fehlerinformationen auf.
Die Icmp6SendEcho2-Funktion wird asynchron aufgerufen, wenn entweder die Parameter ApcRoutine oder Event angegeben sind. 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 Icmp6ParseReplies-Funktion verwiesen wird.
Wenn der Event-Parameter angegeben ist, wird die Icmp6SendEcho2-Funktion asynchron aufgerufen. Das im Event-Parameter angegebene Ereignis wird immer dann signalisiert, wenn eine ICMPv6-Antwort eingeht. Verwenden Sie die CreateEvent-Funktion , um dieses Ereignisobjekt zu erstellen.
Wenn der ApcRoutine-Parameter angegeben ist, wird die Icmp6SendEcho2-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 ICMPv6-Antwort eingeht. Der Aufruf der im ApcRoutine-Parameter angegebenen Rückruffunktion 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 ICMPv6-Antwort eingeht, aber die im ApcRoutine-Parameter angegebene Rückruffunktion wird ignoriert.
Unter Windows Vista und höher muss jede Anwendung, die die Icmp6SendEcho2-Funktion asynchron mit dem ApcRoutine-Parameter aufruft , PIO_APC_ROUTINE_DEFINED definieren, um zu erzwingen, dass der Datentyp für den ApcRoutine-ParameterPIO_APC_ROUTINE anstelle von FARPROC.
Unter Windows Vista und höher muss die Rückruffunktion, auf die die ApcRoutine verweist, 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
);
Unter Windows Vista und höher umfassen die an die Rückruffunktion übergebenen Parameter Folgendes:
Unter Windows Server 2003 und Windows XP darf jede Anwendung, die die Icmp6SendEcho2-Funktion asynchron mit dem ApcRoutine-Parameter aufruft, nicht definieren, PIO_APC_ROUTINE_DEFINED zum Erzwingen des Datentyps für den ApcRoutine-Parameter in FARPROC anstelle von PIO_APC_ROUTINE.
Unter Windows Server 2003 und Windows XP muss die Rückruffunktion, auf die die ApcRoutine verweist, als Funktion vom Typ VOID mit der folgenden Syntax definiert werden:
typedef
VOID WINAPI
(*FARPROC) (
IN PVOID ApcContext,
);
Unter Windows Server 2003 und Windows XP umfassen die an die Rückruffunktion übergebenen Parameter Folgendes:
Die im ApcRoutine-Parameter angegebene Rückruffunktion muss im selben Prozess wie die Anwendung implementiert werden, die die Icmp6SendEcho2-Funktion aufruft . Wenn sich die Rückruffunktion in einer separaten DLL befindet, sollte die DLL geladen werden, bevor die Icmp6SendEcho2-Funktion aufgerufen wird.
Verwenden Sie für IPv4 die Funktionen IcmpCreateFile, IcmpSendEcho, IcmpSendEcho2, IcmpSendEcho2Ex und IcmpParseReplies .
Beachten Sie, dass die include-Direktive für die Headerdatei Iphlpapi.h vor der Headerdatei Icmpapi.h platziert werden muss.
Anforderungen
| Anforderung | Wert |
|---|---|
| Unterstützte Mindestversion (Client) | Windows XP [Desktop-Apps | UWP-Apps] |
| Unterstützte Mindestversion (Server) | Windows Server 2003 [Desktop-Apps | UWP-Apps] |
| Zielplattform | Windows |
| Kopfzeile | icmpapi.h |
| Bibliothek | Iphlpapi.lib |
| DLL | Iphlpapi.dll |