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.

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

Vedi anche

Getlasterror

ICMP_ECHO_REPLY

IPAddr

IP_OPTION_INFORMATION

IP_OPTION_INFORMATION32

Icmp6CreateFile

Icmp6ParseReplies

Icmp6SendEcho2

IcmpCloseHandle

IcmpCreateFile

IcmpParseReplies

IcmpSendEcho2

IcmpSendEcho2Ex