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.
| Codice restituito | Descrizione |
|---|---|
|
Impossibile trovare il nome della rete. Questo errore viene restituito in Windows Vista e versioni successive quando non è stata ricevuta una risposta ARP alla richiesta SendARP . Questo errore si verifica se non è stato possibile raggiungere l'indirizzo IPv4 di destinazione perché non si trova nella stessa subnet o il computer di destinazione non è operativo. |
|
Il nome del file è troppo lungo. Questo errore viene restituito in Windows Vista se il valore ULONG a cui punta il parametro PhyAddrLen è minore di 6, le dimensioni necessarie per archiviare un indirizzo fisico completo. |
|
Un dispositivo collegato al sistema non funziona. Questo errore viene restituito in Windows Server 2003 e versioni precedenti quando non è stata ricevuta una risposta ARP alla richiesta SendARP . Questo errore può verificarsi se non è stato possibile raggiungere l'indirizzo IPv4 di destinazione perché non si trova nella stessa subnet o il computer di destinazione non funziona. |
|
Uno dei parametri non è valido. Questo errore viene restituito in Windows Server 2003 e versioni precedenti se il parametro pMacAddr o PhyAddrLen è un puntatore NULL . |
|
Il buffer utente fornito non è valido per l'operazione richiesta. Questo errore viene restituito in Windows Server 2003 e versioni precedenti se il valore ULONG a cui punta il parametro PhyAddrLen è zero. |
|
Element not found. Questo errore viene restituito in Windows Vista se il parametro SrcIp non specifica un indirizzo IPv4 di origine in un'interfaccia nel computer locale o l'indirizzo IP INADDR_ANY (indirizzo IPv4 0.0.0.0). |
|
La funzione SendARP non è supportata dal sistema operativo in esecuzione nel computer locale. |
|
Se la funzione ha esito negativo, usare FormatMessage per ottenere la stringa del messaggio per l'errore restituito. |
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
| Requisito | Valore |
|---|---|
| Client minimo supportato | Windows 2000 Professional [solo app desktop] |
| Server minimo supportato | Windows 2000 Server [solo app desktop] |
| Piattaforma di destinazione | Windows |
| Intestazione | iphlpapi.h |
| Libreria | Iphlpapi.lib |
| DLL | Iphlpapi.dll |
Vedi anche
Informazioni di riferimento sulle funzioni helper IP