Поделиться через


Функция 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.

Если функция завершается сбоем, возвращаемое значение представляет собой один из следующих кодов ошибок.

Код возврата Описание
ERROR_BAD_NET_NAME
Не найдено сетевое имя". Эта ошибка возвращается в Windows Vista и более поздних версиях, когда ответ ARP на запрос SendARP не был получен. Эта ошибка возникает, если не удалось получить доступ к целевому IPv4-адресу, так как он находится не в той же подсети или конечный компьютер не работает.
ERROR_BUFFER_OVERFLOW
Имя файла слишком длинное. Эта ошибка возвращается в Windows Vista, если значение ULONG , на которое указывает параметр PhyAddrLen , меньше 6, размер, необходимый для хранения полного физического адреса.
ERROR_GEN_FAILURE
Устройство, подключенное к системе, не работает. Эта ошибка возвращается в Windows Server 2003 и более ранних версиях, если ответ ARP на запрос SendARP не был получен. Эта ошибка может возникнуть, если не удалось получить доступ к целевому IPv4-адресу, так как он находится не в той же подсети или конечный компьютер не работает.
ERROR_INVALID_PARAMETER
Один из параметров является недопустимым. Эта ошибка возвращается в Windows Server 2003 и более ранних версиях, если параметр pMacAddr или PhyAddrLen является указателем NULL .
ERROR_INVALID_USER_BUFFER
Предоставленный буфер пользователя недопустим для запрошенной операции. Эта ошибка возвращается в Windows Server 2003 и более ранних версиях, если значение ULONG , на которое указывает параметр PhyAddrLen , равно нулю.
ERROR_NOT_FOUND
Элемент не найден. Эта ошибка возвращается в Windows Vista, если параметр SrcIp не указывает исходный IPv4-адрес в интерфейсе локального компьютера или IP-адрес INADDR_ANY (IPv4-адрес 0.0.0.0).
ERROR_NOT_SUPPORTED
Функция 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

См. также раздел

CreateIpNetEntry

CreateIpNetEntry2

CreateProxyArpEntry

DeleteIpNetEntry

DeleteIpNetEntry2

DeleteProxyArpEntry

FlushIpNetTable

FlushIpNetTable2

GetIpNetEntry2

GetIpNetTable2

Справочник по вспомогательной функции IP

Начальная страница вспомогательного ip-адреса

IPAddr

ResolveIpNetEntry2

SetIpNetEntry

SetIpNetEntry2