Funzione icmp6SendEcho2 (icmpapi.h)

Articolo
10/10/2023

La funzione Icmp6SendEcho2 invia una richiesta echo IPv6 IPv6 e restituisce immediatamente (se Event o ApcRoutine non è NULL) o restituisce dopo il timeout specificato. ReplyBuffer contiene la risposta echo IPv6 IPv6, se presente.

Sintassi

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
);

Parametri

[in] IcmpHandle

Handle aperto restituito da Icmp6CreateFile.

[in, optional] Event

Evento da segnalare ogni volta che arriva una risposta ICMPv6. Se questo parametro è specificato, richiede un handle per un oggetto evento valido. Usare la funzione CreateEvent o CreateEventEx per creare questo oggetto evento.

Per altre informazioni sull'uso di eventi, vedere Oggetti eventi.

[in, optional] ApcRoutine

La routine chiamata quando il thread chiamante si trova in un thread avvisabile e arriva una risposta ICMPv6. In Windows Vista e versioni successive , PIO_APC_ROUTINE_DEFINED deve essere definito per forzare il tipo di dati per questo parametro a PIO_APC_ROUTINE anziché FARPROC.

In Windows Server 2003 e Windows XP , PIO_APC_ROUTINE_DEFINED non deve essere definito per forzare il tipo di dati per questo parametro in FARPROC.

[in, optional] ApcContext

Parametro facoltativo passato alla routine di callback specificata nel parametro ApcRoutine ogni volta che arriva una risposta ICMPv6 o si verifica un errore.

[in] SourceAddress

Indirizzo di origine IPv6 su cui emettere la richiesta echo, sotto forma di struttura sockaddr .

[in] DestinationAddress

Indirizzo di destinazione IPv6 della richiesta echo, sotto forma di struttura sockaddr .

[in] RequestData

Puntatore a un buffer che contiene dati da inviare nella richiesta.

[in] RequestSize

Dimensioni, in byte, del buffer dei dati della richiesta a cui punta il parametro RequestData .

[in, optional] RequestOptions

Puntatore alle opzioni di intestazione IPv6 per la richiesta, sotto forma di una struttura IP_OPTION_INFORMATION . In una piattaforma a 64 bit, questo parametro si trova nel formato per una struttura IP_OPTION_INFORMATION32 .

Questo parametro può essere NULL se non è necessario specificare opzioni di intestazione IP.

Nota In Windows Server 2003 e Windows XP il parametro RequestOptions non è facoltativo e non deve essere NULL e vengono usati solo i membri Ttl e Flag .

[out] ReplyBuffer

Puntatore a un buffer per contenere le risposte alla richiesta. Al ritorno, il buffer contiene una struttura ICMPV6_ECHO_REPLY seguita dal corpo del messaggio dai dati di risposta echo ICMPv6. Il buffer deve essere abbastanza grande per contenere almeno una struttura ICMPV6_ECHO_REPLY più il numero di byte di dati specificati nel parametro RequestSize . Questo buffer deve anche essere abbastanza grande per contenere anche 8 più byte di dati (le dimensioni di un messaggio di errore ICMP) più spazio per una struttura IO_STATUS_BLOCK .

[in] ReplySize

Dimensioni, in byte, del buffer di risposta a cui fa riferimento il parametro ReplyBuffer . Questo buffer deve essere abbastanza grande per contenere almeno una struttura ICMPV6_ECHO_REPLY e i byte RequestSize dei dati. Questo buffer deve anche essere abbastanza grande per contenere anche 8 più byte di dati (le dimensioni di un messaggio di errore ICMP) più spazio per una struttura IO_STATUS_BLOCK .

[in] Timeout

Tempo, in millisecondi, per attendere le risposte. Questo parametro viene usato solo se la funzione Icmp6SendEcho2 viene chiamata in modo sincrono. Questo parametro non viene quindi usato se il parametro ApcRoutine o Event non è NULL.

Valore restituito

Quando viene chiamato in modo sincrono, restituisce il numero di risposte ricevute e archiviate in ReplyBuffer.

Quando viene chiamato in modo asincrono, indica che l'operazione è in corso restituendo ERROR_IO_PENDING. È possibile recuperare il risultato del numero di risposte in un secondo momento, quando l'evento specificato nel segnale del parametro Event o quando viene chiamata la funzione di callback nel parametro ApcRoutine .

Se il valore di numero di risposte sincrono (sincrono o asincrono) è zero, per le informazioni di errore estese chiamare GetLastError.

Se la funzione ha esito negativo, il codice di errore esteso restituito da GetLastError può essere uno dei valori seguenti.

Codice restituito	Descrizione
ERROR_CALL_NOT_IMPLEMENTED	Questa funzione non è supportata in questo sistema.
ERROR_INSUFFICIENT_BUFFER	L'area dati passata a una chiamata di sistema è troppo piccola. Questo errore viene restituito se il parametro ReplySize indica che il buffer a cui punta il parametro ReplyBuffer è troppo piccolo.
ERROR_INVALID_PARAMETER	Uno dei parametri non è valido. Questo errore viene restituito se il parametro IcmpHandle contiene un handle non valido.
ERROR_IO_PENDING	L'operazione è in corso. Questo valore viene restituito da una chiamata asincrona riuscita a Icmp6SendEcho2 e non è un'indicazione di un errore.
ERROR_NOT_ENOUGH_MEMORY	Memoria insufficiente disponibile per elaborare questo comando.
ERROR_NOT_SUPPORTED	La richiesta non è supportata. Questo errore viene restituito se non si trova alcun stack IPv6 nel computer locale.
IP_BUF_TOO_SMALL	Le dimensioni del parametro ReplyBuffer specificato nel parametro ReplySize erano troppo piccole.
Altri	Usare FormatMessage per ottenere la stringa di messaggio per l'errore restituito.

