CreateUnicastIpAddressEntry

ローカルコンピューターに新しいユニキャスト IP アドレスエントリを追加します。

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

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

CreateUnicastIpAddressEntry 関数は Windows Vista 以降で定義されています。

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

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

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

InitializeUnicastIpAddressEntry 関数を使用して、 MIB_UNICASTIPADDRESS_ROW 構造体エントリのメンバーを既定値で初期化する必要があります。その後、アプリケーションは MIB_UNICASTIPADDRESS_ROW エントリ内で変更したいメンバーを変更し、CreateUnicastIpAddressEntry 関数を呼び出すことができます。

Row パラメーターが指す MIB_UNICASTIPADDRESS_ROW 構造体の Address メンバーは、有効なユニキャスト IPv4 または IPv6 アドレスに初期化されている必要があります。Address メンバー内の SOCKADDR_INET 構造体の si_family メンバーは AF_INET または AF_INET6 のいずれかに初期化されている必要があり、SOCKADDR_INET 構造体の関連する Ipv4 または Ipv6 メンバーは有効なユニキャスト IP アドレスに設定されている必要があります。さらに、Row パラメーターが指す MIB_UNICASTIPADDRESS_ROW 構造体内の次のメンバーのうち少なくとも 1 つがインターフェイスに初期化されている必要があります。すなわち、InterfaceLuid または InterfaceIndex です。

これらのフィールドは上記の順序で使用されます。したがって、InterfaceLuid が指定されている場合、このメンバーがユニキャスト IP アドレスを追加するインターフェイスを決定するために使用されます。InterfaceLuid メンバーに値が設定されていない場合（このメンバーの値がゼロに設定されている場合）、次に InterfaceIndex メンバーがインターフェイスを決定するために使用されます。

Row パラメーターが指す MIB_UNICASTIPADDRESS_ROW の OnLinkPrefixLength メンバーが 255 に設定されている場合、CreateUnicastIpAddressEntry は OnLinkPrefixLength メンバーを IP アドレスの長さに等しい値に設定して新しいユニキャスト IP アドレスを追加します。したがって、ユニキャスト IPv4 アドレスの場合は OnLinkPrefixLength が 32 に設定され、ユニキャスト IPv6 アドレスの場合は OnLinkPrefixLength が 128 に設定されます。これが IPv4 アドレスの不正なサブネットマスク、または IPv6 アドレスの不正なリンクプレフィックスをもたらす場合、アプリケーションは CreateUnicastIpAddressEntry を呼び出す前にこのメンバーを正しい値に設定する必要があります。

OnLinkPrefixLength メンバーが正しく設定されていない状態でユニキャスト IP アドレスが作成された場合、OnLinkPrefixLength メンバーを正しい値に設定して SetUnicastIpAddressEntry を呼び出すことで IP アドレスを変更できます。

Row が指す MIB_UNICASTIPADDRESS_ROW 構造体の DadState、ScopeId、および CreationTimeStamp メンバーは、CreateUnicastIpAddressEntry 関数が呼び出されたときには無視されます。これらのメンバーはネットワークスタックによって設定されます。ScopeId メンバーは、アドレスが追加されるインターフェイスによって自動的に決定されます。Windows 10 以降では、CreateUnicastIpAddressEntry を呼び出す際に MIB_UNICASTIPADDRESS_ROW 構造体で DadState が IpDadStatePreferred に設定されている場合、スタックはアドレスの初期 DAD 状態を「tentative」ではなく「preferred」に設定し、そのアドレスに対して楽観的 DAD を実行します。

Row パラメーターが指す MIB_UNICASTIPADDRESS_ROW の Address メンバーに渡されたユニキャスト IP アドレスが、インターフェイス上の既存のユニキャスト IP アドレスと重複している場合、CreateUnicastIpAddressEntry 関数は失敗します。ループバック IP アドレスは、CreateUnicastIpAddressEntry 関数を使用してループバックインターフェイスにのみ追加できる点に注意してください。

Row パラメーターが指す MIB_UNICASTIPADDRESS_ROW の Address メンバーに渡されたユニキャスト IP アドレスは、すぐには使用できません。この IP アドレスは、重複アドレス検出プロセスが正常に完了した後に使用可能になります。重複アドレス検出プロセスの完了には、IP パケットを送信して応答の可能性を待つ必要があるため、数秒かかることがあります。IPv6 の場合、重複アドレス検出プロセスは通常約 1 秒かかります。IPv4 の場合、重複アドレス検出プロセスは通常約 3 秒かかります。

