Funzione icmpSendEcho (icmpapi.h)
La funzione IcmpSendEcho invia una richiesta echo IPv4 ICMP e restituisce eventuali risposte di risposta echo. La chiamata restituisce quando il timeout è scaduto o il buffer di risposta viene riempito.
Sintassi
IPHLPAPI_DLL_LINKAGE DWORD IcmpSendEcho(
[in] HANDLE IcmpHandle,
[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] DestinationAddress
Indirizzo di 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 . 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
Buffer per contenere tutte le risposte alla richiesta echo. Al ritorno, il buffer contiene una matrice di strutture ICMP_ECHO_REPLY seguite dalle opzioni e dai dati per le risposte. Il buffer deve essere abbastanza grande per contenere almeno una struttura ICMP_ECHO_REPLY e i byte RequestSize dei dati.
[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).
[in] Timeout
Tempo, in millisecondi, per attendere le risposte.
Valore restituito
La funzione IcmpSendEcho restituisce il numero di strutture ICMP_ECHO_REPLY archiviate in ReplyBuffer. Lo stato di ogni risposta è contenuto nella struttura. Se il valore restituito è zero, chiamare GetLastError per ulteriori informazioni sugli errori.
Se la funzione ha esito negativo, il codice di errore esteso restituito da GetLastError può essere uno dei valori seguenti.
| Codice restituito | Descrizione |
|---|---|
|
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. |
|
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 . |
|
Memoria insufficiente per completare l’operazione. |
|
La richiesta non è supportata. Questo errore viene restituito se non è presente alcun stack IPv4 nel computer locale. |
|
Le dimensioni del parametro ReplyBuffer specificato nel parametro ReplySize erano troppo piccole. |
|
Usare FormatMessage per ottenere la stringa di messaggio per l'errore restituito. |
Commenti
La funzione IcmpSendEcho invia una richiesta echo ICMP all'indirizzo specificato e restituisce il numero di risposte ricevute e archiviate in ReplyBuffer. La funzione IcmpSendEcho è una funzione sincrona e restituisce dopo l'attesa dell'ora specificata nel parametro Timeout per una risposta. Se il valore restituito è zero, chiamare GetLastError per informazioni sull'errore estese.
Le funzioni IcmpSendEcho2 e IcmpSendEcho2Ex sono versioni avanzate di IcmpSendEcho che supportano l'operazione asincrona. La funzione IcmpSendEcho2Ex consente anche di specificare l'indirizzo IP di origine. Questa funzionalità è utile nei computer con più interfacce di rete.
Per IPv6, usare le funzioni Icmp6CreateFile, Icmp6SendEcho2 e Icmp6ParseReplies .
La funzione IcmpSendEcho viene esportata dal Icmp.dll in Windows 2000. La funzione IcmpSendEcho viene esportata dal Iphlpapi.dll in Windows XP e versioni successive. Il controllo delle versioni di Windows non è consigliabile usare questa funzione. Le applicazioni che richiedono la portabilità con questa funzione in Windows 2000, Windows XP, Windows Server 2003 e versioni successive di Windows non devono essere collegate staticamente al file Icmp.lib o al file Iphlpapi.lib . L'applicazione deve invece verificare la presenza di IcmpSendEcho nella Iphlpapi.dll con chiamate a LoadLibrary e GetProcAddress. In caso contrario, l'applicazione deve verificare la presenza di IcmpSendEcho nella Icmp.dll con chiamate a LoadLibrary e GetProcAddress.
Si noti che la direttiva di inclusione per il file di intestazione Iphlpapi.h deve essere inserita prima del file di intestazione Icmpapi.h .
Esempio
Nell'esempio seguente viene inviata 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;
char SendData[32] = "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;
}
ReplySize = sizeof(ICMP_ECHO_REPLY) + sizeof(SendData);
ReplyBuffer = (VOID*) malloc(ReplySize);
if (ReplyBuffer == NULL) {
printf("\tUnable to allocate memory\n");
return 1;
}
dwRetVal = IcmpSendEcho(hIcmpFile, 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\n",
pEchoReply->Status);
printf("\t Roundtrip time = %ld milliseconds\n",
pEchoReply->RoundTripTime);
}
else {
printf("\tCall to IcmpSendEcho failed.\n");
printf("\tIcmpSendEcho returned error: %ld\n", GetLastError() );
return 1;
}
return 0;
}
Requisiti
| Client minimo supportato | Windows 2000 Professional [solo app desktop] |
| Server minimo supportato | Windows 2000 Server [solo app desktop] |
| 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 |