SendARP, fonction (iphlpapi.h)
La fonction SendARP envoie une requête ARP (Address Resolution Protocol) pour obtenir l’adresse physique qui correspond à l’adresse IPv4 de destination spécifiée.
Syntaxe
IPHLPAPI_DLL_LINKAGE DWORD SendARP(
[in] IPAddr DestIP,
[in] IPAddr SrcIP,
[out] PVOID pMacAddr,
[in, out] PULONG PhyAddrLen
);
Paramètres
[in] DestIP
Adresse IPv4 de destination, sous la forme d’une structure IPAddr . La requête ARP tente d’obtenir l’adresse physique qui correspond à cette adresse IPv4.
[in] SrcIP
Adresse IPv4 source de l’expéditeur, sous la forme d’une structure IPAddr . Ce paramètre est facultatif et est utilisé pour sélectionner l’interface sur laquelle envoyer la demande pour l’entrée ARP. L’appelant peut spécifier zéro correspondant à l’adresse IPv4 INADDR_ANY pour ce paramètre.
[out] pMacAddr
Pointeur vers un tableau de variables ULONG . Ce tableau doit avoir au moins deux éléments ULONG pour contenir une adresse physique Ethernet ou d’anneau de jeton. Les six premiers octets de ce tableau reçoivent l’adresse physique qui correspond à l’adresse IPv4 spécifiée par le paramètre DestIP .
[in, out] PhyAddrLen
Lors de l’entrée, pointeur vers une valeur ULONG qui spécifie la taille maximale de la mémoire tampon, en octets, l’application a mis de côté pour recevoir l’adresse physique ou l’adresse MAC. La taille de la mémoire tampon doit être d’au moins 6 octets pour une adresse physique Ethernet ou en anneau de jeton
La mémoire tampon vers laquelle recevoir l’adresse physique est pointée par le paramètre pMacAddr .
En cas de sortie réussie, ce paramètre pointe vers une valeur qui spécifie le nombre d’octets écrits dans la mémoire tampon pointée par le pMacAddr.
Valeur retournée
Si la fonction réussit, la valeur de retour est NO_ERROR.
Si la fonction échoue, la valeur de retour est l’un des codes d’erreur suivants.
| Code de retour | Description |
|---|---|
|
Le nom du réseau est introuvable. Cette erreur est retournée sur Windows Vista et versions ultérieures lorsqu’une réponse ARP à la requête SendARP n’a pas été reçue. Cette erreur se produit si l’adresse IPv4 de destination n’a pas pu être atteinte, car elle ne se trouve pas sur le même sous-réseau ou si l’ordinateur de destination ne fonctionne pas. |
|
Le nom du fichier est trop long. Cette erreur est retournée sur Windows Vista si la valeur ULONG pointée par le paramètre PhyAddrLen est inférieure à 6, la taille requise pour stocker une adresse physique complète. |
|
Un périphérique connecté au système ne fonctionne pas. Cette erreur est retournée sur Windows Server 2003 et versions antérieures lorsqu’une réponse ARP à la requête SendARP n’a pas été reçue. Cette erreur peut se produire si l’adresse IPv4 de destination n’a pas pu être atteinte, car elle ne se trouve pas sur le même sous-réseau ou si l’ordinateur de destination ne fonctionne pas. |
|
L’un des paramètres n’est pas valide. Cette erreur est retournée sur Windows Server 2003 et versions antérieures si le paramètre pMacAddr ou PhyAddrLen est un pointeur NULL . |
|
La mémoire tampon utilisateur fournie n’est pas valide pour l’opération demandée. Cette erreur est retournée sur Windows Server 2003 et versions antérieures si la valeur ULONG pointée par le paramètre PhyAddrLen est zéro. |
|
Element not found. Cette erreur est retournée sur Windows Vista si le paramètre SrcIp ne spécifie pas d’adresse IPv4 source sur une interface sur l’ordinateur local ou l’adresse IP INADDR_ANY (adresse IPv4 de 0.0.0.0). |
|
La fonction SendARP n’est pas prise en charge par le système d’exploitation exécuté sur l’ordinateur local. |
|
Si la fonction échoue, utilisez FormatMessage pour obtenir la chaîne de message de l’erreur retournée. |
Remarques
La fonction SendARP est utilisée pour demander l’adresse matérielle physique (parfois appelée adresse MAC) qui correspond à une adresse IPv4 de destination spécifiée. Si les informations demandées ne se situent pas dans la table ARP sur l’ordinateur local, la fonction SendARP entraîne l’envoi d’une demande ARP pour obtenir l’adresse physique. Si la fonction réussit, l’adresse physique qui correspond à l’adresse IPv4 de destination spécifiée est retournée dans le tableau vers lequel pointe le paramètre pMacAddr .
L’adresse physique d’une adresse IPv4 n’est disponible que si l’adresse IPv4 de destination se trouve sur le sous-réseau local (l’adresse IPv4 est accessible directement sans passer par les routeurs). La fonction SendARP échoue si l’adresse IPv4 de destination n’est pas sur le sous-réseau local.
Si la fonction SendARP réussit sur Windows Vista et versions ultérieures, la table ARP sur l’ordinateur local est mise à jour avec les résultats. Si la fonction SendARP réussit sur Windows Server 2003 et versions antérieures, la table ARP sur l’ordinateur local n’est pas affectée.
La fonction SendARP sur Windows Vista et ultérieurement retourne des valeurs de retour d’erreur différentes de celles de la fonction SendARP sur Windows Server 2003 et versions antérieures.
Sur Windows Vista et versions ultérieures, un pointeur NULL passé en tant que paramètre pMacAddr ou PhyAddrLen à la fonction SendARP provoque une violation d’accès et l’application est arrêtée. Si une erreur se produit sur Windows Vista et versions ultérieures et ERROR_BAD_NET_NAME, ERROR_BUFFER_OVERFLOW ou ERROR_NOT_FOUND est retourné, la valeur ULONG pointée par le paramètre PhyAddrLen est définie sur zéro. Si la valeur ULONG pointée par le paramètre PhyAddrLen est inférieure à 6 sur Windows Vista et versions ultérieures, la fonction SendARP retourne ERROR_BUFFER_OVERFLOW indiquant que la mémoire tampon pour recevoir l’adresse physique est trop petite. Si le paramètre SrcIp spécifie une adresse IPv4 qui n’est pas une interface sur l’ordinateur local, la fonction SendARP sur Windows Vista et ultérieurement retourne ERROR_NOT_FOUND.
Sur Windows Server 2003 et versions antérieures, un pointeur NULL passé en tant que paramètre pMacAddr ou PhyAddrLen à la fonction SendARP retourne ERROR_INVALID_PARAMETER. Si une erreur se produit sur Windows Server 2003 et versions antérieures et que ERROR_GEN_FAILURE ou ERROR_INVALID_USER_BUFFER est retourné, la valeur ULONG pointée par le paramètre PhyAddrLen est définie sur zéro. Si la valeur ULONG pointée par le paramètre PhyAddrLen est inférieure à 6 sur Windows Server 2003 et versions antérieures, la fonction SendARP ne retourne pas d’erreur, mais retourne uniquement une partie de l’adresse matérielle dans le tableau pointé par le paramètre pMacAddr . Ainsi, si la valeur pointée par le paramètre PhyAddrLen est 4, seuls les 4 premiers octets de l’adresse matérielle sont retournés dans le tableau vers lequel pointe le paramètre pMacAddr . Si le paramètre SrcIp spécifie une adresse IPv4 qui n’est pas une interface sur l’ordinateur local, la fonction SendARP sur Windows Server 2003 et versions antérieures ignore le paramètre SrcIp et utilise une adresse IPv4 sur l’ordinateur local pour l’adresse IPv4 source.
La fonction GetIpNetTable récupère la table ARP sur l’ordinateur local qui mappe les adresses IPv4 aux adresses physiques.
La fonction CreateIpNetEntry crée une entrée ARP dans la table ARP sur l’ordinateur local.
La fonction DeleteIpNetEntry supprime une entrée ARP de la table ARP sur l’ordinateur local.
La fonction SetIpNetEntry modifie une entrée ARP existante dans la table ARP sur l’ordinateur local.
La fonction FlushIpNetTable supprime toutes les entrées ARP pour l’interface spécifiée de la table ARP sur l’ordinateur local.
Sur Windows Vista et versions ultérieures, la fonction ResolveIpNetEntry2 peut être utilisée pour remplacer la fonction SendARP . Une requête ARP est envoyée si le membre Address de la structure MIB_IPNET_ROW2 passée à la fonction ResolveIpNetEntry2 est une adresse IPv4.
Sur Windows Vista, un nouveau groupe de fonctions peut être utilisé pour accéder aux entrées de table ARP, les modifier et les supprimer lorsque le membre Address de la structure MIB_IPNET_ROW2 passée à ces fonctions est une adresse IPv4. Les nouvelles fonctions incluent les suivantes : GetIpNetTable2, CreateIpNetEntry2, DeleteIpNetEntry2, FlushIpNetTable2 et SetIpNetEntry2.
Pour plus d’informations sur le type de données IPAddr , consultez Types de données Windows. Pour convertir une adresse IP entre la notation décimale en pointillés et le format IPAddr , utilisez les fonctions inet_addr et inet_ntoa .
Exemples
Le code suivant montre comment obtenir l’adresse MAC (contrôle d’accès matériel ou multimédia) associée à une adresse IPv4 spécifiée.
#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;
}
Configuration requise
| Condition requise | Valeur |
|---|---|
| Client minimal pris en charge | Windows 2000 Professionnel [applications de bureau uniquement] |
| Serveur minimal pris en charge | Windows 2000 Server [applications de bureau uniquement] |
| Plateforme cible | Windows |
| En-tête | iphlpapi.h |
| Bibliothèque | Iphlpapi.lib |
| DLL | Iphlpapi.dll |
Voir aussi
Informations de référence sur les fonctions d’assistance IP