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 |
|---|---|
|
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. |
|
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. |
|
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. |
|
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 . |
|
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. |
|
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). |
|
A função SendARP não tem suporte do sistema operacional em execução no computador local. |
|
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
Referência de função auxiliar de IP