Compartilhar via


Função SendARP (iphlpapi.h)

A função SendARP envia uma solicitação ARP (Address Resolution Protocol) para obter o endereço físico que corresponde ao endereço IPv4 de destino especificado.

Sintaxe

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

Parâmetros

[in] DestIP

O endereço IPv4 de destino, na forma de uma estrutura IPAddr . A solicitação ARP tenta obter o endereço físico que corresponde a esse endereço IPv4.

[in] SrcIP

O endereço IPv4 de origem do remetente, na forma de uma estrutura IPAddr . Esse parâmetro é opcional e é usado para selecionar a interface para enviar a solicitação para a entrada ARP. O chamador pode especificar zero correspondente ao endereço IPv4 INADDR_ANY para esse parâmetro.

[out] pMacAddr

Um ponteiro para uma matriz de variáveis ULONG . Essa matriz deve ter pelo menos dois elementos ULONG para conter um endereço físico de anel de token ou Ethernet. Os primeiros seis bytes dessa matriz recebem o endereço físico que corresponde ao endereço IPv4 especificado pelo parâmetro DestIP .

[in, out] PhyAddrLen

Na entrada, um ponteiro para um valor ULONG que especifica o tamanho máximo do buffer, em bytes, o aplicativo foi reservado para receber o endereço físico ou o endereço MAC. O tamanho do buffer deve ser de pelo menos 6 bytes para um endereço físico de anel de token ou Ethernet

O buffer para receber o endereço físico é apontado pelo parâmetro pMacAddr .

Na saída bem-sucedida, esse parâmetro aponta para um valor que especifica o número de bytes gravados no buffer apontado pelo pMacAddr.

Retornar valor

Se a função for bem-sucedida, o valor retornado será NO_ERROR.

Se a função falhar, o valor retornado será um dos códigos de erro a seguir.

Código de retorno Descrição
ERROR_BAD_NET_NAME
O nome de rede não foi encontrado. Esse erro é retornado no Windows Vista e posteriormente quando uma resposta ARP à solicitação SendARP não foi recebida. Esse erro ocorrerá se o endereço IPv4 de destino não puder ser acessado porque ele não está na mesma sub-rede ou se o computador de destino não está operando.
ERROR_BUFFER_OVERFLOW
O nome do arquivo é muito longo. Esse erro será retornado no Windows Vista se o valor ULONG apontado pelo parâmetro PhyAddrLen for menor que 6, o tamanho necessário para armazenar um endereço físico completo.
ERROR_GEN_FAILURE
Um dispositivo conectado ao sistema não está funcionando. Esse erro é retornado no Windows Server 2003 e anterior quando uma resposta ARP à solicitação SendARP não foi recebida. Esse erro poderá ocorrer se o endereço IPv4 de destino não puder ser acessado porque ele não está na mesma sub-rede ou se o computador de destino não está operando.
ERROR_INVALID_PARAMETER
Um dos parâmetros é inválido. Esse erro será retornado no Windows Server 2003 e anterior se o parâmetro pMacAddr ou PhyAddrLen for um ponteiro NULL .
ERROR_INVALID_USER_BUFFER
O buffer de usuário fornecido não é válido para a operação solicitada. Esse erro será retornado no Windows Server 2003 e anterior se o valor ULONG apontado pelo parâmetro PhyAddrLen for zero.
ERROR_NOT_FOUND
Elemento não encontrado. Esse erro será retornado no Windows Vista se o parâmetro SrcIp não especificar um endereço IPv4 de origem em uma interface no computador local ou o endereço IP INADDR_ANY (um endereço IPv4 de 0.0.0.0).
ERROR_NOT_SUPPORTED
A função SendARP não tem suporte do sistema operacional em execução no computador local.
Outros
Se a função falhar, use FormatMessage para obter a cadeia de caracteres de mensagem para o erro retornado.

Comentários

A função SendARP é usada para solicitar o endereço de hardware físico (às vezes chamado de endereço MAC) que corresponde a um endereço IPv4 de destino especificado. Se as informações solicitadas não estiverem na tabela ARP no computador local, a função SendARP fará com que uma solicitação ARP seja enviada para obter o endereço físico. Se a função for bem-sucedida, o endereço físico que corresponde ao endereço IPv4 de destino especificado será retornado na matriz apontada pelo parâmetro pMacAddr .

O endereço físico de um endereço IPv4 só estará disponível se o endereço IPv4 de destino estiver na sub-rede local (o endereço IPv4 pode ser acessado diretamente sem passar por nenhum roteador). A função SendARP falhará se o endereço IPv4 de destino não estiver na sub-rede local.

