Funzione icmpSendEcho2Ex (icmpapi.h)

Articolo
08/24/2023

La funzione IcmpSendEcho2Ex invia una richiesta echo ICMP IPv4 e restituisce immediatamente (se Event o ApcRoutine non è NULL) o restituisce dopo il timeout specificato. ReplyBuffer contiene le risposte ICMP, se presenti.

Sintassi

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

Parametri

[in] IcmpHandle

Handle aperto restituito dalla funzione ICMPCreateFile .

[in, optional] Event

Evento da segnalare ogni volta che arriva una risposta ICMP. 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 ICMP. PIO_APC_ROUTINE_DEFINED deve essere definito per forzare il tipo di dati per questo parametro a PIO_APC_ROUTINE anziché FARPROC.

[in, optional] ApcContext

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

[in] SourceAddress

Indirizzo di origine IPv4 su cui eseguire la richiesta echo. Questo indirizzo è sotto forma di una struttura IPAddr .

[in] DestinationAddress

Indirizzo di destinazione IPv4 per la richiesta echo. Questo indirizzo è sotto forma di una struttura IPAddr .

[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 IP 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.

[out] ReplyBuffer

Puntatore a un buffer per contenere tutte le risposte alla richiesta. Al ritorno, il buffer contiene una matrice di strutture ICMP_ECHO_REPLY seguite da opzioni e dati. Il buffer deve essere abbastanza grande per contenere almeno una struttura ICMP_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] ReplySize

Dimensione allocata, in byte, del buffer di risposta. Il buffer deve essere abbastanza grande per contenere almeno una struttura ICMP_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.

Valore restituito

Quando viene chiamato in modo sincrono, la funzione IcmpSendEcho2Ex restituisce il numero di risposte ricevute e archiviate in ReplyBuffer. Se il valore restituito è zero, chiamare GetLastError per informazioni sull'errore estese.

Quando viene chiamato in modo asincrono, la funzione IcmpSendEcho2Ex restituisce ERROR_IO_PENDING per indicare che l'operazione è in corso. I risultati possono essere recuperati in un secondo momento quando viene chiamato l'evento specificato nel parametro Event o la funzione di callback nel parametro ApcRoutine .

Se il valore restituito è zero, chiamare GetLastError per informazioni sull'errore estese.

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

Codice restituito	Descrizione
ERROR_INVALID_PARAMETER	Un parametro non valido è stato passato alla funzione. Questo errore viene restituito se il parametro IcmpHandle contiene un handle non valido. Questo errore può essere restituito anche se il parametro ReplySize specifica un valore minore delle dimensioni di una struttura ICMP_ECHO_REPLY .
ERROR_IO_PENDING	L'operazione è in corso. Questo valore viene restituito da una chiamata asincrona riuscita a IcmpSendEcho2Ex e non è un'indicazione di un errore.
ERROR_NOT_ENOUGH_MEMORY	Memoria insufficiente per completare l’operazione.
ERROR_NOT_SUPPORTED	La richiesta non è supportata. Questo errore viene restituito se non è presente alcun stack IPv4 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 IcmpSendEcho2Ex è disponibile in Windows Server 2008 e versioni successive.

La funzione IcmpSendEcho2Ex è una versione avanzata della funzione IcmpSendEcho2 che consente all'utente di specificare l'indirizzo di origine IPv4 in cui eseguire la richiesta ICMP. La funzione IcmpSendEcho2Ex è utile nei casi in cui un computer ha più interfacce di rete.

La funzione IcmpSendEcho2Ex 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 IcmpSendEcho2Ex 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 IcmpParseReplies .

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

Se viene specificato il parametro ApcRoutine , la funzione IcmpSendEcho2Ex 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 ICMP. 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 ICMP, ma la funzione di callback specificata nel parametro ApcRoutine viene ignorata.

Qualsiasi applicazione che chiama la funzione IcmpSendEcho2Ex 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 definito prima dell'inserimento del file di intestazione Icmpapi.h .

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

I parametri passati alla funzione callback includono quanto segue:

Parametro	Descrizione
IN PVOID ApcContext	Parametro ApcContext passato alla funzione IcmpSendEcho2Ex . Questo parametro può essere usato dall'applicazione per identificare la richiesta IcmpSendEcho2Ex 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.

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

Per IPv6, usare le funzioni Icmp6CreateFile, Icmp6SendEcho2 e Icmp6ParseReplies .

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

Requisiti


Client minimo supportato	Windows Vista con SP1 [solo app desktop]
Server minimo supportato	Windows Server 2008 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	icmpapi.h
Libreria	Iphlpapi.lib
DLL	Iphlpapi.dll