Funzione Icmp6SendEcho2 (icmpapi.h)

La funzione Icmp6SendEcho2 invia una richiesta echo IPv6 ICMPv6 e restituisce immediatamente (se Event o ApcRoutine è diverso da NULL) o restituisce dopo il timeout specificato. ReplyBuffer contiene la risposta echo IPv6 ICMPv6, 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 viene 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 degli eventi, vedere Oggetti evento.

[in, optional] ApcRoutine

Routine chiamata quando il thread chiamante si trova in un thread avvisabile e arriva una risposta ICMPv6. In Windows Vista e versioni successive è necessario definire PIO_APC_ROUTINE_DEFINED 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 a 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 contenente i 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 struttura IP_OPTION_INFORMATION . In una piattaforma a 64 bit, questo parametro è 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 Flags .

[out] ReplyBuffer

Puntatore a un buffer per contenere le risposte alla richiesta. Al termine della restituzione, il buffer contiene una struttura ICMPV6_ECHO_REPLY seguita dal corpo del messaggio dai dati di risposta echo ICMPv6. Il buffer deve essere sufficientemente grande da contenere almeno una struttura ICMPV6_ECHO_REPLY più il numero di byte di dati specificati nel parametro RequestSize . Questo buffer deve anche essere sufficientemente grande da contenere anche 8 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 punta il parametro ReplyBuffer . Questo buffer deve essere sufficientemente grande da contenere almeno una struttura ICMPV6_ECHO_REPLY più i byte RequestSize dei dati. Questo buffer deve anche essere sufficientemente grande da contenere anche 8 byte di dati (le dimensioni di un messaggio di errore ICMP) più spazio per una struttura IO_STATUS_BLOCK .

[in] Timeout

Tempo, espresso 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 parametro Event segnala o quando viene chiamata la funzione di callback nel parametro ApcRoutine .

Se il valore (sincrono o asincrono) delle risposte è pari a zero, per le informazioni estese sull'errore chiamare GetLastError.

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

Codice restituito	Description
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 indica un errore.
ERROR_NOT_ENOUGH_MEMORY	Memoria insufficiente per l'elaborazione di questo comando.
ERROR_NOT_SUPPORTED	La richiesta non è supportata. Questo errore viene restituito se non è presente alcun stack IPv6 nel computer locale.
IP_BUF_TOO_SMALL	Le dimensioni del ReplyBuffer specificato nel parametro ReplySize sono troppo piccole.
Altro	Usare FormatMessage per ottenere la stringa del messaggio per l'errore restituito.

Osservazioni:

La funzione Icmp6SendEcho2 viene chiamata in modo sincrono se i parametri ApcRoutine ed 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 del tempo specificato 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 devono accettare la risposta. I dati di risposta ICMP vengono copiati nell'oggetto ReplyBuffer fornito e l'applicazione viene segnalata (quando viene specificato il parametro Event ) o viene chiamata la funzione di callback (quando viene specificato il parametro ApcRoutine ). L'applicazione deve analizzare i dati a cui punta il parametro ReplyBuffer usando la funzione Icmp6ParseReplies .

Se si specifica il parametro Event , la funzione Icmp6SendEcho2 viene chiamata in modo asincrono. L'evento specificato nel parametro Event viene segnalato ogni volta che arriva una risposta ICMPv6. Utilizzare la funzione CreateEvent per creare questo oggetto evento.

Se viene specificato il parametro ApcRoutine , la funzione Icmp6SendEcho2 viene chiamata in modo asincrono. 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 entrambi i parametri Event e 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 a PIO_APC_ROUTINE anziché FARPROC.

NotaPIO_APC_ROUTINE_DEFINED deve essere definita prima che venga incluso il file di intestazione Icmpapi.h .

In Windows Vista e versioni successive, la funzione di callback a cui punta 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	Description
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 a FARPROC anziché PIO_APC_ROUTINE.

In Windows Server 2003 e Windows XP la funzione di callback a cui punta 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	Description
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	Value
Client minimo supportato	Windows XP [app desktop \| App UWP]
Server minimo supportato	Windows Server 2003 [app desktop \| App UWP]
Piattaforma di destinazione	Windows
Header	icmpapi.h
Library	Iphlpapi.lib
DLL	Iphlpapi.dll

Vedere anche

IP_OPTION_INFORMATION

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2025-11-26