Commenti

La funzione Icmp6SendEcho2 viene chiamata sincrona se i parametri ApcRoutine o Event sono NULL. Quando viene chiamato in modo sincrono, il valore restituito contiene il numero di risposte ricevute e archiviate in ReplyBuffer dopo l'attesa dell'ora specificata nel parametro Timeout . Se il valore restituito è zero, chiamare GetLastError per informazioni sull'errore estese.

La funzione Icmp6SendEcho2 viene chiamata in modo asincrono quando vengono specificati i parametri ApcRoutine o Event . Quando viene chiamato in modo asincrono, i parametri ReplyBuffer e ReplySize sono necessari per accettare la risposta. I dati di risposta ICMP vengono copiati in ReplyBuffer forniti e l'applicazione viene segnalato (quando viene specificato il parametro Event ) o la funzione di callback viene chiamata (quando viene specificato il parametro ApcRoutine ). L'applicazione deve analizzare i dati a cui punta il parametro ReplyBuffer usando la funzione Icmp6ParseReplies .

Se viene specificato il parametro Event , la funzione Icmp6SendEcho2 viene chiamata asincronamente. L'evento specificato nel parametro Event viene segnalato ogni volta che arriva una risposta ICMPv6. Usare la funzione CreateEvent per creare questo oggetto evento.

Se viene specificato il parametro ApcRoutine , la funzione Icmp6SendEcho2 viene chiamata asincronamente. Il parametro ApcRoutine deve puntare a una funzione di callback definita dall'utente. La funzione di callback specificata nel parametro ApcRoutine viene chiamata ogni volta che arriva una risposta ICMPv6. La chiamata della funzione di callback specificata nel parametro ApcRoutine viene serializzata.

Se vengono specificati sia i parametri Event che ApcRoutine , l'evento specificato nel parametro Event viene segnalato ogni volta che arriva una risposta ICMPv6, ma la funzione di callback specificata nel parametro ApcRoutine viene ignorata.

In Windows Vista e versioni successive, qualsiasi applicazione che chiama la funzione Icmp6SendEcho2 in modo asincrono usando il parametro ApcRoutine deve definire PIO_APC_ROUTINE_DEFINED per forzare il tipo di dati per il parametro ApcRoutine per PIO_APC_ROUTINE anziché FARPROC.

NotaPIO_APC_ROUTINE_DEFINED deve essere definito prima dell'inserimento del file di intestazione Icmpapi.h .

In Windows Vista e versioni successive, la funzione callback puntata da ApcRoutine deve essere definita come funzione di tipo VOID con la sintassi seguente:

typedef
VOID WINAPI
(*PIO_APC_ROUTINE) (
    IN PVOID ApcContext,
    IN PIO_STATUS_BLOCK IoStatusBlock,
    IN ULONG Reserved
    );

In Windows Vista e versioni successive, i parametri passati alla funzione di callback includono quanto segue:

Parametro	Descrizione
IN PVOID ApcContext	Parametro ApcContext passato alla funzione Icmp6SendEcho2 . Questo parametro può essere usato dall'applicazione per identificare la richiesta Icmp6SendEcho2 a cui risponde la funzione di callback.
IN PIO_STATUS_BLOCK IoStatusBlock	Puntatore a un IO_STATUS_BLOCK. Questa variabile contiene lo stato di completamento finale e le informazioni sull'operazione. Il numero di byte effettivamente ricevuti nella risposta viene restituito nel membro Informazioni dello struct IO_STATUS_BLOCK . La struttura IO_STATUS_BLOCK è definita nel file di intestazione Wdm.h .
IN ULONG riservato	Questo parametro è riservato.

In Windows Server 2003 e Windows XP, qualsiasi applicazione che chiama la funzione Icmp6SendEcho2 in modo asincrono usando il parametro ApcRoutine non deve definire PIO_APC_ROUTINE_DEFINED per forzare il tipo di dati per il parametro ApcRoutine in FARPROC anziché PIO_APC_ROUTINE.

In Windows Server 2003 e Windows XP la funzione di callback puntata da ApcRoutine deve essere definita come funzione di tipo VOID con la sintassi seguente:

typedef
VOID WINAPI
(*FARPROC) (
    IN PVOID ApcContext,
    );

In Windows Server 2003 e Windows XP, i parametri passati alla funzione di callback includono quanto segue:

Parametro	Descrizione
IN PVOID ApcContext	Parametro ApcContext passato alla funzione Icmp6SendEcho2 . Questo parametro può essere usato dall'applicazione per identificare la richiesta Icmp6SendEcho2 a cui risponde la funzione di callback.

La funzione di callback specificata nel parametro ApcRoutine deve essere implementata nello stesso processo dell'applicazione che chiama la funzione Icmp6SendEcho2 . Se la funzione di callback si trova in una DLL separata, la DLL deve essere caricata prima di chiamare la funzione Icmp6SendEcho2 .

Per IPv4, usare le funzioni IcmpCreateFile, IcmpSendEcho, IcmpSendEcho2, IcmpSendEcho2Ex e IcmpParseReplies .

Si noti che la direttiva include per il file di intestazione Iphlpapi.h deve essere inserita prima del file di intestazione Icmpapi.h .

Requisiti

Requisito	Valore
Client minimo supportato	Windows XP [app desktop \| App UWP]
Server minimo supportato	Windows Server 2003 [app desktop \| App UWP]
Piattaforma di destinazione	Windows
Intestazione	icmpapi.h
Libreria	Iphlpapi.lib
DLL	Iphlpapi.dll