SendARP 関数 (iphlpapi.h)

[アーティクル]
08/24/2023

SendARP 関数は、アドレス解決プロトコル (ARP) 要求を送信して、指定された宛先 IPv4 アドレスに対応する物理アドレスを取得します。

構文

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

パラメーター

[in] DestIP

IPAddr 構造体の形式の宛先 IPv4 アドレス。 ARP 要求は、この IPv4 アドレスに対応する物理アドレスの取得を試みます。

[in] SrcIP

IPAddr 構造体の形式の送信者のソース IPv4 アドレス。このパラメーターは省略可能であり、ARP エントリの要求を送信するインターフェイスを選択するために使用されます。呼び出し元は、このパラメーターの INADDR_ANY IPv4 アドレスに対応するゼロを指定できます。

[out] pMacAddr

ULONG 変数の配列へのポインター。イーサネットまたはトークンリングの物理アドレスを保持するには、この配列に少なくとも 2 つの ULONG 要素が必要です。この配列の最初の 6 バイトは、 DestIP パラメーターで指定された IPv4 アドレスに対応する物理アドレスを受け取ります。

[in, out] PhyAddrLen

入力時に、アプリケーションが物理アドレスまたは MAC アドレスを受け取るために確保した最大バッファーサイズ (バイト単位) を指定する ULONG 値へのポインター。イーサネットまたはトークンリングの物理アドレスのバッファーサイズは、少なくとも 6 バイトにする必要があります

物理アドレスを受信するバッファーは、 pMacAddr パラメーターによって指されます。

正常に出力された場合、このパラメーターは pMacAddr が指すバッファーに書き込まれたバイト数を指定する値を指します。

戻り値

関数が成功した場合、戻り値はNO_ERROR。

関数が失敗した場合、戻り値は次のいずれかのエラーコードになります。

リターンコード	説明
ERROR_BAD_NET_NAME	ネットワーク名が見つかりません。このエラーは、 SendARP 要求に対する ARP 応答が受信されなかった場合に、Windows Vista 以降で返されます。このエラーは、宛先 IPv4 アドレスが同じサブネット上にないため、または宛先コンピューターが動作していないために到達できなかった場合に発生します。
ERROR_BUFFER_OVERFLOW	ファイル名が長すぎます。このエラーは、PhyAddrLen パラメーターが指す ULONG 値が 6 未満の場合、完全な物理アドレスを格納するために必要なサイズが Windows Vista で返されます。
ERROR_GEN_FAILURE	システムに接続されたデバイスが動作していません。このエラーは、 SendARP 要求に対する ARP 応答が受信されなかった場合に、Windows Server 2003 以前で返されます。このエラーは、宛先 IPv4 アドレスが同じサブネット上にないか、宛先コンピューターが動作していないために宛先 IPv4 アドレスに到達できなかった場合に発生する可能性があります。
ERROR_INVALID_PARAMETER	いずれかのパラメーターが無効です。このエラーは、pMacAddr パラメーターまたは PhyAddrLen パラメーターが NULL ポインターである場合、Windows Server 2003 以前で返されます。
ERROR_INVALID_USER_BUFFER	指定されたユーザーバッファーは、要求された操作に対して無効です。このエラーは、PhyAddrLen パラメーターが指す ULONG 値が 0 の場合、Windows Server 2003 以前で返されます。
ERROR_NOT_FOUND	Element not found. SrcIp パラメーターがローカルコンピューター上のインターフェイス上のソース IPv4 アドレスまたは INADDR_ANY IP アドレス (IPv4 アドレス 0.0.0.0) を指定していない場合、このエラーは Windows Vista で返されます。
ERROR_NOT_SUPPORTED	SendARP 関数は、ローカルコンピューターで実行されているオペレーティングシステムではサポートされていません。
その他	関数が失敗した場合は、 FormatMessage を使用して、返されたエラーのメッセージ文字列を取得します。

注釈

SendARP 関数は、指定された宛先 IPv4 アドレスに対応する物理ハードウェアアドレス (MAC アドレスとも呼ばれます) を要求するために使用されます。要求された情報がローカルコンピューターの ARP テーブルにない場合は、 SendARP 関数によって ARP 要求が送信され、物理アドレスが取得されます。関数が成功した場合、指定された宛先 IPv4 アドレスに対応する物理アドレスは、 pMacAddr パラメーターが指す配列で返されます。

IPv4 アドレスの物理アドレスは、宛先 IPv4 アドレスがローカルサブネット上にある場合にのみ使用できます (IPv4 アドレスはルーターを経由せずに直接到達できます)。送信先の IPv4 アドレスがローカルサブネットにない場合、 SendARP 関数は失敗します。

