Icmp6SendEcho2-Funktion (icmpapi.h)

Die Icmp6SendEcho2-Funktion sendet eine IPv6 ICMPv6-Echoanforderung und gibt entweder sofort (wenn "Ereignis " oder "ApcRoutine " nicht 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
);

Die Parameter

[in] IcmpHandle

Das geöffnete Handle, das von Icmp6CreateFile zurückgegeben wird.

[in, optional] Event

Ein Ereignis, das signalisiert wird, wenn eine ICMPv6-Antwort eingeht. 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 Event Objects.

[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 den Datentyp für diesen Parameter zu erzwingen, anstatt FARPROC zu PIO_APC_ROUTINE.

Unter Windows Server 2003 und Windows XP darf PIO_APC_ROUTINE_DEFINED nicht definiert werden, um den Datentyp für diesen Parameter auf 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, auf der die Echoanforderung in Form einer Sockaddr-Struktur ausstellen 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 die 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 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.

Anmerkung Unter Windows Server 2003 und Windows XP ist der Parameter "RequestOptions" nicht optional und darf nicht NULL sein, und nur die Elemente "Ttl" und "Flags" werden verwendet.

[out] ReplyBuffer

Ein Zeiger auf einen Puffer zum Halten von Antworten auf die Anforderung. Beim Zurückgeben enthält der Puffer eine ICMPV6_ECHO_REPLY Struktur gefolgt vom Nachrichtentext aus den Antwortdaten der ICMPv6-Echoantwort. Der Puffer muss groß genug sein, um mindestens eine ICMPV6_ECHO_REPLY Struktur sowie die Anzahl der Im RequestSize-Parameter angegebenen Byte von Daten zu enthalten. Dieser Puffer sollte auch groß genug sein, um auch 8 weitere Bytes an Daten (die Größe einer ICMP-Fehlermeldung) sowie Speicherplatz für eine IO_STATUS_BLOCK Struktur zu enthalten.

[in] ReplySize

Die Größe des Antwortpuffers in Bytes, auf die der ReplyBuffer-Parameter verweist. Dieser Puffer sollte groß genug sein, um mindestens eine ICMPV6_ECHO_REPLY Struktur sowie RequestSize bytes of data zu enthalten. Dieser Puffer sollte auch groß genug sein, um auch 8 weitere Bytes an Daten (die Größe einer ICMP-Fehlermeldung) sowie Speicherplatz für eine IO_STATUS_BLOCK Struktur zu enthalten.

[in] Timeout

Die Zeit in Millisekunden, um auf Antworten zu warten. Dieser Parameter wird nur verwendet, wenn die Icmp6SendEcho2-Funktion synchron aufgerufen wird. Dieser Parameter wird also nicht verwendet, wenn der Parameter "ApcRoutine " oder "Event " nicht NULL ist.

Rückgabewert

Wenn sie synchron aufgerufen wird, wird die Anzahl der empfangenen und in ReplyBuffer gespeicherten Antworten zurückgegeben.

Gibt an, dass der Vorgang asynchron aufgerufen wird, indem ERROR_IO_PENDING zurückgegeben wird. Sie können das Ergebnis der Anzahl von Antworten später abrufen, wenn das im Ereignisparameter angegebene Ereignis signalisiert wird oder wenn die Rückruffunktion im ApcRoutine-Parameter aufgerufen wird.

Wenn der Wert für synchrone oder asynchrone Antworten null 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	Description
ERROR_CALL_NOT_IMPLEMENTED	Diese Funktion wird auf diesem System nicht unterstützt.
ERROR_INSUFFICIENT_BUFFER	Der an einen Systemaufruf übergebene 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.
ERROR_INVALID_PARAMETER	Einer der Parameter ist ungültig. Dieser Fehler wird zurückgegeben, wenn der IcmpHandle-Parameter ein ungültiges Handle enthält.
ERROR_IO_PENDING	Der Vorgang wird ausgeführt. Dieser Wert wird von einem erfolgreichen asynchronen Aufruf von Icmp6SendEcho2 zurückgegeben und ist kein Hinweis auf einen Fehler.
ERROR_NOT_ENOUGH_MEMORY	Nicht genügend Arbeitsspeicher ist verfügbar, um diesen Befehl zu verarbeiten.
ERROR_NOT_SUPPORTED	Die Anforderung wird nicht unterstützt. Dieser Fehler wird zurückgegeben, wenn sich kein IPv6-Stapel auf dem lokalen Computer befindet.
IP_BUF_TOO_SMALL	Die Größe des im ReplySize-Parameter angegebenen ReplyBuffer-Parameters war zu klein.
Andere	Verwenden Sie FormatMessage , um die Nachrichtenzeichenfolge für den zurückgegebenen Fehler abzurufen.

Bemerkungen

Die Icmp6SendEcho2-Funktion wird synchron aufgerufen, wenn die Parameter "ApcRoutine " und "Event " NULL sind. Wenn der Rückgabewert synchron aufgerufen wird, 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 werden. Bei asynchroner 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 wird) oder die Rückruffunktion aufgerufen wird (wenn der ApcRoutine-Parameter angegeben wird). Die Anwendung muss die daten analysieren, auf die der ReplyBuffer-Parameter verweist, mithilfe der Icmp6ParseReplies-Funktion .

