Funzione SendARP (iphlpapi.h)

La funzione SendARP invia una richiesta ARP (Address Resolution Protocol) per ottenere l'indirizzo fisico corrispondente all'indirizzo IPv4 di destinazione specificato.

Sintassi

IPHLPAPI_DLL_LINKAGE DWORD SendARP(
  [in]      IPAddr DestIP,
  [in]      IPAddr SrcIP,
  [out]     PVOID  pMacAddr,
  [in, out] PULONG PhyAddrLen
);

Parametri

[in] DestIP

Indirizzo IPv4 di destinazione, sotto forma di struttura IPAddr . La richiesta ARP tenta di ottenere l'indirizzo fisico corrispondente a questo indirizzo IPv4.

[in] SrcIP

Indirizzo IPv4 di origine del mittente, sotto forma di struttura IPAddr . Questo parametro è facoltativo e viene usato per selezionare l'interfaccia per inviare la richiesta per la voce ARP. Il chiamante può specificare zero corrispondente all'indirizzo IPv4 INADDR_ANY per questo parametro.

[out] pMacAddr

Puntatore a una matrice di variabili ULONG . Questa matrice deve avere almeno due elementi ULONG per contenere un indirizzo fisico Ethernet o un anello di token. I primi sei byte di questa matrice ricevono l'indirizzo fisico corrispondente all'indirizzo IPv4 specificato dal parametro DestIP .

[in, out] PhyAddrLen

In input, un puntatore a un valore ULONG che specifica la dimensione massima del buffer, in byte, l'applicazione ha messo da parte per ricevere l'indirizzo fisico o l'indirizzo MAC. Le dimensioni del buffer devono essere di almeno 6 byte per un indirizzo fisico Ethernet o token ring

Il buffer a cui ricevere l'indirizzo fisico fa riferimento al parametro pMacAddr .

In caso di output riuscito, questo parametro punta a un valore che specifica il numero di byte scritti nel buffer a cui punta pMacAddr.

Valore restituito

Se la funzione ha esito positivo, il valore restituito viene NO_ERROR.

Se la funzione ha esito negativo, il valore restituito è uno dei codici di errore seguenti.

Commenti

La funzione SendARP viene usata per richiedere l'indirizzo hardware fisico (talvolta definito indirizzo MAC) che corrisponde a un indirizzo IPv4 di destinazione specificato. Se le informazioni richieste non sono presenti nella tabella ARP nel computer locale, la funzione SendARP causerà l'invio di una richiesta ARP per ottenere l'indirizzo fisico. Se la funzione ha esito positivo, l'indirizzo fisico corrispondente all'indirizzo IPv4 di destinazione specificato viene restituito nella matrice a cui punta il parametro pMacAddr .

