AddIPAddress 関数 (iphlpapi.h)

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

AddIPAddress 関数は、指定した IPv4 アドレスを指定したアダプターに追加します。

構文

IPHLPAPI_DLL_LINKAGE DWORD AddIPAddress(
  [in]  IPAddr Address,
  [in]  IPMask IpMask,
  [in]  DWORD  IfIndex,
  [out] PULONG NTEContext,
  [out] PULONG NTEInstance
);

パラメーター

[in] Address

IPAddr 構造体の形式でアダプターに追加する IPv4 アドレス。

[in] IpMask

Address パラメーターで指定された IPv4 アドレスのサブネットマスク。 IPMask パラメーターは、IPAddr 構造体と同じ形式を使用します。

[in] IfIndex

IPv4 アドレスを追加するアダプターのインデックス。

[out] NTEContext

ULONG 変数へのポインター。正常に戻った場合、このパラメーターは、追加された IPv4 アドレスの Net Table Entry (NTE) コンテキストを指します。呼び出し元は、後で DeleteIPAddress 関数の呼び出しでこのコンテキストを使用できます。

[out] NTEInstance

ULONG 変数へのポインター。正常に戻った場合、このパラメーターは、追加された IPv4 アドレスの NTE インスタンスを指します。

戻り値

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

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

リターンコード	説明
ERROR_DEV_NOT_EXIST	IfIndex パラメーターで指定されたアダプターが存在しません。
ERROR_DUP_DOMAINNAME	Address パラメーターで指定されている追加する IPv4 アドレスは既に存在します。
ERROR_GEN_FAILURE	一般的なエラー。このエラーは、通常はブロードキャストアドレスと見なされる IPv4 アドレスなど、 Address パラメーターで指定された一部の値に対して返されます。
ERROR_INVALID_HANDLE	関数呼び出しを行おうとしているユーザーは管理者ではありません。
ERROR_INVALID_PARAMETER	1 つ以上のパラメーターが無効です。このエラーは、 NTEContext パラメーターまたは NTEInstance パラメーターが NULL の場合に返されます。このエラーは、 Address パラメーターで指定された IP アドレスが IfIndex パラメーターで指定されたインターフェイスインデックス (非ループバックインターフェイスのループバックアドレスなど) と矛盾している場合にも返されます。
ERROR_NOT_SUPPORTED	関数呼び出しは、実行された Windows のバージョンではサポートされていません。
その他	FormatMessage を使用して、返されたエラーのメッセージ文字列を取得します。

解説

AddIPAddress 関数は、ローカルコンピューターに新しい IPv4 アドレスエントリを追加するために使用されます。 AddIPAddress 関数によって追加された IPv4 アドレスは永続的ではありません。 IPv4 アドレスは、アダプターオブジェクトが存在する限り存在します。ネットワークインターフェイスカード (NIC) を手動でリセットする場合と同様に、コンピューターを再起動すると IPv4 アドレスが破棄されます。また、特定の PnP イベントによってアドレスが破棄される場合があります。

永続化する IPv4 アドレスを作成するには、Windows Management Instrumentation (WMI) コントロールの Win32_NetworkAdapterConfiguration クラスの EnableStatic メソッドを使用できます。 netsh コマンドを使用して、永続的な IPv4 アドレスを作成することもできます。

詳細については、Windows ソケットのドキュメントの Netsh.exe に関するドキュメントを参照してください。

Windows Server 2003、Windows XP、および Windows 2000 では、 Address パラメーターの IPv4 アドレスがネットワーク上に既に存在する場合、 AddIPAddress 関数は NO_ERROR を返し、追加される IPv4 アドレスは 0.0.0.0 です。

Windows Vista 以降では、Address パラメーターで渡された IPv4 アドレスが既にネットワーク上に存在する場合、AddIPAddress 関数はNO_ERRORを返し、重複する IPv4 アドレスは、ipDadStateDuplicate に設定されたIP_ADAPTER_UNICAST_ADDRESS構造体のIP_DAD_STATE メンバーと共に追加されます。

AddIPAddress 関数を使用して追加された IPv4 アドレスは、後で DeleteIPAddress 関数を呼び出して、AddIPAddress 関数によって返される NTEContext パラメーターを渡すことで削除できます。

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

Windows Vista 以降では、 CreateUnicastIpAddressEntry 関数を使用して、ローカルコンピューターに新しいユニキャスト IPv4 または IPv6 アドレスエントリを追加できます。

例

次の例では、最初のアダプターのインターフェイスインデックスを決定するために IP アドレステーブルを取得し、コマンドラインで指定された IP アドレスを最初のアダプターに追加します。追加された IP アドレスが削除されます。

#pragma comment(lib, "iphlpapi.lib")
#pragma comment(lib, "ws2_32.lib")

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

#define MALLOC(x) HeapAlloc(GetProcessHeap(), 0, (x))
#define FREE(x) HeapFree(GetProcessHeap(), 0, (x))

/* Note: could also use malloc() and free() */