Wenn der Parameter "Event " angegeben ist, wird die Icmp6SendEcho2-Funktion asynchron aufgerufen. Das im Parameter "Event " angegebene Ereignis wird immer dann signalisiert, wenn eine ICMPv6-Antwort eingeht. Verwenden Sie die CreateEvent-Funktion , um dieses Ereignisobjekt zu erstellen.

Wenn der Parameter "ApcRoutine " angegeben ist, wird die Icmp6SendEcho2-Funktion asynchron aufgerufen. Der Parameter "ApcRoutine " sollte auf eine benutzerdefinierte Rückruffunktion verweisen. Die im Parameter "ApcRoutine" angegebene Rückruffunktion wird immer aufgerufen, wenn eine ICMPv6-Antwort eingeht. Der Aufruf der rückruffunktion, die im Parameter "ApcRoutine " angegeben ist, wird serialisiert.

Wenn sowohl die Parameter "Event " als auch " ApcRoutine " angegeben sind, wird das im Parameter "Event " angegebene Ereignis immer dann signalisiert, wenn eine ICMPv6-Antwort eingeht, die im Parameter "ApcRoutine " angegebene Rückruffunktion jedoch ignoriert wird.

Unter Windows Vista und höher muss jede Anwendung, die icmp6SendEcho2-Funktion asynchron mithilfe des ApcRoutine-Parameters aufruft, PIO_APC_ROUTINE_DEFINED definieren, um den Datentyp für den ApcRoutine-Parameter zu erzwingen, anstatt FARPROC zu PIO_APC_ROUTINE.

HinweisPIO_APC_ROUTINE_DEFINED muss definiert werden, bevor die Headerdatei "Icmpapi.h " enthalten ist.

Unter Windows Vista und höher muss die Rückruffunktion, auf die die ApcRoutine verweist, als Funktion vom Typ 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 Parameter, die an die Rückruffunktion übergeben werden, Folgendes:

Parameter	Description
IN PVOID ApcContext	Der an die Icmp6SendEcho2-Funktion übergebene ApcContext-Parameter. Dieser Parameter kann von der Anwendung verwendet werden, um die Icmp6SendEcho2-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 den endgültigen Abschlussstatus und Informationen zum Vorgang. Die Anzahl der in der Antwort tatsächlich empfangenen Bytes wird im Information-Element der IO_STATUS_BLOCK Struktur zurückgegeben. Die IO_STATUS_BLOCK Struktur wird in der Wdm.h-Headerdatei definiert.
IN ULONG Reserviert	Dieser Parameter ist reserviert.

Unter Windows Server 2003 und Windows XP darf jede Anwendung, die die Icmp6SendEcho2-Funktion asynchron mithilfe des ApcRoutine-Parameters aufruft, PIO_APC_ROUTINE_DEFINED nicht definieren, um den Datentyp für den ApcRoutine-Parameter auf FARPROC zu erzwingen, anstatt 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 parameter, die an die Rückruffunktion übergeben werden:

Parameter	Description
IN PVOID ApcContext	Der an die Icmp6SendEcho2-Funktion übergebene ApcContext-Parameter. Dieser Parameter kann von der Anwendung verwendet werden, um die Icmp6SendEcho2-Anforderung zu identifizieren, auf die die Rückruffunktion reagiert.

Die im Parameter "ApcRoutine " angegebene Rückruffunktion muss im gleichen Prozess implementiert werden wie die Anwendung, 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 iphlpapi.h-Headerdatei vor der Headerdatei Icmpapi.h platziert werden muss.

Anforderungen

Anforderung	Wert
Mindestens unterstützter Client	Windows XP [Desktop-Apps \| UWP-Apps]
Mindestanforderungen für unterstützte Server	Windows Server 2003 [Desktop-Apps \| UWP-Apps]
Zielplattform	Fenster
Header	icmpapi.h
Library	Iphlpapi.lib
DLL	Iphlpapi.dll

Siehe auch

IP_OPTION_INFORMATION

Feedback

War diese Seite hilfreich?

Last updated on 2025-11-26