Fungsi CreateUnicastIpAddressEntry

Artikel
03/08/2023

Fungsi CreateUnicastIpAddressEntry menambahkan entri alamat IP unicast baru di komputer lokal.

Sintaks

NETIOAPI_API CreateUnicastIpAddressEntry(
  _In_ const MIB_UNICASTIPADDRESS_ROW *Row
);

Parameter

Baris [in]
Penunjuk ke entri struktur MIB_UNICASTIPADDRESS_ROW untuk entri alamat IP unicast.

Nilai hasil

CreateUnicastIpAddressEntry mengembalikan STATUS_SUCCESS jika fungsi berhasil.

Jika fungsi gagal, CreateUnicastIpAddressEntry mengembalikan salah satu kode kesalahan berikut:

Mengembalikan kode	Deskripsi
STATUS_INVALID_PARAMETER	Parameter yang tidak valid diteruskan ke fungsi. Kesalahan ini dikembalikan jika penunjuk NULL diteruskan dalam parameter Baris, anggota Alamat dari struktur MIB_UNICASTIPADDRESS_ROW yang ditunjuk parameter Baris tidak diatur ke alamat IPv4 atau IPv6 unicast yang valid, atau anggota InterfaceLuid dan InterfaceIndex dari struktur MIB_UNICASTIPADDRESS_ROW tidak ditentukan. Kesalahan ini juga dikembalikan untuk kesalahan lain dalam nilai yang ditetapkan untuk anggota dalam struktur MIB_UNICASTIPADDRESS_ROW. Kesalahan ini mencakup situasi berikut: Anggota ValidLifetime kurang dari anggota PreferredLifetime . Anggota PrefixOrigin diatur ke IpPrefixOriginUnchanged dan SuffixOrigin tidak diatur ke IpSuffixOriginUnchanged. Anggota PrefixOrigin tidak diatur ke IpPrefixOriginUnchanged dan SuffixOrigin diatur ke IpSuffixOriginUnchanged. Anggota PrefixOrigin tidak diatur ke nilai dari enumerasi NL_PREFIX_ORIGIN. Anggota SuffixOrigin tidak diatur ke nilai dari enumerasi NL_SUFFIX_ORIGIN. Anggota OnLinkPrefixLength diatur ke nilai yang lebih besar dari panjang alamat IP, dalam bit (32 untuk alamat IPv4 unicast atau 128 untuk alamat IPv6 unicast). Untuk kemungkinan nilai enumerasi NL_PREFIX_ORIGIN dan NL_SUFFIX_ORIGIN, lihat MIB_UNICASTIPADDRESS_ROW.
STATUS_NOT_FOUND	Antarmuka yang ditentukan tidak dapat ditemukan. Kesalahan ini dikembalikan jika fungsi tidak dapat menemukan antarmuka jaringan yang ditentukan oleh anggota InterfaceLuid atau InterfaceIndex dari struktur MIB_UNICASTIPADDRESS_ROW yang ditunjuk parameter Baris .
STATUS_NOT_SUPPORTED	Permintaan tidak didukung. Kesalahan ini dikembalikan jika tidak ada tumpukan IPv4 yang terletak di komputer lokal dan alamat IPv4 ditentukan dalam anggota Alamat struktur MIB_UNICASTIPADDRESS_ROW yang ditunjuk parameter Baris , atau jika tidak ada tumpukan IPv6 yang terletak di komputer lokal dan alamat IPv6 ditentukan di anggota Alamat .
ERROR_OBJECT_ALREADY_EXISTS	Objek sudah ada. Kesalahan ini dikembalikan jika anggota Alamat dari struktur MIB_UNICASTIPADDRESS_ROW yang ditunjuk parameter Baris adalah duplikat alamat IP unicast yang ada pada antarmuka yang ditentukan oleh anggota InterfaceLuid atau InterfaceIndex dari MIB_UNICASTIPADDRESS_ROW.
Lainnya	Gunakan fungsi FormatMessage untuk mendapatkan string pesan untuk kesalahan yang dikembalikan.

Keterangan

Gunakan fungsi InitializeUnicastIpAddressEntry untuk menginisialisasi anggota entri struktur MIB_UNICASTIPADDRESS_ROW dengan nilai default. Driver kemudian dapat mengubah anggota dalam entri MIB_UNICASTIPADDRESS_ROW yang ingin diubah, lalu memanggil fungsi CreateUnicastIpAddressEntry .

Pada input, driver Anda harus menginisialisasi anggota struktur MIB_UNICASTIPADDRESS_ROW berikut yang ditunjuk parameter Baris .

Alamat
Atur ke alamat dan keluarga IPv4 atau IPv6 unicast yang valid.
InterfaceLuid atau InterfaceIndex
Anggota ini digunakan dalam urutan yang tercantum sebelumnya. Jadi jika InterfaceLuid ditentukan, anggota ini digunakan untuk menentukan antarmuka untuk menambahkan alamat IP unicast. Jika tidak ada nilai yang ditetapkan untuk anggota InterfaceLuid (nilai anggota ini diatur ke nol), anggota InterfaceIndex selanjutnya digunakan untuk menentukan antarmuka.

