Fungsi SendARP (iphlpapi.h)

Fungsi SendARP mengirimkan permintaan Protokol Resolusi Alamat (ARP) untuk mendapatkan alamat fisik yang sesuai dengan alamat IPv4 tujuan yang ditentukan.

Sintaks

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

Parameter

[in] DestIP

Alamat IPv4 tujuan, dalam bentuk struktur IPAddr . Permintaan ARP mencoba mendapatkan alamat fisik yang sesuai dengan alamat IPv4 ini.

[in] SrcIP

Alamat IPv4 sumber pengirim, dalam bentuk struktur IPAddr . Parameter ini bersifat opsional dan digunakan untuk memilih antarmuka untuk mengirim permintaan pada entri ARP. Pemanggil dapat menentukan nol yang sesuai dengan alamat IPv4 INADDR_ANY untuk parameter ini.

[out] pMacAddr

Penunjuk ke array variabel ULONG . Array ini harus memiliki setidaknya dua elemen ULONG untuk menahan alamat fisik cincin Ethernet atau token. Enam byte pertama dari array ini menerima alamat fisik yang sesuai dengan alamat IPv4 yang ditentukan oleh parameter DestIP .

[in, out] PhyAddrLen

Pada input, penunjuk ke nilai ULONG yang menentukan ukuran buffer maksimum, dalam byte, aplikasi telah menyisihkan untuk menerima alamat fisik atau alamat MAC. Ukuran buffer harus setidaknya 6 byte untuk alamat fisik cincin Ethernet atau token

Buffer untuk menerima alamat fisik ditunjukkan oleh parameter pMacAddr .

Pada output yang berhasil, parameter ini menunjuk ke nilai yang menentukan jumlah byte yang ditulis ke buffer yang ditunjukkan oleh pMacAddr.

Nilai kembali

Jika fungsi berhasil, nilai yang dikembalikan adalah NO_ERROR.

Jika fungsi gagal, nilai yang dikembalikan adalah salah satu kode kesalahan berikut.

Keterangan

Fungsi SendARP digunakan untuk meminta alamat perangkat keras fisik (terkadang disebut sebagai alamat MAC) yang sesuai dengan alamat IPv4 tujuan tertentu. Jika informasi yang diminta tidak ada dalam tabel ARP di komputer lokal, maka fungsi SendARP akan menyebabkan permintaan ARP dikirim untuk mendapatkan alamat fisik. Jika fungsi berhasil, alamat fisik yang sesuai dengan alamat IPv4 tujuan yang ditentukan dikembalikan dalam array yang ditunjukkan oleh parameter pMacAddr .

Alamat fisik alamat IPv4 hanya tersedia jika alamat IPv4 tujuan ada di subnet lokal (alamat IPv4 dapat dijangkau langsung tanpa melalui router apa pun). Fungsi SendARP akan gagal jika alamat IPv4 tujuan tidak ada di subnet lokal.

Jika fungsi SendARP berhasil pada Windows Vista dan yang lebih baru, tabel ARP pada komputer lokal diperbarui dengan hasilnya. Jika fungsi SendARP berhasil pada Windows Server 2003 dan yang lebih lama, tabel ARP pada komputer lokal tidak terpengaruh.

Fungsi SendARP pada Windows Vista dan kemudian mengembalikan nilai pengembalian kesalahan yang berbeda dari fungsi SendARP pada Windows Server 2003 dan yang lebih lama.

Pada Windows Vista dan yang lebih baru, pointer NULL diteruskan sebagai parameter pMacAddr atau PhyAddrLen ke fungsi SendARP menyebabkan pelanggaran akses dan aplikasi dihentikan. Jika terjadi kesalahan pada Windows Vista dan yang lebih baru dan ERROR_BAD_NET_NAME, ERROR_BUFFER_OVERFLOW, atau ERROR_NOT_FOUND dikembalikan, nilai ULONG yang ditunjukkan oleh parameter PhyAddrLen diatur ke nol. Jika nilai ULONG yang diarahkan oleh parameter PhyAddrLen kurang dari 6 pada Windows Vista dan yang lebih baru, fungsi SendARP mengembalikan ERROR_BUFFER_OVERFLOW menunjukkan buffer untuk menerima alamat fisik terlalu kecil. Jika parameter SrcIp menentukan alamat IPv4 yang bukan antarmuka di komputer lokal, fungsi SendARP pada Windows Vista dan kemudian mengembalikan ERROR_NOT_FOUND.