int __cdecl main(int argc, char **argv)
{

    /* Variables used by GetIpAddrTable */
    PMIB_IPADDRTABLE pIPAddrTable;
    DWORD dwSize = 0;
    DWORD dwRetVal = 0;
    IN_ADDR IPAddr;
    DWORD ifIndex;

    /* IPv4 address and subnet mask we will be adding */
    UINT iaIPAddress;
    UINT iaIPMask;

    /* Variables where handles to the added IP are returned */
    ULONG NTEContext = 0;
    ULONG NTEInstance = 0;

    /* Variables used to return error message */
    LPVOID lpMsgBuf;

    // Validate the parameters
    if (argc != 3) {
        printf("usage: %s IPAddress SubnetMask\n", argv[0]);
        exit(1);
    }

    iaIPAddress = inet_addr(argv[1]);
    if (iaIPAddress == INADDR_NONE) {
        printf("usage: %s IPAddress SubnetMask\n", argv[0]);
        exit(1);
    }

    iaIPMask = inet_addr(argv[2]);
    if (iaIPMask == INADDR_NONE) {
        printf("usage: %s IPAddress SubnetMask\n", argv[0]);
        exit(1);
    }

    // Before calling AddIPAddress we use GetIpAddrTable to get
    // an adapter to which we can add the IP.
    pIPAddrTable = (MIB_IPADDRTABLE *) MALLOC(sizeof (MIB_IPADDRTABLE));
    if (pIPAddrTable == NULL) {
        printf("Error allocating memory needed to call GetIpAddrTable\n");
        exit (1);
    }
    else {
        dwSize = 0;
        // Make an initial call to GetIpAddrTable to get the
        // necessary size into the dwSize variable
        if (GetIpAddrTable(pIPAddrTable, &dwSize, 0) ==
            ERROR_INSUFFICIENT_BUFFER) {
            FREE(pIPAddrTable);
            pIPAddrTable = (MIB_IPADDRTABLE *) MALLOC(dwSize);

        }
        if (pIPAddrTable == NULL) {
            printf("Memory allocation failed for GetIpAddrTable\n");
            exit(1);
        }
    }
    // Make a second call to GetIpAddrTable to get the
    // actual data we want
    if ((dwRetVal = GetIpAddrTable(pIPAddrTable, &dwSize, 0)) == NO_ERROR) {
        // Save the interface index to use for adding an IP address
        ifIndex = pIPAddrTable->table[0].dwIndex;
        printf("\n\tInterface Index:\t%ld\n", ifIndex);
        IPAddr.S_un.S_addr = (u_long) pIPAddrTable->table[0].dwAddr;
        printf("\tIP Address:       \t%s (%lu%)\n", inet_ntoa(IPAddr),
               pIPAddrTable->table[0].dwAddr);
        IPAddr.S_un.S_addr = (u_long) pIPAddrTable->table[0].dwMask;
        printf("\tSubnet Mask:      \t%s (%lu%)\n", inet_ntoa(IPAddr),
               pIPAddrTable->table[0].dwMask);
        IPAddr.S_un.S_addr = (u_long) pIPAddrTable->table[0].dwBCastAddr;
        printf("\tBroadCast Address:\t%s (%lu%)\n", inet_ntoa(IPAddr),
               pIPAddrTable->table[0].dwBCastAddr);
        printf("\tReassembly size:  \t%lu\n\n",
               pIPAddrTable->table[0].dwReasmSize);
    } else {
        printf("Call to GetIpAddrTable failed with error %d.\n", dwRetVal);
        if (pIPAddrTable)
            FREE(pIPAddrTable);
        exit(1);
    }

    if (pIPAddrTable) {
        FREE(pIPAddrTable);
        pIPAddrTable = NULL;
    }

    if ((dwRetVal = AddIPAddress(iaIPAddress,
                                 iaIPMask,
                                 ifIndex,
                                 &NTEContext, &NTEInstance)) == NO_ERROR) {
        printf("\tIPv4 address %s was successfully added.\n", argv[1]);
    } else {
        printf("AddIPAddress failed with error: %d\n", dwRetVal);

        if (FormatMessage(FORMAT_MESSAGE_ALLOCATE_BUFFER | FORMAT_MESSAGE_FROM_SYSTEM | FORMAT_MESSAGE_IGNORE_INSERTS, NULL, dwRetVal, MAKELANGID(LANG_NEUTRAL, SUBLANG_DEFAULT),       // Default language
                          (LPTSTR) & lpMsgBuf, 0, NULL)) {
            printf("\tError: %s", lpMsgBuf);
            LocalFree(lpMsgBuf);
            exit(1);
        }
    }

// Delete the IP we just added using the NTEContext
// variable where the handle was returned       
    if ((dwRetVal = DeleteIPAddress(NTEContext)) == NO_ERROR) {
        printf("\tIPv4 address %s was successfully deleted.\n", argv[1]);
    } else {
        printf("\tDeleteIPAddress failed with error: %d\n", dwRetVal);
        exit(1);
    }

    exit(0);
}

要件


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

AddIPAddress 関数 (iphlpapi.h)

構文

パラメーター

戻り値

解説

例

要件

関連項目

フィードバック

フィードバック

その他のリソース