CreateUnicastIpAddressEntry 関数

  • [アーティクル]

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

構文

NETIOAPI_API CreateUnicastIpAddressEntry(
  _In_ const MIB_UNICASTIPADDRESS_ROW *Row
);

パラメーター

  • Row [in]
    ユニキャスト IP アドレス エントリの MIB_UNICASTIPADDRESS_ROW 構造体エントリへのポインター。

戻り値

CreateUnicastIpAddressEntry は、関数が成功した場合に STATUS_SUCCESS を返します。

関数が失敗した場合、CreateUnicastIpAddressEntry は次のいずれかのエラー コードを返します:

リターン コード 説明
STATUS_INVALID_PARAMETER

その関数に渡された無効なパラメーター。 このエラーは、Row パラメーターに NULL ポインターが渡された場合、Row パラメーターが指す MIB_UNICASTIPADDRESS_ROW 構造体の Address メンバーに有効なユニキャスト IPv4 または IPv6 アドレスが設定されなかった場合、または、MIB_UNICASTIPADDRESS_ROW 構造体の InterfaceLuid メンバーと InterfaceIndex メンバーの両方が指定されていない場合に返されます。

このエラーは、MIB_UNICASTIPADDRESS_ROW構造体のメンバーに設定されている値の他のエラーに対しても返されます。 これらのエラーには、次の状況が含まれます。

  • ValidLifetime メンバーが PreferredLifetime メンバーより小さい。

  • PrefixOrigin メンバーが IpPrefixOriginUnchanged に設定され、SuffixOrigin が IpSuffixOriginUnchanged に設定されていません。

  • PrefixOrigin メンバーが IpPrefixOriginUnchanged に設定され、SuffixOrigin が IpSuffixOriginUnchanged に設定されていません。

  • PrefixOrigin メンバーは、NL_PREFIX_ORIGIN列挙型の値に設定されていません。

  • SuffixOrigin メンバーは、NL_SUFFIX_ORIGIN列挙体の値に設定されていません。

  • OnLinkPrefixLength メンバーは、IP アドレスの長さを超える値 (ユニキャスト IPv4 アドレスの場合は 32、ユニキャスト IPv6 アドレスの場合は 128) に設定されます。

NL_PREFIX_ORIGINおよびNL_SUFFIX_ORIGIN列挙体の使用可能な値については、MIB_UNICASTIPADDRESS_ROWを参照してください。
STATUS_NOT_FOUND

指定されたインターフェイスが見つかりませんでした。 このエラーは、Row パラメーターが指す MIB_UNICASTIPADDRESS_ROW 構造体の InterfaceLuid メンバーまたは InterfaceIndex メンバーで指定されるネットワーク インターフェイスを関数が見つけられない場合に返されます。
STATUS_NOT_SUPPORTED

要求はサポートされていません。 このエラーは、ローカル コンピューターに IPv4 スタックが存在せず、Row パラメーターが指す MIB_UNICASTIPADDRESS_ROW 構造体の Address メンバーに IPv4 アドレスが指定されていた場合、またはローカル コンピューターに IPv6 スタックが存在せず、Address メンバーに IPv6 アドレスが指定されていた場合に返されます。
ERROR_OBJECT_ALREADY_EXISTS

オブジェクトが既に存在します。 このエラーは、Row パラメーターが指すMIB_UNICASTIPADDRESS_ROW構造体の Address メンバーが、MIB_UNICASTIPADDRESS_ROW構造体の InterfaceLuid または InterfaceIndex メンバーによって指定されたインターフェイス上の既存のエニーキャスト IP アドレスの複製である場合に返されます。
その他

FormatMessage 関数を使用して、返されたエラーのメッセージ文字列を取得します。

解説