Se a função SendARP for bem-sucedida no Windows Vista e posterior, a tabela ARP no computador local será atualizada com os resultados. Se a função SendARP for bem-sucedida no Windows Server 2003 e anterior, a tabela ARP no computador local não será afetada.

A função SendARP no Windows Vista e posterior retorna valores de retorno de erro diferentes da função SendARP no Windows Server 2003 e anterior.

No Windows Vista e posterior, um ponteiro NULL passado como o parâmetro pMacAddr ou PhyAddrLen para a função SendARP causa uma violação de acesso e o aplicativo é encerrado. Se ocorrer um erro no Windows Vista e posterior e ERROR_BAD_NET_NAME, ERROR_BUFFER_OVERFLOW ou ERROR_NOT_FOUND for retornado, o valor ULONG apontado pelo parâmetro PhyAddrLen será definido como zero. Se o valor ULONG apontado pelo parâmetro PhyAddrLen for menor que 6 no Windows Vista e posterior, a função SendARP retornará ERROR_BUFFER_OVERFLOW indicando que o buffer para receber o endereço físico é muito pequeno. Se o parâmetro SrcIp especificar um endereço IPv4 que não seja uma interface no computador local, a função SendARP no Windows Vista e posteriormente retornará ERROR_NOT_FOUND.

No Windows Server 2003 e anteriores, um ponteiro NULL passado como o parâmetro pMacAddr ou PhyAddrLen para a função SendARP retorna ERROR_INVALID_PARAMETER. Se ocorrer um erro no Windows Server 2003 e anterior e ERROR_GEN_FAILURE ou ERROR_INVALID_USER_BUFFER for retornado, o valor ULONG apontado pelo parâmetro PhyAddrLen será definido como zero. Se o valor ULONG apontado pelo parâmetro PhyAddrLen for menor que 6 no Windows Server 2003 e anterior, a função SendARP não retornará um erro, mas retornará apenas parte do endereço de hardware na matriz apontada pelo parâmetro pMacAddr . Portanto, se o valor apontado pelo parâmetro PhyAddrLen for 4, somente os primeiros 4 bytes do endereço de hardware serão retornados na matriz apontada pelo parâmetro pMacAddr . Se o parâmetro SrcIp especificar um endereço IPv4 que não seja uma interface no computador local, a função SendARP no Windows Server 2003 e anteriores ignorará o parâmetro SrcIp e usará um endereço IPv4 no computador local para o endereço IPv4 de origem.

A função GetIpNetTable recupera a tabela ARP no computador local que mapeia endereços IPv4 para endereços físicos.

A função CreateIpNetEntry cria uma entrada ARP na tabela ARP no computador local.

A função DeleteIpNetEntry exclui uma entrada ARP da tabela ARP no computador local.

A função SetIpNetEntry modifica uma entrada ARP existente na tabela ARP no computador local.

A função FlushIpNetTable exclui todas as entradas ARP para a interface especificada da tabela ARP no computador local.

No Windows Vista e posterior, a função ResolveIpNetEntry2 pode ser usada para substituir a função SendARP . Uma solicitação ARP será enviada se o membro Address da estrutura MIB_IPNET_ROW2 passada para a função ResolveIpNetEntry2 for um endereço IPv4.

No Windows Vista, um novo grupo de funções pode ser usado para acessar, modificar e excluir as entradas da tabela ARP quando o membro Address da estrutura MIB_IPNET_ROW2 passada para essas funções for um endereço IPv4. As novas funções incluem: GetIpNetTable2, CreateIpNetEntry2, DeleteIpNetEntry2, FlushIpNetTable2 e SetIpNetEntry2.

Para obter informações sobre o tipo de dados IPAddr , consulte Tipos de dados do Windows. Para converter um endereço IP entre a notação decimal pontilhada e o formato IPAddr , use as funções inet_addr e inet_ntoa .

Exemplos

O código a seguir demonstra como obter o endereço MAC (controle de acesso à mídia) ou hardware associado a um endereço IPv4 especificado.

#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;
}


Requisitos

Requisito Valor
Cliente mínimo com suporte Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino Windows
Cabeçalho iphlpapi.h
Biblioteca Iphlpapi.lib
DLL Iphlpapi.dll

Confira também

CreateIpNetEntry

CreateIpNetEntry2

CreateProxyArpEntry

DeleteIpNetEntry

DeleteIpNetEntry2

DeleteProxyArpEntry

FlushIpNetTable

FlushIpNetTable2

GetIpNetEntry2

GetIpNetTable2

Referência de função auxiliar de IP

Página Inicial do Auxiliar de IP

Ipaddr

ResolveIpNetEntry2

SetIpNetEntry

SetIpNetEntry2