Funzione CreatePersistentUdpPortReservation (iphlpapi.h)

Articolo
03/14/2023

La funzione CreatePersistentUdpPortReservation crea una prenotazione di porta UDP persistente per un blocco consecutivo di porte UDP nel computer locale.

Sintassi

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

Parametri

[in] StartPort

Numero di porta UDP iniziale nell'ordine di byte di rete.

[in] NumberOfPorts

Numero di numeri di porta UDP da riservare.

[out] Token

Puntatore a un token di prenotazione della porta restituito se la funzione ha esito positivo.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è 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	Un parametro non valido è stato passato alla funzione. Questo errore viene restituito se zero viene passato nei parametri StartPort o NumberOfPorts . Questo errore viene restituito anche se il parametro NumberOfPorts è troppo grande un blocco di porte a seconda del parametro StartPort che il blocco allocabile di porte supera la porta massima che può essere allocata.
ERROR_SHARING_VIOLATION	Il processo non può accedere al file perché è in uso da un altro processo. Questo errore viene restituito se viene usata una porta UDP nel blocco di porte UDP specificate dai parametri StartPort e NumberOfPorts . Questo errore viene restituito anche se una prenotazione persistente per un blocco di porte UDP specificate dai parametri StartPort e NumberOfPorts corrisponde o sovrappone una prenotazione persistente per un blocco di porte UDP già create.
Altri	Usare FormatMessage per ottenere la stringa di messaggio per l'errore restituito.

Commenti

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

La funzione CreatePersistentUdpPortReservation viene usata per aggiungere una prenotazione persistente per un blocco di porte UDP.

Le applicazioni e i servizi che devono riservare le porte rientrano in due categorie. La prima categoria include componenti che necessitano di una determinata porta nell'ambito dell'operazione. Tali componenti preferiscono in genere specificare la porta richiesta in fase di installazione (ad esempio in un manifesto dell'applicazione). La seconda categoria include componenti che richiedono qualsiasi porta o blocco disponibile di porte in fase di esecuzione.

Queste due categorie corrispondono a richieste di prenotazione delle porte con caratteri jolly e specifiche. Le richieste di prenotazione specifiche possono essere persistenti o in fase di esecuzione, mentre le richieste di prenotazione con porta jolly sono supportate solo in fase di esecuzione.

La funzione CreatePersistentUdpPortReservation consente a un'applicazione o a un servizio di riservare in modo permanente un blocco di porte UDP. Le prenotazioni TCP persistenti vengono registrate in un archivio permanente per il modulo UDP in Windows.

Un chiamante ottiene una prenotazione di porta persistente specificando il numero di porte necessarie e se è necessario un intervallo specifico. Se la richiesta può essere soddisfatta, la funzione CreatePersistentUdpPortReservation restituisce un token opaco ULONG64 univoco, che identifica successivamente la prenotazione. Una prenotazione della porta UDP persistente può essere rilasciata chiamando la funzione DeletePersistentUdpPortReservation . Si noti che il token per una determinata prenotazione della porta UDP persistente può cambiare ogni volta che il sistema viene riavviato.

Windows non implementa la sicurezza tra componenti per le prenotazioni persistenti ottenute usando queste funzioni. Ciò significa che se un componente ha la possibilità di ottenere prenotazioni di porte persistenti, tale componente ottiene automaticamente la possibilità di utilizzare tutte le prenotazioni di porte persistenti concesse a qualsiasi altro componente nel sistema. La sicurezza a livello di processo viene applicata per le prenotazioni di runtime, ma tale controllo non può essere esteso alle prenotazioni persistenti create usando la funzione CreatePersistentTcpPortReservation o CreatePersistentUdpPortReservation .

Dopo aver ottenuto una prenotazione della porta UDP persistente, un'applicazione può richiedere assegnazioni di porta dalla prenotazione della porta UDP aprendo un socket UDP, quindi chiamando la funzione WSAIoctl specificando la SIO_ASSOCIATE_PORT_RESERVATION IOCTL e passando il token di prenotazione prima di inviare una chiamata alla funzione di associazione nel socket.

Il SIO_ACQUIRE_PORT_RESERVATION IOCTL può essere usato per richiedere una prenotazione di runtime per un blocco di porte TCP o UDP. Per le prenotazioni delle porte di runtime, il pool di porte richiede che le prenotazioni vengano usate dal processo in cui è stata concessa la prenotazione. Le prenotazioni delle porte di runtime durano solo fino alla durata del socket in cui è stato chiamato il SIO_ACQUIRE_PORT_RESERVATION IOCTL. Al contrario, le prenotazioni delle porte persistenti create usando la funzione CreatePersistentUdpPortReservation possono essere usate da qualsiasi processo con la possibilità di ottenere prenotazioni persistenti.

La funzione CreatePersistentUdpPortReservation può essere chiamata solo da un utente connesso come membro del gruppo Administrators. Se CreatePersistentUdpPortReservation viene chiamato da un utente che non è membro del gruppo Administrators, la chiamata alla funzione avrà esito negativo e ERROR_ACCESS_DENIED viene restituita. Questa funzione può anche non riuscire a causa del controllo account utente (UAC) in Windows Vista e versioni successive. Se un'applicazione contenente 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 per richiedereAdministrator. Se l'applicazione manca di questo file manifesto, un utente ha eseguito l'accesso come membro del gruppo Administrators diverso dall'amministratore predefinito, deve quindi eseguire l'applicazione in una shell avanzata come amministratore predefinito (amministratore RunAs) per la riuscita di questa funzione.

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