CreateUnicastIpAddressEntry 関数の呼び出し後に IP アドレスがいつ使用可能になるかを知る必要があるアプリケーションには、使用できる 2 つの方法があります。1 つ目の方法は、ポーリングと GetUnicastIpAddressEntry 関数を使用します。2 つ目の方法は、通知関数の 1 つである NotifyAddrChange、NotifyIpInterfaceChange、または NotifyUnicastIpAddressChange を呼び出して、アドレスが変更されたときの非同期通知を設定します。

次の方法は、GetUnicastIpAddressEntry とポーリングの使用方法を説明します。CreateUnicastIpAddressEntry 関数の呼び出しが正常に返された後、重複アドレス検出プロセスが正常に完了する時間を確保するため、1 ～ 3 秒間（IPv6 アドレスを作成するか IPv4 アドレスを作成するかによる）待機します。次に GetUnicastIpAddressEntry 関数を呼び出して、更新された MIB_UNICASTIPADDRESS_ROW 構造体を取得し、DadState メンバーの値を調べます。DadState メンバーの値が IpDadStatePreferred に設定されている場合、IP アドレスは使用可能になっています。DadState メンバーの値が IpDadStateTentative に設定されている場合、重複アドレス検出はまだ完了していません。この場合、DadState メンバーが IpDadStateTentative に設定されたままの間、0.5 秒ごとに GetUnicastIpAddressEntry 関数を再度呼び出します。DadState メンバーの値が IpDadStatePreferred または IpDadStateTentative 以外の値で返された場合、重複アドレス検出は失敗しており、IP アドレスは使用できません。

次の方法は、適切な通知関数の使用方法を説明します。CreateUnicastIpAddressEntry 関数の呼び出しが正常に返された後、作成する IP アドレスの種類に応じて、NotifyUnicastIpAddressChange 関数を呼び出して、IPv6 または IPv4 ユニキャスト IP アドレスのいずれかの変更通知を受け取るように登録します。作成中の IP アドレスに関する通知を受け取ったら、GetUnicastIpAddressEntry 関数を呼び出して DadState メンバーを取得します。DadState メンバーの値が IpDadStatePreferred に設定されている場合、IP アドレスは使用可能になっています。DadState メンバーの値が IpDadStateTentative に設定されている場合、重複アドレス検出はまだ完了しておらず、アプリケーションは今後の通知を待つ必要があります。DadState メンバーの値が IpDadStatePreferred または IpDadStateTentative 以外の値で返された場合、重複アドレス検出は失敗しており、IP アドレスは使用できません。

重複アドレス検出プロセス中にメディアが切断された後に再接続された場合、重複アドレス検出プロセスは再開されます。そのため、プロセスの完了時間が IPv6 の通常の 1 秒、または IPv4 の通常の 3 秒を超えて増加する可能性があります。

CreateUnicastIpAddressEntry 関数は、Administrators グループのメンバーとしてログオンしたユーザーのみが呼び出すことができます。CreateUnicastIpAddressEntry が Administrators グループのメンバーでないユーザーによって呼び出された場合、関数呼び出しは失敗し、ERROR_ACCESS_DENIED が返されます。この関数は、Windows Vista 以降のユーザーアカウント制御（UAC）が原因で失敗することもあります。この関数を含むアプリケーションが、組み込みの Administrator 以外の Administrators グループのメンバーとしてログオンしたユーザーによって実行された場合、アプリケーションがマニフェストファイルで requestedExecutionLevel を requireAdministrator に設定してマークされていない限り、この呼び出しは失敗します。アプリケーションにこのマニフェストファイルがない場合、組み込みの Administrator 以外の Administrators グループのメンバーとしてログオンしたユーザーは、この関数が成功するためには、組み込みの Administrator（管理者として実行）として昇格したシェルでアプリケーションを実行する必要があります。

例

次の例は、CreateUnicastIpAddressEntry 関数を使用してローカルコンピューターに新しいユニキャスト IP アドレスエントリを追加する方法を示しています。

#ifndef WIN32_LEAN_AND_MEAN
#define WIN32_LEAN_AND_MEAN
#endif

#include <windows.h>
#include <winsock2.h>
#include <ws2ipdef.h> 
#include <iphlpapi.h>
#include <stdio.h>
#include <stdlib.h>

// Need to link with Iphlpapi.lib and Ws2_32.lib
#pragma comment(lib, "iphlpapi.lib")
#pragma comment(lib, "ws2_32.lib")

HANDLE gCallbackComplete;
HANDLE gNotifyEvent;

