CreateUnicastIpAddressEntry 함수

CreateUnicastIpAddressEntry 함수는 로컬 컴퓨터에 새 유니캐스트 IP 주소 항목을 추가합니다.

구문

NETIOAPI_API CreateUnicastIpAddressEntry(
  _In_ const MIB_UNICASTIPADDRESS_ROW *Row
);

매개 변수

• 행 [in]
  유니캐스트 IP 주소 항목에 대한 MIB_UNICASTIPADDRESS_ROW 구조체 항목에 대한 포인터입니다.

반환 값

CreateUnicastIpAddressEntry 는 함수가 성공하면 STATUS_SUCCESS 반환합니다.

함수가 실패 하면 CreateUnicastIpAddressEntry 는 다음 오류 코드 중 하나를 반환합니다.

설명

InitializeUnicastIpAddressEntry 함수를 사용하여 MIB_UNICASTIPADDRESS_ROW 구조체 항목의 멤버를 기본값으로 초기화합니다. 그런 다음 드라이버는 수정하려는 MIB_UNICASTIPADDRESS_ROW 항목의 멤버를 변경한 다음 CreateUnicastIpAddressEntry 함수를 호출할 수 있습니다.

입력 시 드라이버는 Row 매개 변수가 가리키는 MIB_UNICASTIPADDRESS_ROW 구조체의 다음 멤버를 초기화해야 합니다.

• 주소
  유효한 유니캐스트 IPv4 또는 IPv6 주소 및 패밀리로 설정합니다.

• InterfaceLuid 또는 InterfaceIndex
  이러한 멤버는 이전에 나열된 순서대로 사용됩니다. 따라서 InterfaceLuid를 지정하면 이 멤버를 사용하여 유니캐스트 IP 주소를 추가할 인터페이스를 결정합니다. InterfaceLuid 멤버에 대해 값이 설정되지 않은 경우(이 멤버의 값이 0으로 설정된 경우) InterfaceIndex 멤버는 인터페이스를 확인하는 데 사용됩니다.

Row 매개 변수가 가리키는 MIB_UNICASTIPADDRESS_ROW 구조체의 OnLinkPrefixLength 멤버가 255로 설정된 경우 CreateUnicastIpAddressEntry는 OnLinkPrefixLength 멤버가 IP 주소의 길이와 동일하게 설정된 새 유니캐스트 IP 주소를 추가합니다. 따라서 유니캐스트 IPv4 주소의 경우 OnLinkPrefixLength 는 32로 설정되고 유니캐스트 IPv6 주소의 경우 OnLinkPrefixLength 는 128로 설정됩니다. 이 설정으로 인해 IPv4 주소에 대한 잘못된 서브넷 마스크 또는 IPv6 주소의 잘못된 링크 접두사가 발생하는 경우 드라이버는 CreateUnicastIpAddressEntry를 호출하기 전에 OnLinkPrefixLength 멤버를 올바른 값으로 설정해야 합니다.

OnLinkPrefixLength 멤버가 잘못 설정된 유니캐스트 IP 주소를 만든 경우 드라이버는 OnLinkPrefixLength 멤버가 올바른 값으로 설정된 SetUnicastIpAddressEntry를 호출하여 IP 주소를 변경할 수 있습니다.

Row 매개 변수가 가리키는 MIB_UNICASTIPADDRESS_ROW 구조체의 DadState, ScopeId 및 CreationTimeStamp 멤버는 CreateUnicastIpAddressEntry 함수가 호출될 때 무시됩니다. 이러한 멤버는 네트워크 스택에 의해 설정됩니다. ScopeId 멤버는 주소가 추가되는 인터페이스에 의해 자동으로 결정됩니다.

Row 매개 변수가 가리키는 MIB_UNICASTIPADDRESS_ROW 구조체의 Address 멤버에 전달된 유니캐스트 IP 주소가 인터페이스의 기존 유니캐스트 IP 주소와 중복되는 경우 CreateUnicastIpAddressEntry 함수가 실패합니다. 드라이버는 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 멤버의 값이 IpDadStateP 참조로 설정된 경우 이제 IP 주소를 사용할 수 있습니다. DadState 멤버의 값이 IpDadStateTentative로 설정된 경우 중복 주소 검색이 아직 완료되지 않았습니다. 이 경우 DadState 멤버가 여전히 IpDadStateTentative로 설정되어 있는 동안 0.5초마다 GetUnicastIpAddressEntry 함수를 다시 호출합니다. DadState 멤버의 값이 IpDadStateP 참조 또는 IpDadStateTentative 이외의 값으로 반환되는 경우 중복 주소 검색이 실패하고 IP 주소를 사용할 수 없습니다.

• IP 도우미 NotifyXxx 알림 함수 중 하나를 호출하여 주소가 변경되는 경우에 대한 비동기 알림을 설정합니다.
  CreateUnicastIpAddressEntry 함수에 대한 호출이 성공적으로 반환되면 NotifyUnicastIpAddressChange 함수를 호출하여 생성되는 IP 주소의 유형에 따라 IPv6 또는 IPv4 유니캐스트 IP 주소에 대한 변경 내용을 알리는 드라이버를 등록합니다. 생성되는 IP 주소에 대한 알림을 받으면 GetUnicastIpAddressEntry 함수를 호출하여 DadState 멤버를 검색합니다. DadState 멤버의 값이 IpDadStateP 참조로 설정된 경우 이제 IP 주소를 사용할 수 있습니다. DadState 멤버의 값이 IpDadStateTentative로 설정된 경우 중복 주소 검색이 아직 완료되지 않았으며 드라이버는 이후 알림을 기다려야 합니다. DadState 멤버의 값이 IpDadStateP 참조 또는 IpDadStateTentative 이외의 값으로 반환되는 경우 중복 주소 검색이 실패하고 IP 주소를 사용할 수 없습니다.

  중복 주소 검색 프로세스 중에 미디어의 연결이 끊어진 후 다시 연결되면 중복 주소 검색 프로세스가 다시 시작됩니다. 따라서 프로세스를 완료하는 시간이 IPv6의 일반적인 1초 값 또는 IPv4의 경우 3초 값 이상으로 증가할 수 있습니다.

요구 사항

참고 항목

DeleteUnicastIpAddressEntry

GetUnicastIpAddressEntry

GetUnicastIpAddressTable

InitializeUnicastIpAddressEntry

MIB_UNICASTIPADDRESS_ROW

MIB_UNICASTIPADDRESS_TABLE

NL_PREFIX_ORIGIN

NL_SUFFIX_ORIGIN

NotifyIpInterfaceChange

NotifyRouteChange2

NotifyStableUnicastIpAddressTable

NotifyTeredoPortChange

NotifyUnicastIpAddressChange

SetUnicastIpAddressEntry