Funzione icmpSendEcho2 (icmpapi.h)
La funzione IcmpSendEcho2 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 echo ICMP, se presenti.
Sintassi
IPHLPAPI_DLL_LINKAGE DWORD IcmpSendEcho2(
[in] HANDLE IcmpHandle,
[in, optional] HANDLE Event,
[in, optional] PIO_APC_ROUTINE ApcRoutine,
[in, optional] PVOID ApcContext,
[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 (al massimo) quando arriva una risposta ICMP. 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 di eventi, vedere Oggetti evento.
[in, optional] ApcRoutine
La routine chiamata quando il thread chiamante si trova in un thread avvisabile e arriva una risposta ICMPv4. 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 (al massimo) quando arriva una risposta ICMP o si verifica un errore.
[in] DestinationAddress
Destinazione IPv4 della richiesta echo, sotto forma di 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 .
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 , più i byte RequestSize dei dati, oltre a un ulteriore 8 byte di dati (le dimensioni di un messaggio di errore ICMP).
[in] ReplySize
Dimensione allocata, in byte, del buffer di risposta.
Il buffer deve essere abbastanza grande per contenere almeno una struttura ICMP_ECHO_REPLY , più i byte RequestSize dei dati, oltre a un ulteriore 8 byte di dati (le dimensioni di un messaggio di errore ICMP).
[in] Timeout
Tempo in millisecondi per attendere le risposte.
Valore restituito
Quando viene chiamato in modo sincrono, la funzione IcmpSendEcho2 restituisce il numero di risposte ricevute e archiviate in ReplyBuffer. Se il valore restituito è zero, per le informazioni di errore estese chiamare GetLastError.
Quando viene chiamato in modo asincrono, la funzione IcmpSendEcho2 restituisce zero. Una chiamata successiva a GetLastError restituisce il codice di errore esteso ERROR_IO_PENDING per indicare che l'operazione è in corso. I risultati possono essere recuperati in un secondo momento quando l'evento specificato nel segnale del parametro Event o la funzione di callback nel parametro ApcRoutine viene chiamata.
Se il valore restituito è 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_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 IcmpSendEcho2 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 IcmpSendEcho2 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, per le informazioni di errore estese chiamare GetLastError.
La funzione IcmpSendEcho2 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 IcmpSendEcho2 viene chiamata in modo asincrono. L'evento specificato nel parametro Event viene segnalato (al massimo una volta) quando arriva una risposta ICMP. Usare la funzione CreateEvent o CreateEventEx per creare questo oggetto evento.
Se viene specificato il parametro ApcRoutine , la funzione IcmpSendEcho2 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 (al massimo) quando arriva una risposta ICMP. 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 (al massimo) quando arriva una risposta ICMP, ma la funzione di callback specificata nel parametro ApcRoutine viene ignorata.
Qualsiasi applicazione che chiama la funzione IcmpSendEcho2 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.
Nota
PIO_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 | Il parametro AppContext passato alla funzione IcmpSendEcho2 . Questo parametro può essere usato dall'applicazione per identificare la richiesta IcmpSendEcho2 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 Wdm.h file di intestazione. |
| 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 IcmpSendEcho2 . Se la funzione di callback si trova in una DLL separata, la DLL deve essere caricata prima di chiamare la funzione IcmpSendEcho2 .
La funzione IcmpSendEcho2 viene esportata da Iphlpapi.dll.
Per IPv6, usare le funzioni Icmp6CreateFile, Icmp6SendEcho2 e Icmp6ParseReplies .
La direttiva di inclusione per il Iphlpapi.h file di intestazione deve essere posizionata prima di quella per il Icmpapi.h file di intestazione.
Esempio
Nell'esempio seguente viene chiamata la funzione IcmpSendEcho2 in modo sincrono. L'esempio invia una richiesta echo ICMP all'indirizzo IP specificato nella riga di comando e stampa le informazioni ricevute dalla prima risposta.
#include <winsock2.h>
#include <iphlpapi.h>
#include <icmpapi.h>
#include <stdio.h>
#pragma comment(lib, "iphlpapi.lib")
#pragma comment(lib, "ws2_32.lib")
int __cdecl main(int argc, char **argv)
{
// Declare and initialize variables.
HANDLE hIcmpFile;
unsigned long ipaddr = INADDR_NONE;
DWORD dwRetVal = 0;
DWORD dwError = 0;
char SendData[] = "Data Buffer";
LPVOID ReplyBuffer = NULL;
DWORD ReplySize = 0;
// Validate the parameters.
if (argc != 2) {
printf("usage: %s IP address\n", argv[0]);
return 1;
}
ipaddr = inet_addr(argv[1]);
if (ipaddr == INADDR_NONE) {
printf("usage: %s IP address\n", argv[0]);
return 1;
}
hIcmpFile = IcmpCreateFile();
if (hIcmpFile == INVALID_HANDLE_VALUE) {
printf("\tUnable to open handle.\n");
printf("IcmpCreatefile returned error: %ld\n", GetLastError());
return 1;
}
// Allocate space for a single reply.
ReplySize = sizeof (ICMP_ECHO_REPLY) + sizeof (SendData) + 8;
ReplyBuffer = (VOID *) malloc(ReplySize);
if (ReplyBuffer == NULL) {
printf("\tUnable to allocate memory for reply buffer\n");
return 1;
}
dwRetVal = IcmpSendEcho2(hIcmpFile, NULL, NULL, NULL,
ipaddr, SendData, sizeof (SendData), NULL,
ReplyBuffer, ReplySize, 1000);
if (dwRetVal != 0) {
PICMP_ECHO_REPLY pEchoReply = (PICMP_ECHO_REPLY) ReplyBuffer;
struct in_addr ReplyAddr;
ReplyAddr.S_un.S_addr = pEchoReply->Address;
printf("\tSent icmp message to %s\n", argv[1]);
if (dwRetVal > 1) {
printf("\tReceived %ld icmp message responses\n", dwRetVal);
printf("\tInformation from the first response:\n");
} else {
printf("\tReceived %ld icmp message response\n", dwRetVal);
printf("\tInformation from this response:\n");
}
printf("\t Received from %s\n", inet_ntoa(ReplyAddr));
printf("\t Status = %ld ", pEchoReply->Status);
switch (pEchoReply->Status) {
case IP_DEST_HOST_UNREACHABLE:
printf("(Destination host was unreachable)\n");
break;
case IP_DEST_NET_UNREACHABLE:
printf("(Destination Network was unreachable)\n");
break;
case IP_REQ_TIMED_OUT:
printf("(Request timed out)\n");
break;
default:
printf("\n");
break;
}
printf("\t Roundtrip time = %ld milliseconds\n",
pEchoReply->RoundTripTime);
} else {
printf("Call to IcmpSendEcho2 failed.\n");
dwError = GetLastError();
switch (dwError) {
case IP_BUF_TOO_SMALL:
printf("\tReplyBufferSize too small\n");
break;
case IP_REQ_TIMED_OUT:
printf("\tRequest timed out\n");
break;
default:
printf("\tExtended error returned: %ld\n", dwError);
break;
}
return 1;
}
return 0;
}
Requisiti
| Requisito | Valore |
|---|---|
| Client minimo supportato | Windows 2000 Professional [app desktop | App UWP] |
| Server minimo supportato | Windows 2000 Server [app desktop | App UWP] |
| Piattaforma di destinazione | Windows |
| Intestazione | icmpapi.h |
| Libreria | Iphlpapi.lib |
| DLL | Iphlpapi.dll in Windows Server 2008, Windows Vista, Windows Server 2003 e Windows XP; Icmp.dll in Windows 2000 Server e Windows 2000 Professional |