Jika anggota OnLinkPrefixLength dari struktur MIB_UNICASTIPADDRESS_ROW yang ditunjuk parameter Baris diatur ke 255, CreateUnicastIpAddressEntry menambahkan alamat IP unicast baru dengan anggota OnLinkPrefixLength yang diatur sama dengan panjang alamat IP. Jadi untuk alamat IPv4 unicast, OnLinkPrefixLength diatur ke 32 dan OnLinkPrefixLength diatur ke 128 untuk alamat IPv6 unicast. Jika pengaturan ini akan mengakibatkan subnet mask yang salah untuk alamat IPv4 atau awalan tautan yang salah untuk alamat IPv6, driver harus mengatur anggota OnLinkPrefixLength ke nilai yang benar sebelum memanggil CreateUnicastIpAddressEntry.

Jika alamat IP unicast dibuat dengan anggota OnLinkPrefixLength salah diatur, driver Anda dapat mengubah alamat IP dengan memanggil SetUnicastIpAddressEntry dengan anggota OnLinkPrefixLength diatur ke nilai yang benar.

Anggota DadState, ScopeId, dan CreationTimeStamp dari struktur MIB_UNICASTIPADDRESS_ROW yang diabaikan oleh parameter Baris saat fungsi CreateUnicastIpAddressEntry dipanggil. Anggota ini diatur oleh tumpukan jaringan. Anggota ScopeId secara otomatis ditentukan oleh antarmuka tempat alamat ditambahkan.

Fungsi CreateUnicastIpAddressEntry gagal jika alamat IP unicast yang diteruskan di anggota Alamat struktur MIB_UNICASTIPADDRESS_ROW yang ditunjuk parameter Baris adalah duplikat alamat IP unicast yang ada pada antarmuka. Perhatikan bahwa driver Anda dapat menambahkan alamat IP loopback ke antarmuka loopback hanya dengan menggunakan fungsi CreateUnicastIpAddressEntry .

Alamat IP unicast yang diteruskan di anggota Alamat struktur MIB_UNICASTIPADDRESS_ROW yang ditunjuk parameter Baris tidak dapat digunakan segera. Alamat IP dapat digunakan setelah proses deteksi alamat duplikat berhasil diselesaikan. Diperlukan waktu beberapa detik agar proses deteksi alamat duplikat selesai karena paket IP harus dikirim dan respons potensial harus ditunggu. Untuk IPv6, proses deteksi alamat duplikat biasanya memakan waktu sekitar 1 detik. Untuk IPv4, proses deteksi alamat duplikat biasanya memakan waktu sekitar 3 detik.

Setelah driver memanggil fungsi CreateUnicastIpAddressEntry , driver dapat menggunakan metode berikut untuk menentukan apakah alamat IP masih dapat digunakan:

Menggunakan polling dan fungsi GetUnicastIpAddressEntry
Setelah panggilan ke fungsi CreateUnicastIpAddressEntry berhasil dikembalikan, jeda selama 1 hingga 3 detik (tergantung pada apakah alamat IPv6 atau IPv4 sedang dibuat) untuk memungkinkan waktu untuk keberhasilan penyelesaian proses deteksi alamat duplikasi. Kemudian, panggil GetUnicastIpAddressEntry untuk mengambil struktur MIB_UNICASTIPADDRESS_ROW yang diperbarui dan memeriksa nilai anggota DadState . Jika nilai anggota DadState diatur ke IpDadStatePreferred, alamat IP sekarang dapat digunakan. Jika nilai anggota DadState diatur ke IpDadStateTentative, deteksi alamat duplikat belum selesai. Dalam hal ini, panggil fungsi GetUnicastIpAddressEntry lagi setiap 0,5 detik sementara anggota DadState masih diatur ke IpDadStateTentative. Jika nilai anggota DadState dikembalikan dengan beberapa nilai selain IpDadStatePreferred atau IpDadStateTentative, deteksi alamat duplikat telah gagal dan alamat IP tidak dapat digunakan.
Panggil salah satu fungsi pemberitahuan NotifyXxx Pembantu IP untuk menyiapkan pemberitahuan asinkron saat alamat berubah
Setelah panggilan ke fungsi CreateUnicastIpAddressEntry berhasil dikembalikan, panggil fungsi NotifyUnicastIpAddressChange untuk mendaftarkan driver untuk diberi tahu tentang perubahan pada alamat IP unicast IPv6 atau IPv4, tergantung pada jenis alamat IP yang sedang dibuat. Saat pemberitahuan diterima untuk alamat IP yang sedang dibuat, panggil fungsi GetUnicastIpAddressEntry untuk mengambil anggota DadState . Jika nilai anggota DadState diatur ke IpDadStatePreferred, alamat IP sekarang dapat digunakan. Jika nilai anggota DadState diatur ke IpDadStateTentative, deteksi alamat duplikat belum selesai dan driver harus menunggu pemberitahuan di masa mendatang. Jika nilai anggota DadState dikembalikan dengan beberapa nilai selain IpDadStatePreferred atau IpDadStateTentative, deteksi alamat duplikat telah gagal dan alamat IP tidak dapat digunakan.

Jika, selama proses deteksi alamat duplikat, media terputus dan kemudian disambungkan kembali, proses deteksi alamat duplikat dimulai ulang. Jadi waktu untuk menyelesaikan proses mungkin meningkat melebihi nilai 1 detik khas untuk nilai IPv6 atau 3 detik untuk IPv4.

Persyaratan

Platform target	Universal
Versi	Tersedia di Windows Vista dan versi sistem operasi Windows yang lebih baru.
Header	Netioapi.h (termasuk Netioapi.h)
Pustaka	Netio.lib
IRQL	< DISPATCH_LEVEL