Функция SendARP (iphlpapi.h)
Функция SendARP отправляет запрос протокола разрешения адресов (ARP) для получения физического адреса, соответствующего указанному целевому IPv4-адресу.
Синтаксис
IPHLPAPI_DLL_LINKAGE DWORD SendARP(
[in] IPAddr DestIP,
[in] IPAddr SrcIP,
[out] PVOID pMacAddr,
[in, out] PULONG PhyAddrLen
);
Параметры
[in] DestIP
Целевой IPv4-адрес в виде структуры IPAddr . Запрос ARP пытается получить физический адрес, соответствующий этому IPv4-адресу.
[in] SrcIP
Исходный IPv4-адрес отправителя в виде структуры IPAddr . Этот параметр является необязательным и используется для выбора интерфейса для отправки запроса для записи ARP. Вызывающий объект может указать ноль, соответствующий INADDR_ANY IPv4-адресу для этого параметра.
[out] pMacAddr
Указатель на массив переменных ULONG . Этот массив должен содержать по крайней мере два элемента ULONG для хранения физического адреса Ethernet или круга токенов. Первые шесть байтов этого массива получают физический адрес, соответствующий IPv4-адресу, указанному параметром DestIP .
[in, out] PhyAddrLen
На входных данных — указатель на значение ULONG , указывающее максимальный размер буфера в байтах, которое приложение выделило для получения физического адреса или MAC-адреса. Размер буфера должен быть не менее 6 байт для физического адреса Ethernet или круга токенов.
На буфер для получения физического адреса указывает параметр pMacAddr .
При успешном выводе этот параметр указывает на значение, указывающее количество байтов, записанных в буфер, на который указывает pMacAddr.
Возвращаемое значение
Если функция выполняется успешно, возвращаемое значение будет NO_ERROR.
Если функция завершается сбоем, возвращаемое значение представляет собой один из следующих кодов ошибок.
| Код возврата | Описание |
|---|---|
|
Не найдено сетевое имя". Эта ошибка возвращается в Windows Vista и более поздних версиях, когда ответ ARP на запрос SendARP не был получен. Эта ошибка возникает, если не удалось получить доступ к целевому IPv4-адресу, так как он находится не в той же подсети или конечный компьютер не работает. |
|
Имя файла слишком длинное. Эта ошибка возвращается в Windows Vista, если значение ULONG , на которое указывает параметр PhyAddrLen , меньше 6, размер, необходимый для хранения полного физического адреса. |
|
Устройство, подключенное к системе, не работает. Эта ошибка возвращается в Windows Server 2003 и более ранних версиях, если ответ ARP на запрос SendARP не был получен. Эта ошибка может возникнуть, если не удалось получить доступ к целевому IPv4-адресу, так как он находится не в той же подсети или конечный компьютер не работает. |
|
Один из параметров является недопустимым. Эта ошибка возвращается в Windows Server 2003 и более ранних версиях, если параметр pMacAddr или PhyAddrLen является указателем NULL . |
|
Предоставленный буфер пользователя недопустим для запрошенной операции. Эта ошибка возвращается в Windows Server 2003 и более ранних версиях, если значение ULONG , на которое указывает параметр PhyAddrLen , равно нулю. |
|
Элемент не найден. Эта ошибка возвращается в Windows Vista, если параметр SrcIp не указывает исходный IPv4-адрес в интерфейсе локального компьютера или IP-адрес INADDR_ANY (IPv4-адрес 0.0.0.0). |
|
Функция SendARP не поддерживается операционной системой, работающей на локальном компьютере. |
|
Если функция завершается сбоем, используйте FormatMessage , чтобы получить строку сообщения для возвращаемой ошибки. |
Комментарии
Функция SendARP используется для запроса физического аппаратного адреса (иногда называемого MAC-адресом), соответствующего указанному IPv4-адресу назначения. Если запрошенная информация отсутствует в таблице ARP на локальном компьютере, функция SendARP вызовет отправку запроса ARP для получения физического адреса. Если функция выполнена успешно, физический адрес, соответствующий указанному IPv4-адресу назначения, возвращается в массиве, на который указывает параметр pMacAddr .
Физический адрес IPv4-адреса доступен только в том случае, если целевой IPv4-адрес находится в локальной подсети (адрес IPv4 можно получить напрямую, не проходя через маршрутизаторы). Функция SendARP завершится ошибкой, если целевой IPv4-адрес не находится в локальной подсети.
При успешном выполнении функции SendARP в Windows Vista и более поздних версиях таблица ARP на локальном компьютере обновляется с учетом результатов. При успешном выполнении функции SendARP в Windows Server 2003 и более ранних версиях таблица ARP на локальном компьютере не затрагивается.
Функция SendARP в Windows Vista и более поздних версиях возвращает значения ошибок, отличные от функции SendARP в Windows Server 2003 и более ранних версиях.
В Windows Vista и более поздних версиях указатель NULL , передаваемый в качестве параметра pMacAddr или PhyAddrLen в функцию SendARP , приводит к нарушению доступа, и приложение завершается. Если в Windows Vista и более поздних версиях возникает ошибка и возвращается ERROR_BAD_NET_NAME, ERROR_BUFFER_OVERFLOW или ERROR_NOT_FOUND , значение ULONG , на которое указывает параметр PhyAddrLen , устанавливается равным нулю. Если значение ULONG , на которое указывает параметр PhyAddrLen , в Windows Vista и более поздних версиях меньше 6, функция SendARP возвращает ERROR_BUFFER_OVERFLOW , указывающую, что буфер для получения физического адреса слишком мал. Если параметр SrcIp указывает IPv4-адрес, который не является интерфейсом на локальном компьютере, функция SendARP в Windows Vista и более поздних версий возвращает ERROR_NOT_FOUND.
В Windows Server 2003 и более ранних версиях указатель NULL , передаваемый в качестве параметра pMacAddr или PhyAddrLen в функцию SendARP , возвращает ERROR_INVALID_PARAMETER. Если в Windows Server 2003 и более ранних версиях возникает ошибка и возвращается ERROR_GEN_FAILURE или ERROR_INVALID_USER_BUFFER , значение ULONG , на которое указывает параметр PhyAddrLen , устанавливается равным нулю. Если значение ULONG , на которое указывает параметр PhyAddrLen , меньше 6 в Windows Server 2003 и более ранних версиях, функция SendARP не возвращает ошибку, а возвращает только часть аппаратного адреса в массиве, на который указывает параметр pMacAddr . Поэтому если значение, на которое указывает параметр PhyAddrLen , равно 4, то в массиве, на который указывает параметр pMacAddr , возвращаются только первые 4 байта аппаратного адреса. Если параметр SrcIp указывает IPv4-адрес, который не является интерфейсом на локальном компьютере, функция SendARP в Windows Server 2003 и более ранних версиях игнорирует параметр SrcIp и использует IPv4-адрес на локальном компьютере для исходного IPv4-адреса.
Функция GetIpNetTable извлекает таблицу ARP на локальном компьютере, которая сопоставляет IPv4-адреса с физическими адресами.
Функция CreateIpNetEntry создает запись ARP в таблице ARP на локальном компьютере.
Функция DeleteIpNetEntry удаляет запись ARP из таблицы ARP на локальном компьютере.
Функция SetIpNetEntry изменяет существующую запись ARP в таблице ARP на локальном компьютере.
Функция FlushIpNetTable удаляет все записи ARP для указанного интерфейса из таблицы ARP на локальном компьютере.
В Windows Vista и более поздних версиях функция ResolveIpNetEntry2 может использоваться для замены функции SendARP . Запрос ARP отправляется, если элемент addressструктуры MIB_IPNET_ROW2 , передаваемый в функцию ResolveIpNetEntry2 , является IPv4-адресом.
В Windows Vista новую группу функций можно использовать для доступа, изменения и удаления записей таблицы ARP, если элементом Addressструктуры MIB_IPNET_ROW2 , передаваемой этим функциям, является IPv4-адрес. Новые функции включают следующие: GetIpNetTable2, CreateIpNetEntry2, DeleteIpNetEntry2, FlushIpNetTable2 и SetIpNetEntry2.
Сведения о типе данных IPAddr см. в разделе Типы данных Windows. Чтобы преобразовать IP-адрес между десятичными знаками с точками и форматом IPAddr , используйте функции inet_addr и inet_ntoa .
Примеры
В следующем коде показано, как получить MAC-адрес, связанный с указанным IPv4-адресом.
#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;
}
Требования
| Требование | Значение |
|---|---|
| Минимальная версия клиента | Windows 2000 Professional [только классические приложения] |
| Минимальная версия сервера | Windows 2000 Server [только классические приложения] |
| Целевая платформа | Windows |
| Header | iphlpapi.h |
| Библиотека | Iphlpapi.lib |
| DLL | Iphlpapi.dll |
См. также раздел
Справочник по вспомогательной функции IP