InitializeUnicastIpAddressEntry 関数を使用して、MIB_UNICASTIPADDRESS_ROW構造体エントリのメンバーを既定値で初期化します。 その後、ドライバーは、変更する MIB_UNICASTIPADDRESS_ROW エントリのメンバーを変更してから、CreateUnicastIpAddressEntry 関数を呼び出すことができます。

入力時に、ドライバーは、 Row パラメーターが指す MIB_UNICASTIPADDRESS_ROW構造体の次のメンバーを初期化する必要があります。

  • 住所
    有効なユニキャスト IPv4 アドレスまたはユニキャスト IPv6 アドレスとファミリを設定します。

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

Row パラメーターが指すMIB_UNICASTIPADDRESS_ROW構造体の OnLinkPrefixLength メンバーが 255 に設定されている場合、CreateUnicastIpAddressEntry はユニキャスト IP アドレス プロパティを設定して、OnLinkPrefixLength メンバーが IP アドレスの長さと同じになるようにします。 そのため、ユニキャスト IPv4 アドレスの場合、 OnLinkPrefixLength は 32 に設定され 、ユニキャスト IPv6 アドレスの場合は OnLinkPrefixLength が 128 に設定されます。 この設定により、IPv4 アドレスのサブネット マスクが正しくないか、IPv6 アドレスのリンク プレフィックスが正しくない場合、ドライバーは CreateUnicastIpAddressEntry を呼び出す前に OnLinkPrefixLength メンバーを正しい値に設定する必要があります。

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

CreateUnicastIpAddressEntry 関数が呼び出されると、Row パラメーターが指すMIB_UNICASTIPADDRESS_ROW構造体の DadState、ScopeId、CreationTimeStamp メンバーは無視されます。 これらのメンバーは、ネットワーク スタックによって設定されます。 ScopeId メンバーは、アドレスが追加されたインターフェイスによって自動的に決定されます。

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

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

ドライバーが CreateUnicastIpAddressEntry 関数を呼び出した後、次のメソッドを使用して、IP アドレスがまだ使用可能かどうかを判断できます。

  • ポーリングと 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 アドレスは使用できません。

  • IP ヘルパーの NotifyXxx 通知関数の 1 つを呼び出して、アドレスが変更されたときの非同期通知を設定します
    CreateUnicastIpAddressEntry 関数の呼び出しが正常に返されたら、NotifyUnicastIpAddressChange 関数を呼び出して、作成される IP アドレスの種類に応じて、IPv6 または IPv4 ユニキャスト IP アドレスへの変更を通知するドライバーを登録します。 作成中の IP アドレスに関する通知を受信したら、GetUnicastIpAddressEntry 関数を呼び出して DadState メンバーを取得します。 DadState メンバーの値が IpDadStatePreferred に設定されている場合、IP アドレスが使用できるようになりました。 DadState メンバーの値が IpDadStateTentative に設定されている場合、重複アドレスの検出はまだ完了していないため、ドライバーは今後の通知を待つ必要があります。 DadState メンバーの値が IpDadStatePreferred または IpDadStateTentative 以外の値で返された場合、重複アドレスの検出は失敗し、IP アドレスは使用できません。

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

要件

対象プラットフォーム

 ユニバーサル

バージョン

Windows Vista 以降のバージョンの Windows オペレーティング システムで使用できます。

ヘッダー

 Netioapi.h (Netioapi.h を含む)

ライブラリ

 Netio.lib

IRQL

< DISPATCH_LEVEL

関連項目

DeleteUnicastIpAddressEntry

GetUnicastIpAddressEntry

GetUnicastIpAddressTable

InitializeUnicastIpAddressEntry

MIB_UNICASTIPADDRESS_ROW

MIB_UNICASTIPADDRESS_TABLE

NL_PREFIX_ORIGIN

NL_SUFFIX_ORIGIN

NotifyIpInterfaceChange

NotifyRouteChange2

NotifyStableUnicastIpAddressTable

NotifyTeredoPortChange

NotifyUnicastIpAddressChange

SetUnicastIpAddressEntry