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.

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.

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:

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

Vedi anche

• CreateEvent
• CreateEventEx
• Oggetti evento
• Getlasterror
• ICMP_ECHO_REPLY
• IP_OPTION_INFORMATION
• IP_OPTION_INFORMATION32
• IPAddr
• Icmp6CreateFile
• Icmp6ParseReplies
• Icmp6SendEcho2
• IcmpCloseHandle
• IcmpCreateFile
• IcmpParseReplies
• IcmpSendEcho
• IcmpSendEcho2Ex