Pada Windows Server 2003 dan yang lebih lama, pointer NULL diteruskan sebagai parameter pMacAddr atau PhyAddrLen ke fungsi SendARP mengembalikan ERROR_INVALID_PARAMETER. Jika kesalahan terjadi pada Windows Server 2003 dan yang lebih lama dan ERROR_GEN_FAILURE atau ERROR_INVALID_USER_BUFFER dikembalikan, nilai ULONG yang ditujukkan oleh parameter PhyAddrLen diatur ke nol. Jika nilai ULONG yang ditunjukkan oleh parameter PhyAddrLen kurang dari 6 pada Windows Server 2003 dan yang lebih lama, fungsi SendARP tidak mengembalikan kesalahan tetapi hanya mengembalikan bagian dari alamat perangkat keras dalam array yang ditunjukkan oleh parameter pMacAddr . Jadi, jika nilai yang ditunjukkan oleh parameter PhyAddrLen adalah 4, maka hanya 4 byte pertama dari alamat perangkat keras yang dikembalikan dalam array yang ditunjukkan oleh parameter pMacAddr . Jika parameter SrcIp menentukan alamat IPv4 yang bukan antarmuka di komputer lokal, fungsi SendARP pada Windows Server 2003 dan sebelumnya mengabaikan parameter SrcIp dan menggunakan alamat IPv4 di komputer lokal untuk alamat IPv4 sumber.

Fungsi GetIpNetTable mengambil tabel ARP di komputer lokal yang memetakan alamat IPv4 ke alamat fisik.

Fungsi CreateIpNetEntry membuat entri ARP dalam tabel ARP di komputer lokal.

Fungsi DeleteIpNetEntry menghapus entri ARP dari tabel ARP di komputer lokal.

Fungsi SetIpNetEntry memodifikasi entri ARP yang ada dalam tabel ARP di komputer lokal.

Fungsi FlushIpNetTable menghapus semua entri ARP untuk antarmuka yang ditentukan dari tabel ARP di komputer lokal.

Pada Windows Vista dan yang lebih baru, fungsi ResolveIpNetEntry2 dapat digunakan untuk menggantikan fungsi SendARP . Permintaan ARP dikirim jika anggota Alamat struktur MIB_IPNET_ROW2 yang diteruskan ke fungsi ResolveIpNetEntry2 adalah alamat IPv4.

Di Windows Vista, grup fungsi baru dapat digunakan untuk mengakses, memodifikasi, dan menghapus entri tabel ARP ketika anggota Alamat struktur MIB_IPNET_ROW2 yang diteruskan ke fungsi ini adalah alamat IPv4. Fungsi baru mencakup yang berikut: GetIpNetTable2, CreateIpNetEntry2, DeleteIpNetEntry2, FlushIpNetTable2, dan SetIpNetEntry2.

Untuk informasi tentang jenis data IPAddr , lihat Jenis Data Windows. Untuk mengonversi alamat IP antara notasi desimal putus-putus dan format IPAddr , gunakan fungsi inet_addr dan inet_ntoa .

Contoh

Kode berikut menunjukkan cara mendapatkan alamat perangkat keras atau kontrol akses media (MAC) yang terkait dengan alamat IPv4 tertentu.

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

Persyaratan

Lihat juga

CreateIpNetEntry

CreateIpNetEntry2

CreateProxyArpEntry

DeleteIpNetEntry

DeleteIpNetEntry2

DeleteProxyArpEntry

FlushIpNetTable

FlushIpNetTable2

GetIpNetEntry2

GetIpNetTable2

Referensi Fungsi Pembantu IP

Halaman Mulai Pembantu IP

IPAddr

ResolveIpNetEntry2

SetIpNetEntry

SetIpNetEntry2