Windows Vista 以降で SendARP 関数が成功した場合、ローカルコンピューター上の ARP テーブルが結果で更新されます。 Windows Server 2003 以前で SendARP 関数が成功した場合、ローカルコンピューター上の ARP テーブルは影響を受けません。

Windows Vista 以降の SendARP 関数は、Windows Server 2003 以前の SendARP 関数とは異なるエラー戻り値を返します。

Windows Vista 以降では、pMacAddr または PhyAddrLen パラメーターとして SendARP 関数に NULL ポインターが渡されると、アクセス違反が発生し、アプリケーションが終了します。 Windows Vista 以降でエラーが発生し、ERROR_BAD_NET_NAME、ERROR_BUFFER_OVERFLOW、またはERROR_NOT_FOUNDが返された場合、PhyAddrLen パラメーターが指す ULONG 値は 0 に設定されます。 Windows Vista 以降で PhyAddrLen パラメーターが指す ULONG 値が 6 未満の場合、SendARP 関数は、物理アドレスを受信するバッファーが小さすぎるERROR_BUFFER_OVERFLOWを返します。 SrcIp パラメーターで、ローカルコンピューター上のインターフェイスではない IPv4 アドレスが指定されている場合、Windows Vista 以降の SendARP 関数はERROR_NOT_FOUNDを返します。

Windows Server 2003 以前では、pMacAddr または PhyAddrLen パラメーターとして SendARP 関数に渡された NULL ポインターは、ERROR_INVALID_PARAMETERを返します。 Windows Server 2003 以前でエラーが発生し、ERROR_GEN_FAILUREまたはERROR_INVALID_USER_BUFFERが返された場合、PhyAddrLen パラメーターが指す ULONG 値は 0 に設定されます。 Windows Server 2003 以前では、PhyAddrLen パラメーターが指す ULONG 値が 6 未満の場合、SendARP 関数はエラーを返しませんが、pMacAddr パラメーターが指す配列内のハードウェアアドレスの一部のみを返します。したがって、 PhyAddrLen パラメーターによって指される値が 4 の場合、ハードウェアアドレスの最初の 4 バイトのみが 、pMacAddr パラメーターによって指される配列で返されます。 SrcIp パラメーターで、ローカルコンピューター上のインターフェイスではない IPv4 アドレスが指定されている場合、Windows Server 2003 以前の SendARP 関数は SrcIp パラメーターを無視し、ソース IPv4 アドレスにローカルコンピューターの IPv4 アドレスを使用します。

GetIpNetTable 関数は、IPv4 アドレスを物理アドレスにマップするローカルコンピューター上の ARP テーブルを取得します。

CreateIpNetEntry 関数は、ローカルコンピューターの ARP テーブルに ARP エントリを作成します。

DeleteIpNetEntry 関数は、ローカルコンピューター上の ARP テーブルから ARP エントリを削除します。

SetIpNetEntry 関数は、ローカルコンピューター上の ARP テーブル内の既存の ARP エントリを変更します。

FlushIpNetTable 関数は、指定したインターフェイスのすべての ARP エントリをローカルコンピューターの ARP テーブルから削除します。

Windows Vista 以降では、 ResolveIpNetEntry2 関数を使用して SendARP 関数を置き換えることができます。 ResolveIpNetEntry2 関数に渡されるMIB_IPNET_ROW2構造体の Address メンバーが IPv4 アドレスである場合、ARP 要求が送信されます。

Windows Vista では、これらの関数に渡されるMIB_IPNET_ROW2構造体の Address メンバーが IPv4 アドレスである場合、ARP テーブルエントリにアクセス、変更、および削除するために新しい関数グループを使用できます。新しい関数には、 GetIpNetTable2、 CreateIpNetEntry2、 DeleteIpNetEntry2、 FlushIpNetTable2、および SetIpNetEntry2 が含まれます。

IPAddr データ型の詳細については、「Windows データ型」を参照してください。ドット 10 進表記と IPAddr 形式の間で IP アドレスを変換するには、 inet_addr 関数と inet_ntoa 関数を使用します。

例

次のコードは、指定された IPv4 アドレスに関連付けられているハードウェアまたはメディアアクセス制御 (MAC) アドレスを取得する方法を示しています。

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

要件

要件	値
サポートされている最小のクライアント	Windows 2000 Professional [デスクトップアプリのみ]
サポートされている最小のサーバー	Windows 2000 Server [デスクトップアプリのみ]
対象プラットフォーム	Windows
ヘッダー	iphlpapi.h
Library	Iphlpapi.lib
[DLL]	Iphlpapi.dll