Función SendARP (iphlpapi.h)
La función SendARP envía una solicitud del Protocolo de resolución de direcciones (ARP) para obtener la dirección física que corresponde a la dirección IPv4 de destino especificada.
Sintaxis
IPHLPAPI_DLL_LINKAGE DWORD SendARP(
[in] IPAddr DestIP,
[in] IPAddr SrcIP,
[out] PVOID pMacAddr,
[in, out] PULONG PhyAddrLen
);
Parámetros
[in] DestIP
Dirección IPv4 de destino, en forma de una estructura IPAddr . La solicitud ARP intenta obtener la dirección física que corresponde a esta dirección IPv4.
[in] SrcIP
Dirección IPv4 de origen del remitente, en forma de una estructura IPAddr . Este parámetro es opcional y se usa para seleccionar la interfaz en la que se va a enviar la solicitud para la entrada ARP. El llamador puede especificar cero correspondiente a la dirección IPv4 de INADDR_ANY para este parámetro.
[out] pMacAddr
Puntero a una matriz de variables ULONG . Esta matriz debe tener al menos dos elementos ULONG para contener una dirección física ethernet o token ring. Los seis primeros bytes de esta matriz reciben la dirección física que corresponde a la dirección IPv4 especificada por el parámetro DestIP .
[in, out] PhyAddrLen
En la entrada, un puntero a un valor ULONG que especifica el tamaño máximo del búfer, en bytes, la aplicación se ha reservado para recibir la dirección física o la dirección MAC. El tamaño del búfer debe ser de al menos 6 bytes para una dirección física ethernet o de anillo de token.
El búfer al que se va a recibir la dirección física apunta el parámetro pMacAddr .
En la salida correcta, este parámetro apunta a un valor que especifica el número de bytes escritos en el búfer al que apunta pMacAddr.
Valor devuelto
Si la función se realiza correctamente, el valor devuelto es NO_ERROR.
Si se produce un error en la función, el valor devuelto es uno de los siguientes códigos de error.
| Código devuelto | Descripción |
|---|---|
|
No se encuentra el nombre de red especificado. Este error se devuelve en Windows Vista y versiones posteriores cuando no se recibió una respuesta ARP a la solicitud SendARP . Este error se produce si no se pudo alcanzar la dirección IPv4 de destino porque no está en la misma subred o el equipo de destino no funciona. |
|
El nombre de archivo es demasiado largo. Este error se devuelve en Windows Vista si el valor de ULONG al que apunta el parámetro PhyAddrLen es inferior a 6, el tamaño necesario para almacenar una dirección física completa. |
|
Uno de los dispositivos conectados al sistema no funciona. Este error se devuelve en Windows Server 2003 y versiones anteriores cuando no se recibió una respuesta de ARP a la solicitud SendARP . Este error puede producirse si no se pudo acceder a la dirección IPv4 de destino porque no está en la misma subred o el equipo de destino no funciona. |
|
Uno de los parámetros no es válido. Este error se devuelve en Windows Server 2003 y versiones anteriores si el parámetro pMacAddr o PhyAddrLen es un puntero NULL . |
|
El búfer de usuario proporcionado no es válido para la operación solicitada. Este error se devuelve en Windows Server 2003 y versiones anteriores si el valor de ULONG al que apunta el parámetro PhyAddrLen es cero. |
|
Elemento no encontrado. Este error se devuelve en Windows Vista si el parámetro SrcIp no especifica una dirección IPv4 de origen en una interfaz del equipo local o la dirección IP INADDR_ANY (una dirección IPv4 de 0.0.0.0).0). |
|
El sistema operativo que se ejecuta en el equipo local no admite la función SendARP . |
|
Si se produce un error en la función, use FormatMessage para obtener la cadena de mensaje para el error devuelto. |
Comentarios
La función SendARP se usa para solicitar la dirección de hardware físico (a veces denominada dirección MAC) que corresponde a una dirección IPv4 de destino especificada. Si la información solicitada no está en la tabla ARP del equipo local, la función SendARP hará que se envíe una solicitud ARP para obtener la dirección física. Si la función se ejecuta correctamente, la dirección física que corresponde a la dirección IPv4 de destino especificada se devuelve en la matriz a la que apunta el parámetro pMacAddr .
La dirección física de una dirección IPv4 solo está disponible si la dirección IPv4 de destino está en la subred local (la dirección IPv4 se puede acceder directamente sin pasar por ningún enrutador). Se producirá un error en la función SendARP si la dirección IPv4 de destino no está en la subred local.
Si la función SendARP se realiza correctamente en Windows Vista y versiones posteriores, la tabla ARP del equipo local se actualiza con los resultados. Si la función SendARP se ejecuta correctamente en Windows Server 2003 y versiones anteriores, la tabla ARP del equipo local no se ve afectada.
La función SendARP en Windows Vista y versiones posteriores devuelve valores devueltos de error diferentes que la función SendARP en Windows Server 2003 y versiones anteriores.
En Windows Vista y versiones posteriores, un puntero NULL pasado como parámetro pMacAddr o PhyAddrLen a la función SendARP provoca una infracción de acceso y la aplicación finaliza. Si se produce un error en Windows Vista y versiones posteriores y ERROR_BAD_NET_NAME, se devuelve ERROR_BUFFER_OVERFLOW o ERROR_NOT_FOUND , el valor de ULONG al que apunta el parámetro PhyAddrLen se establece en cero. Si el valor de ULONG al que apunta el parámetro PhyAddrLen es menor que 6 en Windows Vista y versiones posteriores, la función SendARP devuelve ERROR_BUFFER_OVERFLOW que indica que el búfer para recibir la dirección física es demasiado pequeño. Si el parámetro SrcIp especifica una dirección IPv4 que no es una interfaz en el equipo local, la función SendARP en Windows Vista y posterior devuelve ERROR_NOT_FOUND.
En Windows Server 2003 y versiones anteriores, un puntero NULL pasado como parámetro pMacAddr o PhyAddrLen a la función SendARP devuelve ERROR_INVALID_PARAMETER. Si se produce un error en Windows Server 2003 y versiones anteriores y se devuelven ERROR_GEN_FAILURE o ERROR_INVALID_USER_BUFFER , el valor de ULONG al que apunta el parámetro PhyAddrLen se establece en cero. Si el valor de ULONG al que apunta el parámetro PhyAddrLen es menor que 6 en Windows Server 2003 y versiones anteriores, la función SendARP no devuelve un error, sino que solo devuelve parte de la dirección de hardware de la matriz a la que apunta el parámetro pMacAddr . Por lo tanto, si el valor al que apunta el parámetro PhyAddrLen es 4, solo se devuelven los primeros 4 bytes de la dirección de hardware en la matriz a la que apunta el parámetro pMacAddr . Si el parámetro SrcIp especifica una dirección IPv4 que no es una interfaz en el equipo local, la función SendARP en Windows Server 2003 y versiones anteriores omite el parámetro SrcIp y usa una dirección IPv4 en el equipo local para la dirección IPv4 de origen.
La función GetIpNetTable recupera la tabla ARP en el equipo local que asigna direcciones IPv4 a direcciones físicas.
La función CreateIpNetEntry crea una entrada ARP en la tabla ARP del equipo local.
La función DeleteIpNetEntry elimina una entrada ARP de la tabla ARP en el equipo local.
La función SetIpNetEntry modifica una entrada ARP existente en la tabla ARP del equipo local.
La función FlushIpNetTable elimina todas las entradas de ARP de la interfaz especificada de la tabla ARP en el equipo local.
En Windows Vista y versiones posteriores, la función ResolveIpNetEntry2 puede usarse para reemplazar la función SendARP . Se envía una solicitud ARP si el miembro Address de la estructura de MIB_IPNET_ROW2 que se pasa a la función ResolveIpNetEntry2 es una dirección IPv4.
En Windows Vista, se puede usar un nuevo grupo de funciones para acceder, modificar y eliminar las entradas de la tabla ARP cuando el miembro Address de la estructura MIB_IPNET_ROW2 que se pasa a estas funciones es una dirección IPv4. Las nuevas funciones incluyen lo siguiente: GetIpNetTable2, CreateIpNetEntry2, DeleteIpNetEntry2, FlushIpNetTable2 y SetIpNetEntry2.
Para obtener información sobre el tipo de datos IPAddr , vea Tipos de datos de Windows. Para convertir una dirección IP entre la notación decimal con puntos y el formato IPAddr , use las funciones inet_addr y inet_ntoa .
Ejemplos
En el código siguiente se muestra cómo obtener la dirección de control de acceso de hardware o multimedia (MAC) asociada a una dirección IPv4 especificada.
#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 | Value |
|---|---|
| Cliente mínimo compatible | Windows 2000 Professional [solo aplicaciones de escritorio] |
| Servidor mínimo compatible | Windows 2000 Server [solo aplicaciones de escritorio] |
| Plataforma de destino | Windows |
| Encabezado | iphlpapi.h |
| Library | Iphlpapi.lib |
| Archivo DLL | Iphlpapi.dll |
Consulte también
Referencia de la función auxiliar de IP