Fungsi CreatePersistentUdpPortReservation (iphlpapi.h)

Artikel
03/14/2023

Fungsi CreatePersistentUdpPortReservation membuat reservasi port UDP persisten untuk blok berturut-turut port UDP di komputer lokal.

Sintaks

IPHLPAPI_DLL_LINKAGE ULONG CreatePersistentUdpPortReservation(
  [in]  USHORT   StartPort,
  [in]  USHORT   NumberOfPorts,
  [out] PULONG64 Token
);

Parameter

[in] StartPort

Nomor port UDP awal dalam urutan byte jaringan.

[in] NumberOfPorts

Jumlah nomor port UDP yang akan dicadangkan.

[out] Token

Pointer ke token reservasi port yang dikembalikan jika fungsi berhasil.

Nilai kembali

Jika fungsi berhasil, nilai yang dikembalikan adalah 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 nol diteruskan dalam parameter StartPort atau NumberOfPorts . Kesalahan ini juga dikembalikan jika parameter NumberOfPorts terlalu besar blok port tergantung pada parameter StartPort bahwa blok port yang dapat dialokasikan akan melebihi port maksimum yang dapat dialokasikan.
ERROR_SHARING_VIOLATION	Proses tidak bisa mengakses file karena sedang digunakan oleh proses lain. Kesalahan ini dikembalikan jika port UDP di blok port UDP yang ditentukan oleh parameter StartPort dan NumberOfPorts sudah digunakan. Kesalahan ini juga dikembalikan jika reservasi persisten untuk blok port UDP yang ditentukan oleh parameter StartPort dan NumberOfPorts cocok atau tumpang tindih dengan reservasi persisten untuk blok port UDP yang sudah dibuat.
Lainnya	Gunakan FormatMessage untuk mendapatkan string pesan untuk kesalahan yang dikembalikan.

Keterangan

Fungsi CreatePersistentUdpPortReservation didefinisikan pada Windows Vista dan yang lebih baru.

Fungsi CreatePersistentUdpPortReservation digunakan untuk menambahkan reservasi persisten untuk blok port UDP.

Aplikasi dan layanan yang perlu memesan port termasuk dalam dua kategori. Kategori pertama mencakup komponen yang membutuhkan port tertentu sebagai bagian dari operasi mereka. Komponen tersebut umumnya akan lebih memilih untuk menentukan port yang diperlukan pada waktu penginstalan (misalnya dalam manifes aplikasi). Kategori kedua mencakup komponen yang memerlukan port atau blok port yang tersedia saat runtime.

Kedua kategori ini sesuai dengan permintaan reservasi port tertentu dan kartubebas. Permintaan reservasi tertentu mungkin persisten atau runtime, sementara permintaan reservasi port wildcard hanya didukung saat runtime.

Fungsi CreatePersistentUdpPortReservation menyediakan kemampuan bagi aplikasi atau layanan untuk mencadangkan blok port UDP secara persisten. Reservasi TCP persisten dicatat di penyimpanan persisten untuk modul UDP di Windows.

Penelepon mendapatkan reservasi port persisten dengan menentukan berapa banyak port yang diperlukan dan apakah rentang tertentu diperlukan. Jika permintaan dapat dipenuhi, fungsi CreatePersistentUdpPortReservation mengembalikan token ULONG64 buram unik, yang kemudian mengidentifikasi reservasi. Reservasi port UDP persisten dapat dirilis dengan memanggil fungsi DeletePersistentUdpPortReservation . Perhatikan bahwa token untuk reservasi port UDP persisten tertentu dapat berubah setiap kali sistem dimulai ulang.

Windows tidak menerapkan keamanan antar komponen untuk reservasi persisten yang diperoleh menggunakan fungsi-fungsi ini. Ini berarti bahwa jika komponen diberikan kemampuan untuk mendapatkan reservasi port persisten, komponen tersebut secara otomatis mendapatkan kemampuan untuk mengonsumsi reservasi port persisten yang diberikan kepada komponen lain pada sistem. Keamanan tingkat proses diberlakukan untuk reservasi runtime, tetapi kontrol tersebut tidak dapat diperluas ke reservasi persisten yang dibuat menggunakan fungsi CreatePersistentTcpPortReservation atau CreatePersistentUdpPortReservation .

Setelah reservasi port UDP persisten diperoleh, aplikasi dapat meminta penetapan port dari reservasi port UDP dengan membuka soket UDP, lalu memanggil fungsi WSAIoctl yang menentukan SIO_ASSOCIATE_PORT_RESERVATION IOCTL dan meneruskan token reservasi sebelum mengeluarkan panggilan ke fungsi ikat pada soket.

IOCTL SIO_ACQUIRE_PORT_RESERVATION dapat digunakan untuk meminta reservasi runtime untuk blok port TCP atau UDP. Untuk reservasi port runtime, kumpulan port mengharuskan reservasi dikonsumsi dari proses yang soket reservasinya diberikan. Reservasi port runtime hanya berlangsung selama masa pakai soket tempat IOCTL SIO_ACQUIRE_PORT_RESERVATION dipanggil. Sebaliknya, reservasi port persisten yang dibuat menggunakan fungsi CreatePersistentUdpPortReservation dapat digunakan oleh proses apa pun dengan kemampuan untuk mendapatkan reservasi persisten.

Fungsi CreatePersistentUdpPortReservation hanya dapat dipanggil oleh pengguna yang masuk sebagai anggota grup Administrator. Jika CreatePersistentUdpPortReservation dipanggil oleh pengguna yang bukan anggota grup Administrator, panggilan fungsi akan gagal dan ERROR_ACCESS_DENIED dikembalikan. Fungsi ini 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 yang 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	iphlpapi.h
Pustaka	Iphlpapi.lib
DLL	Iphlpapi.dll