Fungsi SetUnicastIpAddressEntry (netioapi.h)

Artikel
03/05/2024

Fungsi SetUnicastIpAddressEntry mengatur properti entri alamat IP unicast yang ada di komputer lokal.

Sintaks

IPHLPAPI_DLL_LINKAGE _NETIOAPI_SUCCESS_ NETIOAPI_API SetUnicastIpAddressEntry(
  [in] const MIB_UNICASTIPADDRESS_ROW *Row
);

Parameter

[in] Row

Penunjuk ke entri struktur MIB_UNICASTIPADDRESS_ROW untuk entri alamat IP unicast yang ada.

Nilai kembali

Jika fungsi berhasil, nilai yang dikembalikan NO_ERROR.

Jika fungsi gagal, nilai yang dikembalikan adalah salah satu kode kesalahan berikut.

Menampilkan kode	Deskripsi
ERROR_ACCESS_DENIED	Akses ditolak. Kesalahan ini dikembalikan dalam beberapa kondisi yang mencakup hal berikut: pengguna tidak memiliki hak istimewa administratif yang diperlukan di komputer lokal atau aplikasi tidak berjalan dalam shell yang ditingkatkan sebagai Administrator bawaan (administrator RunAs).
ERROR_INVALID_PARAMETER	Parameter yang tidak valid diteruskan ke fungsi. Kesalahan ini dikembalikan jika penunjuk NULL diteruskan dalam parameter Baris , anggota AlamatMIB_UNICASTIPADDRESS_ROW yang diarahkan oleh parameter Baris tidak diatur ke alamat IPv4 atau IPv6 unicast yang valid, atau anggota InterfaceLuid atau InterfaceIndexdari MIB_UNICASTIPADDRESS_ROW yang diarahkan oleh parameter Baris tidak ditentukan. Kesalahan ini juga dikembalikan untuk kesalahan lain dalam nilai yang ditetapkan untuk anggota dalam struktur MIB_UNICASTIPADDRESS_ROW . Kesalahan ini mencakup hal berikut: jika anggota ValidLifetime kurang dari anggota PreferredLifetime , jika anggota PrefixOrigin diatur ke IpPrefixOriginUnchanged dan SuffixOrigin tidak diatur ke IpSuffixOriginUnchanged, jika anggota PrefixOrigin tidak diatur ke IpPrefixOriginUnchanged dan SuffixOrigin diatur ke IpSuffixOriginUnchanged, jika PrefixOrigin anggota tidak diatur ke nilai dari enumerasi NL_PREFIX_ORIGIN , jika anggota SuffixOrigin tidak diatur ke nilai dari enumerasi NL_SUFFIX_ORIGIN , atau jika 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).
ERROR_NOT_FOUND	Antarmuka yang ditentukan tidak dapat ditemukan. Kesalahan ini dikembalikan jika antarmuka jaringan yang ditentukan oleh anggota InterfaceLuid atau InterfaceIndexdari MIB_UNICASTIPADDRESS_ROW yang ditunjukkan oleh parameter Baris tidak dapat ditemukan.
ERROR_NOT_SUPPORTED	Permintaan tidak didukung. Kesalahan ini dikembalikan jika tidak ada tumpukan IPv4 di komputer lokal dan alamat IPv4 ditentukan di anggota AlamatMIB_UNICASTIPADDRESS_ROW ditunjukkan oleh parameter Baris atau tidak ada tumpukan IPv6 di komputer lokal dan alamat IPv6 ditentukan dalam anggota Alamat .
Lainnya	Gunakan FormatMessage untuk mendapatkan string pesan untuk kesalahan yang dikembalikan.

Keterangan

Fungsi SetUnicastIpAddressEntry ditentukan pada Windows Vista dan yang lebih baru.

Fungsi GetUnicastIpAddressEntry biasanya digunakan untuk mengambil entri struktur MIB_UNICASTIPADDRESS_ROW yang ada untuk dimodifikasi. Aplikasi kemudian dapat mengubah anggota dalam entri MIB_UNICASTIPADDRESS_ROW yang ingin diubah, lalu memanggil fungsi SetUnicastIpAddressEntry .

Aplikasi dapat memanggil fungsi InitializeUnicastIpAddressEntry untuk menginisialisasi anggota entri struktur MIB_UNICASTIPADDRESS_ROW dengan nilai default sebelum membuat perubahan. Namun, aplikasi biasanya akan menyimpan anggota InterfaceLuid atau InterfaceIndex sebelum memanggil InitializeUnicastIpAddressEntry dan memulihkan salah satu anggota ini setelah panggilan.

Anggota Alamat dalam struktur MIB_UNICASTIPADDRESS_ROW yang ditunjukkan oleh parameter Baris harus diinisialisasi ke alamat dan keluarga IPv4 atau IPv6 unicast yang valid. Selain itu, setidaknya salah satu anggota berikut dalam struktur MIB_UNICASTIPADDRESS_ROW yang menunjuk ke parameter Baris harus diinisialisasi: InterfaceLuid atau InterfaceIndex.

Bidang digunakan dalam urutan yang tercantum di atas. Jadi, jika InterfaceLuid ditentukan, maka anggota ini digunakan untuk menentukan antarmuka. Jika tidak ada nilai yang ditetapkan untuk anggota InterfaceLuid (nilai anggota ini diatur ke nol), maka anggota InterfaceIndex selanjutnya digunakan untuk menentukan antarmuka.

Jika anggota OnLinkPrefixLength dari MIB_UNICASTIPADDRESS_ROW yang ditunjukkan oleh parameter Baris diatur ke 255, maka SetUnicastIpAddressEntry akan mengatur properti alamat IP unicast sehingga anggota OnLinkPrefixLength sama dengan panjang alamat IP. Jadi untuk alamat IPv4 unicast, OnLinkPrefixLength diatur ke 32 dan OnLinkPrefixLength diatur ke 128 untuk alamat IPv6 unicast. Jika ini akan mengakibatkan subnet mask yang salah untuk alamat IPv4 atau awalan tautan yang salah untuk alamat IPv6, maka aplikasi harus mengatur anggota ini ke nilai yang benar sebelum memanggil SetUnicastIpAddressEntry.

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

Fungsi SetUnicastIpAddressEntry hanya dapat dipanggil oleh pengguna yang masuk sebagai anggota grup Administrator. Jika SetUnicastIpAddressEntry dipanggil oleh pengguna yang bukan anggota grup Administrator, panggilan fungsi akan gagal dan ERROR_ACCESS_DENIED dikembalikan.

Fungsi SetUnicastIpAddressEntry juga dapat gagal karena kontrol akun pengguna (UAC) pada Windows Vista dan yang lebih baru. Jika aplikasi yang berisi fungsi ini dijalankan oleh pengguna yang masuk sebagai anggota grup Administrator selain Administrator bawaan, panggilan ini akan gagal kecuali aplikasi telah ditandai dalam file manifes dengan requestedExecutionLevel diatur ke requireAdministrator. Jika aplikasi tidak memiliki file manifes ini, pengguna yang masuk sebagai anggota grup Administrator selain Administrator bawaan kemudian harus menjalankan aplikasi dalam shell yang ditingkatkan sebagai Administrator bawaan (administrator RunAs) agar fungsi ini berhasil.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows Vista [hanya aplikasi desktop]
Server minimum yang didukung	Windows Server 2008 [hanya aplikasi desktop]
Target Platform	Windows
Header	netioapi.h (termasuk Iphlpapi.h)
Pustaka	Iphlpapi.lib
DLL	Iphlpapi.dll