Funzione DeletePersistentTcpPortReservation (iphlpapi.h)

Articolo
08/24/2023

La funzione DeletePersistentTcpPortReservation elimina una prenotazione di porta TCP persistente per un blocco consecutivo di porte TCP nel computer locale.

Sintassi

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

Parametri

[in] StartPort

Numero di porta TCP iniziale nell'ordine dei byte di rete.

[in] NumberOfPorts

Numero di numeri di porta TCP da eliminare.

Valore restituito

Se la funzione ha esito positivo, il valore restituito viene NO_ERROR.

Se la funzione ha esito negativo, il valore restituito è uno dei codici di errore seguenti.

Codice restituito	Descrizione
ERROR_ACCESS_DENIED	Accesso negato. Questo errore viene restituito in diverse condizioni che includono quanto segue: l'utente non dispone dei privilegi amministrativi necessari nel computer locale o l'applicazione non è in esecuzione in una shell avanzata come amministratore predefinito (amministratore RunAs).
ERROR_INVALID_PARAMETER	Alla funzione è stato passato un parametro non valido. Questo errore viene restituito se zero viene passato nei parametri StartPort o NumberOfPorts .
ERROR_NOT_FOUND	Impossibile trovare l'elemento. Questo errore viene restituito se non è stato possibile trovare il blocco di porte persistente specificato dai parametri StartPort e NumberOfPorts .
Altri	Usare FormatMessage per ottenere la stringa del messaggio per l'errore restituito.

Commenti

La funzione DeletePersistentTcpPortReservation è definita in Windows Vista e versioni successive.

La funzione DeletePersistentTcpPortReservation viene usata per eliminare una prenotazione permanente per un blocco di porte TCP.

La funzione DeletePersistentTcpPortReservation può essere chiamata solo da un utente connesso come membro del gruppo Administrators. Se DeletePersistentTcpPortReservation viene chiamato da un utente che non è membro del gruppo Administrators, la chiamata di funzione avrà esito negativo e ERROR_ACCESS_DENIED viene restituito. Questa funzione può anche non riuscire a causa del controllo dell'account utente in Windows Vista e versioni successive. Se un'applicazione che contiene questa funzione viene eseguita da un utente connesso come membro del gruppo Administrators diverso dall'amministratore predefinito, questa chiamata avrà esito negativo a meno che l'applicazione non sia stata contrassegnata nel file manifesto con un set requestedExecutionLevel impostato su requireAdministrator. Se l'applicazione non dispone di questo file manifesto, un utente connesso come membro del gruppo Administrators diverso dall'amministratore predefinito deve quindi eseguire l'applicazione in una shell avanzata come amministratore predefinito (amministratore RunAs) affinché questa funzione abbia esito positivo.

Esempio

Nell'esempio seguente viene eliminata una prenotazione di porta TCP persistente.

Questo esempio deve essere eseguito da un utente membro del gruppo Administrators. Il modo più semplice per eseguire questo esempio è in una shell avanzata come amministratore predefinito (amministratore 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;
}

Requisiti

Requisito	Valore
Client minimo supportato	Windows Vista [solo app desktop]
Server minimo supportato	Windows Server 2008 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	iphlpapi.h
Libreria	Iphlpapi.lib
DLL	Iphlpapi.dll