void CALLBACK CallCompleted (VOID *callerContext, 
    PMIB_UNICASTIPADDRESS_ROW row, 
    MIB_NOTIFICATION_TYPE notificationType);

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

    // Declare and initialize variables
    
    unsigned long ipAddress = INADDR_NONE;
    unsigned long ipMask = INADDR_NONE;

    DWORD dwRetVal = 0;

    DWORD dwSize = 0;
    unsigned long status = 0;

    DWORD lastError = 0;
    SOCKADDR_IN localAddress;

    NET_LUID interfaceLuid;
    PMIB_IPINTERFACE_TABLE pipTable = NULL; 
    MIB_UNICASTIPADDRESS_ROW ipRow;

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

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

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


    status = GetIpInterfaceTable( AF_INET, &pipTable );
    if( status != NO_ERROR )
    {
        printf("GetIpInterfaceTable returned error: %ld\n", 
            status);
        exit(1);
    }

    // Use loopback interface
    interfaceLuid = pipTable->Table[0].InterfaceLuid;

    localAddress.sin_family            = AF_INET;
    localAddress.sin_addr.S_un.S_addr  = ipAddress;
    
    FreeMibTable(pipTable);
    pipTable = NULL;    

    // Initialize the row
    InitializeUnicastIpAddressEntry( &ipRow );

    ipRow.InterfaceLuid = interfaceLuid;
    ipRow.Address.Ipv4 = localAddress;

    // Create a Handle to be notified of IP address changes
    gCallbackComplete = CreateEvent(NULL, FALSE, FALSE, NULL);
    if (gCallbackComplete == NULL) {
        printf("CreateEvent failed with error: %d\n", GetLastError() );
        exit(1);
    }    
    
    // Use NotifyUnicastIpAddressChange to determine when the address is ready
    NotifyUnicastIpAddressChange(AF_INET, &CallCompleted, NULL, FALSE, &gNotifyEvent);

    status = CreateUnicastIpAddressEntry(&ipRow);
    if(status != NO_ERROR)
    {
        CancelMibChangeNotify2(gNotifyEvent);
        switch(status)
        {
            case ERROR_INVALID_PARAMETER:
                printf("Error: CreateUnicastIpAddressEntry returned ERROR_INVALID_PARAMETER\n");
                break;
            case ERROR_NOT_FOUND:
                printf("Error: CreateUnicastIpAddressEntry returned ERROR_NOT_FOUND\n");
                break;
            case ERROR_NOT_SUPPORTED:
                printf("Error: CreateUnicastIpAddressEntry returned ERROR_NOT_SUPPORTED\n");
                break;
            case ERROR_OBJECT_ALREADY_EXISTS:
                printf("Error: CreateUnicastIpAddressEntry returned ERROR_OBJECT_ALREADY_EXISTS\n");
                break;
            default:
                //NOTE: Is this case needed? If not, we can remove the ErrorExit() function
                printf("CreateUnicastIpAddressEntry returned error: %d\n", status);
                break;
        }
        exit (status);
        
    }
    else
        printf("CreateUnicastIpAddressEntry succeeded\n");
        
    // Set timeout to 6 seconds
    status = WaitForSingleObject(gCallbackComplete, 6000);
    if(status != WAIT_OBJECT_0)
    {
        CancelMibChangeNotify2(gNotifyEvent);
        CancelMibChangeNotify2(gCallbackComplete);
        switch(status)
        {
            case WAIT_ABANDONED:
                printf("Wait on event was abandoned\n");
                break;
            case WAIT_TIMEOUT:
                printf("Wait on event timed out\n");
                break;
            default:
                printf("Wait on event exited with status %d\n", status);
                break;
        }
        return status;
    }
    printf("Task completed successfully\n");
    CancelMibChangeNotify2(gNotifyEvent);
    CancelMibChangeNotify2(gCallbackComplete);

    exit (0);
}


void CALLBACK CallCompleted(PVOID callerContext, PMIB_UNICASTIPADDRESS_ROW row, MIB_NOTIFICATION_TYPE notificationType)
{

    ADDRESS_FAMILY addressFamily; 
    SOCKADDR_IN sockv4addr;
    struct in_addr ipv4addr;
    
    // Ensure that this is the correct notification before setting gCallbackComplete
    // NOTE: Is there a stronger way to do this?
    if(notificationType == MibAddInstance) {
        printf("NotifyUnicastIpAddressChange received an Add instance\n");
        addressFamily = (ADDRESS_FAMILY) row->Address.si_family;
        switch (addressFamily) {
            case AF_INET:
                printf("\tAddressFamily: AF_INET\n");
                break;
            case AF_INET6:
                printf("\tAddressFamily: AF_INET6\n");
                break;
            default:    
                printf("\tAddressFamily: %d\n", addressFamily);
                break;
       }
       if (addressFamily == AF_INET) {
            sockv4addr = row->Address.Ipv4;
            ipv4addr = sockv4addr.sin_addr;
            printf("IPv4 address:  %s\n", inet_ntoa(ipv4addr) );
       }     
       if (callerContext != NULL)
           printf("Received a CallerContext value\n");
           
       SetEvent(gCallbackComplete);
    }    
    return;
}