L'indirizzo fisico di un indirizzo IPv4 è disponibile solo se l'indirizzo IPv4 di destinazione si trova nella subnet locale (l'indirizzo IPv4 può essere raggiunto direttamente senza passare attraverso router). La funzione SendARP avrà esito negativo se l'indirizzo IPv4 di destinazione non si trova nella subnet locale.

Se la funzione SendARP ha esito positivo in Windows Vista e versioni successive, la tabella ARP nel computer locale viene aggiornata con i risultati. Se la funzione SendARP ha esito positivo in Windows Server 2003 e versioni precedenti, la tabella ARP nel computer locale non è interessata.

La funzione SendARP in Windows Vista e versioni successive restituisce valori restituiti di errore diversi rispetto alla funzione SendARP in Windows Server 2003 e versioni precedenti.

In Windows Vista e versioni successive, un puntatore NULL passato come parametro pMacAddr o PhyAddrLen alla funzione SendARP causa una violazione di accesso e l'applicazione viene terminata. Se si verifica un errore in Windows Vista e versioni successive e ERROR_BAD_NET_NAME, ERROR_BUFFER_OVERFLOW o ERROR_NOT_FOUND viene restituito, il valore ULONG a cui punta il parametro PhyAddrLen è impostato su zero. Se il valore ULONG a cui punta il parametro PhyAddrLen è minore di 6 in Windows Vista e versioni successive, la funzione SendARP restituisce ERROR_BUFFER_OVERFLOW indicante che il buffer per ricevere l'indirizzo fisico è troppo piccolo. Se il parametro SrcIp specifica un indirizzo IPv4 che non è un'interfaccia nel computer locale, la funzione SendARP in Windows Vista e in seguito restituisce ERROR_NOT_FOUND.

In Windows Server 2003 e versioni precedenti, un puntatore NULL passato come parametro pMacAddr o PhyAddrLen alla funzione SendARP restituisce ERROR_INVALID_PARAMETER. Se si verifica un errore in Windows Server 2003 e versioni precedenti e ERROR_GEN_FAILURE o ERROR_INVALID_USER_BUFFER viene restituito, il valore ULONG a cui punta il parametro PhyAddrLen viene impostato su zero. Se il valore ULONG a cui punta il parametro PhyAddrLen è minore di 6 in Windows Server 2003 e versioni precedenti, la funzione SendARP non restituisce un errore ma restituisce solo parte dell'indirizzo hardware nella matrice a cui punta il parametro pMacAddr . Pertanto, se il valore a cui punta il parametro PhyAddrLen è 4, solo i primi 4 byte dell'indirizzo hardware vengono restituiti nella matrice a cui punta il parametro pMacAddr . Se il parametro SrcIp specifica un indirizzo IPv4 che non è un'interfaccia nel computer locale, la funzione SendARP in Windows Server 2003 e versioni precedenti ignora il parametro SrcIp e usa un indirizzo IPv4 nel computer locale per l'indirizzo IPv4 di origine.

La funzione GetIpNetTable recupera la tabella ARP nel computer locale che esegue il mapping degli indirizzi IPv4 agli indirizzi fisici.

La funzione CreateIpNetEntry crea una voce ARP nella tabella ARP nel computer locale.

La funzione DeleteIpNetEntry elimina una voce ARP dalla tabella ARP nel computer locale.

La funzione SetIpNetEntry modifica una voce ARP esistente nella tabella ARP nel computer locale.

La funzione FlushIpNetTable elimina tutte le voci ARP per l'interfaccia specificata dalla tabella ARP nel computer locale.

In Windows Vista e versioni successive la funzione ResolveIpNetEntry2 può essere usata per sostituire la funzione SendARP . Viene inviata una richiesta ARP se il membro Address della struttura MIB_IPNET_ROW2 passata alla funzione ResolveIpNetEntry2 è un indirizzo IPv4.

In Windows Vista è possibile usare un nuovo gruppo di funzioni per accedere, modificare ed eliminare le voci della tabella ARP quando il membro Address della struttura MIB_IPNET_ROW2 passata a queste funzioni è un indirizzo IPv4. Le nuove funzioni includono: GetIpNetTable2, CreateIpNetEntry2, DeleteIpNetEntry2, FlushIpNetTable2 e SetIpNetEntry2.

Per informazioni sul tipo di dati IPAddr , vedere Tipi di dati Windows. Per convertire un indirizzo IP tra notazione decimale punteggiata e formato IPAddr , usare le funzioni inet_addr e inet_ntoa .

Esempio

Il codice seguente illustra come ottenere l'indirizzo MAC (Hardware o Media Access Control) associato a un indirizzo IPv4 specificato.

#ifndef WIN32_LEAN_AND_MEAN
#define WIN32_LEAN_AND_MEAN
#endif

#include <winsock2.h>
#include <iphlpapi.h>
#include <stdio.h>
#include <stdlib.h>

#pragma comment(lib, "iphlpapi.lib")
#pragma comment(lib, "ws2_32.lib")

void usage(char *pname)
{
    printf("Usage: %s [options] ip-address\n", pname);
    printf("\t -h \t\thelp\n");
    printf("\t -l length \tMAC physical address length to set\n");
    printf("\t -s src-ip \tsource IP address\n");
    exit(1);
}

int __cdecl main(int argc, char **argv)
{
    DWORD dwRetVal;
    IPAddr DestIp = 0;
    IPAddr SrcIp = 0;       /* default for src ip */
    ULONG MacAddr[2];       /* for 6-byte hardware addresses */
    ULONG PhysAddrLen = 6;  /* default to length of six bytes */

    char *DestIpString = NULL;
    char *SrcIpString = NULL;

    BYTE *bPhysAddr;
    unsigned int i;

    if (argc > 1) {
        for (i = 1; i < (unsigned int) argc; i++) {
            if ((argv[i][0] == '-') || (argv[i][0] == '/')) {
                switch (tolower(argv[i][1])) {
                case 'l':
                    PhysAddrLen = (ULONG) atol(argv[++i]);
                    break;
                case 's':
                    SrcIpString = argv[++i];
                    SrcIp = inet_addr(SrcIpString);
                    break;
                case 'h':
                default:
                    usage(argv[0]);
                    break;
                }               /* end switch */
            } else
                DestIpString = argv[i];
        }                       /* end for */
    } else
        usage(argv[0]);

    if (DestIpString == NULL || DestIpString[0] == '\0')
        usage(argv[0]);

    DestIp = inet_addr(DestIpString);

    memset(&MacAddr, 0xff, sizeof (MacAddr));

    printf("Sending ARP request for IP address: %s\n", DestIpString);

    dwRetVal = SendARP(DestIp, SrcIp, &MacAddr, &PhysAddrLen);

    if (dwRetVal == NO_ERROR) {
        bPhysAddr = (BYTE *) & MacAddr;
        if (PhysAddrLen) {
            for (i = 0; i < (int) PhysAddrLen; i++) {
                if (i == (PhysAddrLen - 1))
                    printf("%.2X\n", (int) bPhysAddr[i]);
                else
                    printf("%.2X-", (int) bPhysAddr[i]);
            }
        } else
            printf
                ("Warning: SendArp completed successfully, but returned length=0\n");

    } else {
        printf("Error: SendArp failed with error: %d", dwRetVal);
        switch (dwRetVal) {
        case ERROR_GEN_FAILURE:
            printf(" (ERROR_GEN_FAILURE)\n");
            break;
        case ERROR_INVALID_PARAMETER:
            printf(" (ERROR_INVALID_PARAMETER)\n");
            break;
        case ERROR_INVALID_USER_BUFFER:
            printf(" (ERROR_INVALID_USER_BUFFER)\n");
            break;
        case ERROR_BAD_NET_NAME:
            printf(" (ERROR_GEN_FAILURE)\n");
            break;
        case ERROR_BUFFER_OVERFLOW:
            printf(" (ERROR_BUFFER_OVERFLOW)\n");
            break;
        case ERROR_NOT_FOUND:
            printf(" (ERROR_NOT_FOUND)\n");
            break;
        default:
            printf("\n");
            break;
        }
    }

    return 0;
}

Requisiti

Vedi anche

CreateIpNetEntry

CreateIpNetEntry2

CreateProxyArpEntry

DeleteIpNetEntry

DeleteIpNetEntry2

DeleteProxyArpEntry

FlushIpNetTable

FlushIpNetTable2

GetIpNetEntry2

GetIpNetTable2

Informazioni di riferimento sulle funzioni helper IP

Pagina iniziale dell'helper IP

IPAddr

ResolveIpNetEntry2

SetIpNetEntry

SetIpNetEntry2