ホーム › NetworkManagement.IpHelper › AddIPAddress

AddIPAddress

関数

指定インターフェイスに新しいIPv4アドレスを追加する。

DLLIPHLPAPI.dll呼出規約winapi対応OSWindows 2000 以降

シグネチャ

// IPHLPAPI.dll
#include <windows.h>

DWORD AddIPAddress(
    DWORD Address,
    DWORD IpMask,
    DWORD IfIndex,
    DWORD* NTEContext,
    DWORD* NTEInstance
);

パラメーター

名前	型	方向	説明
Address	DWORD	in	アダプターに追加する IPv4 アドレス。IPAddr 構造体の形式で指定します。
IpMask	DWORD	in	Address パラメーターで指定した IPv4 アドレスのサブネットマスク。IPMask パラメーターは IPAddr 構造体と同じ形式を使用します。
IfIndex	DWORD	in	IPv4 アドレスを追加する対象アダプターのインデックス。
NTEContext	DWORD*	out	ULONG 変数へのポインター。正常に復帰した場合、このパラメーターは追加された IPv4 アドレスの Net Table Entry (NTE) コンテキストを指します。呼び出し元は後で、このコンテキストを DeleteIPAddress 関数の呼び出しに使用できます。
NTEInstance	DWORD*	out	ULONG 変数へのポインター。正常に復帰した場合、このパラメーターは追加された IPv4 アドレスの NTE インスタンスを指します。

戻り値の型: DWORD

公式ドキュメント

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

戻り値

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

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

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

解説(Remarks)

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

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

詳細については、Windows Sockets のドキュメント内の 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 アドレスは IP_ADAPTER_UNICAST_ADDRESS 構造体の IP_DAD_STATE メンバーが IpDadStateDuplicate に設定された状態で追加されます。

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

IPAddr および IPMask データ型については、 Windows Data Types を参照してください。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);
}

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

各言語での呼び出し定義

// IPHLPAPI.dll
#include <windows.h>

DWORD AddIPAddress(
    DWORD Address,
    DWORD IpMask,
    DWORD IfIndex,
    DWORD* NTEContext,
    DWORD* NTEInstance
);

[DllImport("IPHLPAPI.dll", ExactSpelling = true)]
static extern uint AddIPAddress(
    uint Address,   // DWORD
    uint IpMask,   // DWORD
    uint IfIndex,   // DWORD
    out uint NTEContext,   // DWORD* out
    out uint NTEInstance   // DWORD* out
);

<DllImport("IPHLPAPI.dll", ExactSpelling:=True)>
Public Shared Function AddIPAddress(
    Address As UInteger,   ' DWORD
    IpMask As UInteger,   ' DWORD
    IfIndex As UInteger,   ' DWORD
    <Out> ByRef NTEContext As UInteger,   ' DWORD* out
    <Out> ByRef NTEInstance As UInteger   ' DWORD* out
) As UInteger
End Function

' Address : DWORD
' IpMask : DWORD
' IfIndex : DWORD
' NTEContext : DWORD* out
' NTEInstance : DWORD* out
Declare PtrSafe Function AddIPAddress Lib "iphlpapi" ( _
    ByVal Address As Long, _
    ByVal IpMask As Long, _
    ByVal IfIndex As Long, _
    ByRef NTEContext As Long, _
    ByRef NTEInstance As Long) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

AddIPAddress = ctypes.windll.iphlpapi.AddIPAddress
AddIPAddress.restype = wintypes.DWORD
AddIPAddress.argtypes = [
    wintypes.DWORD,  # Address : DWORD
    wintypes.DWORD,  # IpMask : DWORD
    wintypes.DWORD,  # IfIndex : DWORD
    ctypes.POINTER(wintypes.DWORD),  # NTEContext : DWORD* out
    ctypes.POINTER(wintypes.DWORD),  # NTEInstance : DWORD* out
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('IPHLPAPI.dll')
AddIPAddress = Fiddle::Function.new(
  lib['AddIPAddress'],
  [
    -Fiddle::TYPE_INT,  # Address : DWORD
    -Fiddle::TYPE_INT,  # IpMask : DWORD
    -Fiddle::TYPE_INT,  # IfIndex : DWORD
    Fiddle::TYPE_VOIDP,  # NTEContext : DWORD* out
    Fiddle::TYPE_VOIDP,  # NTEInstance : DWORD* out
  ],
  -Fiddle::TYPE_INT)

#[link(name = "iphlpapi")]
extern "system" {
    fn AddIPAddress(
        Address: u32,  // DWORD
        IpMask: u32,  // DWORD
        IfIndex: u32,  // DWORD
        NTEContext: *mut u32,  // DWORD* out
        NTEInstance: *mut u32  // DWORD* out
    ) -> u32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("IPHLPAPI.dll")]
public static extern uint AddIPAddress(uint Address, uint IpMask, uint IfIndex, out uint NTEContext, out uint NTEInstance);
"@
$api = Add-Type -MemberDefinition $sig -Name 'IPHLPAPI_AddIPAddress' -Namespace Win32 -PassThru
# $api::AddIPAddress(Address, IpMask, IfIndex, NTEContext, NTEInstance)

#uselib "IPHLPAPI.dll"
#func global AddIPAddress "AddIPAddress" sptr, sptr, sptr, sptr, sptr
; AddIPAddress Address, IpMask, IfIndex, varptr(NTEContext), varptr(NTEInstance)   ; 戻り値は stat
; Address : DWORD -> "sptr"
; IpMask : DWORD -> "sptr"
; IfIndex : DWORD -> "sptr"
; NTEContext : DWORD* out -> "sptr"
; NTEInstance : DWORD* out -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "IPHLPAPI.dll"
#cfunc global AddIPAddress "AddIPAddress" int, int, int, var, var
; res = AddIPAddress(Address, IpMask, IfIndex, NTEContext, NTEInstance)
; Address : DWORD -> "int"
; IpMask : DWORD -> "int"
; IfIndex : DWORD -> "int"
; NTEContext : DWORD* out -> "var"
; NTEInstance : DWORD* out -> "var"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "IPHLPAPI.dll"
#cfunc global AddIPAddress "AddIPAddress" int, int, int, sptr, sptr
; res = AddIPAddress(Address, IpMask, IfIndex, varptr(NTEContext), varptr(NTEInstance))
; Address : DWORD -> "int"
; IpMask : DWORD -> "int"
; IfIndex : DWORD -> "int"
; NTEContext : DWORD* out -> "sptr"
; NTEInstance : DWORD* out -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。