Fungsi DeletePersistentTcpPortReservation (iphlpapi.h)

Artikel
08/24/2023

Fungsi DeletePersistentTcpPortReservation menghapus reservasi port TCP persisten untuk blok berturut-turut port TCP di komputer lokal.

Sintaks

IPHLPAPI_DLL_LINKAGE ULONG DeletePersistentTcpPortReservation(
  [in] USHORT StartPort,
  [in] USHORT NumberOfPorts
);

Parameter

[in] StartPort

Nomor port TCP awal dalam urutan byte jaringan.

[in] NumberOfPorts

Jumlah nomor port TCP yang akan dihapus.

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 nol diteruskan dalam parameter StartPort atau NumberOfPorts .
ERROR_NOT_FOUND	Elemen tidak ditemukan. Kesalahan ini dikembalikan jika blok port persisten yang ditentukan oleh parameter StartPort dan NumberOfPorts tidak dapat ditemukan.
Lainnya	Gunakan FormatMessage untuk mendapatkan string pesan untuk kesalahan yang dikembalikan.

Keterangan

Fungsi DeletePersistentTcpPortReservation ditentukan pada Windows Vista dan yang lebih baru.

Fungsi DeletePersistentTcpPortReservation digunakan untuk menghapus reservasi persisten untuk blok port TCP.

Fungsi DeletePersistentTcpPortReservation hanya dapat dipanggil oleh pengguna yang masuk sebagai anggota grup Administrator. Jika DeletePersistentTcpPortReservation 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 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.

Contoh

Contoh berikut menghapus reservasi port TCP persisten.

Contoh ini harus dijalankan oleh pengguna yang merupakan anggota grup Administrator. Cara paling sederhana untuk menjalankan contoh ini adalah dalam shell yang ditingkatkan sebagai Administrator bawaan (administrator RunAs).

#ifndef UNICODE
#define UNICODE
#endif

#ifndef WIN32_LEAN_AND_MEAN
#define WIN32_LEAN_AND_MEAN
#endif

#include <Windows.h.>
#include <winsock2.h>
#include <ws2ipdef.h> 
#include <iphlpapi.h>
#include <stdio.h>
#include <stdlib.h>

// Need to link with iphlpapi.lib
#pragma comment(lib, "iphlpapi.lib")

// Need to link with ws2_32.lib for htons
#pragma comment(lib, "ws2_32.lib")

int wmain(int argc, WCHAR **argv)  {

    // Declare and initialize variables
    
    int startPort = 0;         // host byte order
    int numPorts = 0;
    USHORT startPortns = 0;    // Network byte order
    
    unsigned long status = 0;

    // Validate the parameters
    if (argc != 3) {
        wprintf(L"usage: %s <Starting Port> <Number of Ports>\n", argv[0]);
        wprintf(L"Delete a persistent TCP port reservation\n");
        wprintf(L"Example usage:\n");
        wprintf(L"   %s 5000 20\n", argv[0]);
        wprintf(L"   where StartPort=5000 NumPorts=20");
        return 1;
    }

    startPort = _wtoi(argv[1]);
    if ( startPort < 0 || startPort> 65535) {
        wprintf(L"Starting point must be either 0 or between 1 and 65,535\n");
        return 1;
    }    
    startPortns = htons((u_short) startPort);

    numPorts = _wtoi(argv[2]);
    if (numPorts < 0) {
        wprintf(L"Number of ports must be a positive number\n");
        return 1;
    }    

    status = DeletePersistentTcpPortReservation((USHORT) startPortns, (USHORT) numPorts);
    if( status != NO_ERROR )
    {
        wprintf(L"DeletePersistentTcpPortReservation returned error: %ld\n", 
            status);
        return 1;
    }

    wprintf(L"DeletePersistentTcpPortReservation call succeeded\n");  

    return 0;
}

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