Share via


SendARP (Compact 2013)

3/26/2014

This function sends an ARP request to obtain the physical address that corresponds to the specified destination IP address.

Syntax

DWORD SendARP(
  IPAddr DestIP, 
  IPAddr SrcIP, 
  PULONG pMacAddr,
  PULONG PhyAddrLen 
);

Parameters

  • DestIP
    [in] The destination IPv4 address, in the form of an IPAddr structure. The ARP request attempts to obtain the physical address that corresponds to this IPv4 address.
  • SrcIP
    [in] The source IPV4 address of the sender, in the form of an IPAddr structure. This parameter is optional and is used to select the interface to send the request on for the ARP entry. The caller may specify zero that corresponds to the INADDR_ANY IPv4 address for this parameter.
  • pMacAddr
    [out] A pointer to an array of ULONG variables. This array must have at least two ULONG elements to hold an Ethernet or token ring physical address. The first six bytes of this array receive the physical address that corresponds to the IPv4 address specified by the DestIP parameter.
  • PhyAddrLen
    [out] On input, a pointer to a ULONG value that specifies the maximum buffer size, in bytes, the application has set aside to receive the physical address or MAC address. The buffer to receive the physical address is pointed to by the pMacAddr parameter. On successful output, this parameter points to a value that specifies the number of bytes written to the buffer pointed to by the pMacAddr.

Return Value

Return code

Description

NO_ERROR

The function succeeds.

ERROR_BAD_NET_NAME

The network name cannot be found.

ERROR_BUFFER_OVERFLOW

The file name is too long.

ERROR_GEN_FAILURE

A device attached to the system is not functioning.

ERROR_INVALID_PARAMETER

One of the parameters is invalid.

ERROR_INVALID_USER_BUFFER

The supplied user buffer is not valid for the requested operation.

ERROR_NOT_FOUND

Element not found.

ERROR_NOT_SUPPORTED

The SendARP function is not supported by the operating system that is running on the local device.

Other

If the function fails, use FormatMessage to obtain the message string for the returned error.

Remarks

The SendARP function is used to request the physical hardware address (also known as the MAC address) that corresponds to a specified destination IPv4 address. If the information requested is not in the ARP table on the local device, the SendARP function will cause an ARP request to be sent to obtain the physical address. If the function is successful, the physical address that corresponds to the specified destination IPv4 address is returned in the array pointed to by the pMacAddr parameter.

The GetIpNetTable function retrieves the ARP table on the local device that maps IPv4 addresses to physical addresses. The CreateIpNetEntry function creates an ARP entry in the ARP table on the local device. The DeleteIpNetEntry function deletes an ARP entry from the ARP table on the local device. The SetIpNetEntry function modifies an existing ARP entry in the ARP table on the local device. The FlushIpNetTable function deletes all ARP entries for the specified interface from the ARP table on the local device.

Example Code

The following code demonstrates how to obtain the hardware or media access control (MAC) address associated with a specified IPv4 address.

Important

For readability, the following code example does not contain security checking or error handling. Do not use the following code in a production environment.

/* sendarp.c 
 * Link with wsock2.lib and iphlpapi.lib 
 */

#include <winsock2.h>
#include <iphlpapi.h>
#include <stdio.h>

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;
    int i;

    if (argc > 1) {
        for (i = 1; i < 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;
}

Requirements

Header

iphlpapi.h

Library

Iphlpapi.lib

See Also

Reference

IP Helper Functions
IPAddr
CreateIpNetEntry
CreateIpNetEntry2
CreateProxyArpEntry
DeleteIpNetEntry
DeleteIpNetEntry2
DeleteProxyArpEntry
FlushIpNetTable
FlushIpNetTable2
GetIpNetEntry2
GetIpNetTable2
ResolveIpNetEntry2
SetIpNetEntry
SetIpNetEntry2

Other Resources

IP Helper