codice di controllo SIO_ASSOCIATE_PORT_RESERVATION

Articolo
06/13/2023

Descrizione

Il codice di controllo SIO_ASSOCIATE_PORT_RESERVATION associa un socket a una prenotazione persistente o di runtime per un blocco di TCP o UDP identificato dal token di prenotazione della porta. Questo IOCTL deve essere emesso prima che il socket sia associato. Se e quando il socket è associato, la porta assegnata verrà selezionata dalla prenotazione della porta identificata dal token specificato. Se non sono disponibili porte dalla prenotazione specificata , la chiamata di funzione di associazione avrà esito negativo.

Per eseguire questa operazione, chiamare la funzione WSAIoctl o WSPIoctl con i parametri seguenti.

int WSAIoctl(
  (socket) s,             // descriptor identifying a socket
  SIO_ASSOCIATE_PORT_RESERVATION, // dwIoControlCode
  (LPVOID) lpvInBuffer,  // pointer to an INET_PORT_RESERVATION_TOKEN
  (DWORD) cbInBuffer,    // size, in bytes, of the input buffer
  NULL,           // lpvOutBuffer is a pointer to the output buffer
  0,              // cbOutBuffer is the size, in bytes, of the output buffer
  (LPDWORD) lpcbBytesReturned,    // number of bytes returned
  (LPWSAOVERLAPPED) lpOverlapped,   // OVERLAPPED structure
  (LPWSAOVERLAPPED_COMPLETION_ROUTINE) lpCompletionRoutine,  // completion routine
);

int WSPIoctl(
  (socket) s,             // descriptor identifying a socket
  SIO_ASSOCIATE_PORT_RESERVATION, // dwIoControlCode
  (LPVOID) lpvInBuffer,  // pointer to an INET_PORT_RESERVATION_TOKEN
  (DWORD) cbInBuffer,    // size, in bytes, of the input buffer
  NULL,           // lpvOutBuffer is a pointer to the output buffer
  0,              // cbOutBuffer is the size, in bytes, of the output buffer
  (LPDWORD) lpcbBytesReturned,    // number of bytes returned
  (LPWSAOVERLAPPED) lpOverlapped,   // OVERLAPPED structure
  (LPWSAOVERLAPPED_COMPLETION_ROUTINE) lpCompletionRoutine,  // completion routine
  (LPWSATHREADID) lpThreadId,   // a WSATHREADID structure
  (LPINT) lpErrno   // a pointer to the error code.
);

Parametri

s

Descrittore che identifica un socket.

dwIoControlCode

Codice di controllo per l'operazione. Usare SIO_ASSOCIATE_PORT_RESERVATION per questa operazione.

lpvInBuffer

Puntatore al buffer di input. Questo parametro contiene un puntatore a una struttura INET_PORT_RESERVATION_TOKEN con il token per la prenotazione della porta TCP o UDP da associare al socket.

cbInBuffer

Dimensione, in byte, del buffer di input. Questo parametro deve avere almeno le dimensioni della struttura INET_PORT_RESERVATION_TOKEN .

lpvOutBuffer

Puntatore al buffer di output. Questo parametro non è usato per questa operazione.

cbOutBuffer

Dimensione, in byte, del buffer di output. Questo parametro deve essere impostato su zero.

lpcbBytesReturned

Puntatore a una variabile che riceve le dimensioni, in byte, dei dati archiviati nel buffer di output.

Se il buffer di output è troppo piccolo, la chiamata non riesce, WSAGetLastErrorrestituisce WSAEINVAL e il parametro lpcbBytesReturned punta a un valore DWORD pari a zero.

Se lpOverlapped è NULL, il valore DWORD a cui punta il parametro lpcbBytesReturned restituito in una chiamata riuscita non può essere zero.

Se il parametro lpOverlapped non è NULL per i socket sovrapposti, le operazioni che non possono essere completate immediatamente verranno avviate e il completamento verrà indicato in un secondo momento. Il valore DWORD a cui punta il parametro lpcbBytesReturned restituito può essere zero perché le dimensioni dei dati archiviati non possono essere determinate fino al completamento dell'operazione sovrapposta. Lo stato di completamento finale può essere recuperato quando viene segnalato il metodo di completamento appropriato al termine dell'operazione.

lpvOverlapped

Puntatore a una struttura WSAOVERLAPPED .

Se socket s è stato creato senza l'attributo sovrapposto, il parametro lpOverlapped viene ignorato.

Se s è stato aperto con l'attributo sovrapposto e il parametro lpOverlapped non è NULL, l'operazione viene eseguita come operazione sovrapposta (asincrona). In questo caso, il parametro lpOverlapped deve puntare a una struttura WSAOVERLAPPED valida.

Per le operazioni sovrapposte, la funzione WSAIoctl o WSPIoctl restituisce immediatamente e il metodo di completamento appropriato viene segnalato al termine dell'operazione. In caso contrario, la funzione non restituisce finché l'operazione non è stata completata o si verifica un errore.

lpCompletionRoutine

Tipo: _In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE

Puntatore alla routine di completamento chiamata quando l'operazione è stata completata (ignorata per socket non sovrapposti).

lpThreadId

Puntatore a una struttura WSATHREADID da usare dal provider in una chiamata successiva a WPUQueueApc. Il provider deve archiviare la struttura WSATHREADID a cui si fa riferimento (non il puntatore allo stesso) fino a quando non viene restituita la funzione WPUQueueApc .

Nota Questo parametro si applica solo alla funzione WSPIoctl .

lpErrno

Puntatore al codice di errore.

Nota Questo parametro si applica solo alla funzione WSPIoctl .

Valore restituito

Se l'operazione viene completata correttamente, la funzione WSAIoctl o WSPIoctl restituisce zero.

Se l'operazione ha esito negativo o è in sospeso, la funzione WSAIoctl o WSPIoctl restituisce SOCKET_ERROR. Per ottenere informazioni estese sull'errore, chiamare WSAGetLastError.

Codice di errore	Significato
WSA_IO_PENDING	L'operazione di I/O sovrapposta è in corso. Questo valore viene restituito se un'operazione sovrapposta è stata avviata correttamente e il completamento verrà indicato in un secondo momento.
WSA_OPERATION_ABORTED	Operazione di I/O annullata per uscita da un thread o su richiesta di un'applicazione. Questo errore viene restituito se un'operazione sovrapposta è stata annullata a causa della chiusura del socket o dell'esecuzione del comando IOCTL SIO_FLUSH .
WSAEACCES	È stato effettuato un tentativo di accesso a un socket in modo non consentito dalle autorizzazioni di accesso. Questo errore viene restituito in diverse condizioni per le prenotazioni di porte persistenti 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 (`RunAs administrator`).
WSAEFAULT	Il sistema ha rilevato un indirizzo puntatore non valido nel tentativo di usare un argomento puntatore in una chiamata. Questo errore viene restituito del parametro lpvInBuffer, lpvoutBuffer, lpcbBytesReturned, lpOverlapped o lpCompletionRoutine non è completamente contenuto in una parte valida dello spazio indirizzi utente.
WSAEINPROGRESS	È in corso un'operazione di blocco. Questo errore viene restituito se la funzione viene richiamata quando è in corso un callback.
WSAEINTR	Un'operazione di blocco è stata interrotta da una chiamata a WSACancelBlockingCall. Questo errore viene restituito se un'operazione di blocco è stata interrotta.
WSAEINVAL	Argomento fornito non valido. Questo errore viene restituito se il parametro dwIoControlCode non è un comando valido o un parametro di input specificato non è accettabile oppure il comando non è applicabile al tipo di socket specificato.
WSAENETDOWN	Rete inattiva rilevata durante l'operazione del socket. Questo errore viene restituito se il sottosistema di rete non è riuscito.
WSAENOTSOCK	È stata tentata un'operazione su un elemento che non è un socket. Questo errore viene restituito se il descrittore s non è un socket.
WSAEOPNOTSUPP	L'operazione tentata non è supportata per il tipo di oggetto a cui si fa riferimento. Questo errore viene restituito se il comando IOCTL specificato non è supportato. Questo errore viene restituito anche se il SIO_ASSOCIATE_PORT_RESERVATION IOCTL non è supportato dal provider di trasporto. Questo errore viene restituito anche quando viene eseguito un tentativo di usare il SIO_ASSOCIATE_PORT_RESERVATION IOCTL in un socket diverso da UDP o TCP.

Commenti

Il SIO_ASSOCIATE_PORT_RESERVATION IOCTL è supportato in Windows Vista e versioni successive del sistema operativo.

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 come parte del loro funzionamento. 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 necessitano di qualsiasi porta o blocco di porte disponibile in fase di esecuzione. Queste due categorie corrispondono a richieste di prenotazione di porte specifiche e con caratteri jolly. Le richieste di prenotazione specifiche possono essere persistenti o in fase di esecuzione, mentre le richieste di prenotazione con porta con caratteri jolly sono supportate solo in fase di esecuzione.

Il SIO_ASSOCIATE_PORT_RESERVATION IOCTL viene usato per associare una prenotazione di porta TCP o UDP a una prenotazione permanente o di runtime.

La funzione CreatePersistentTcpPortReservation o CreatePersistentUdpPortReservation consente a un'applicazione o a un servizio di riservare un blocco permanente di porte TCP o UDP. Le prenotazioni delle porte persistenti vengono registrate in un archivio permanente per il modulo TCP o UDP in Windows. Si noti che il token per una determinata prenotazione di porta persistente può cambiare ogni volta che il sistema viene riavviato.

Dopo aver ottenuto una prenotazione della porta TCP o UDP persistente, un'applicazione può richiedere assegnazioni di porta dalla prenotazione della porta aprendo un socket TCP o 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 di porte persistenti create usando la funzione CreatePersistentTcpPortReservation o CreatePersistentUdpPortReservation possono essere usate da qualsiasi processo con la possibilità di ottenere prenotazioni persistenti.

Dopo aver ottenuto una prenotazione della porta TCP o UDP di runtime, un'applicazione può richiedere assegnazioni di porta dalla prenotazione della porta aprendo un socket TCP o 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.

Se entrambi i parametri lpOverlapped e lpCompletionRoutine sono NULL, il socket in questa funzione verrà considerato come socket non sovrapposto. Per un socket non sovrapposto, i parametri lpOverlapped e lpCompletionRoutine vengono ignorati, ad eccezione del fatto che la funzione può bloccare se socket s è in modalità di blocco. Se socket s è in modalità non bloccabile, questa funzione continuerà a bloccarsi poiché questa particolare modalità IOCTL non supporta la modalità di blocco.

Per i socket sovrapposti, le operazioni che non possono essere completate immediatamente verranno avviate e il completamento verrà indicato in un secondo momento.

Qualsiasi IOCTL può bloccare in modo indefinito, a seconda dell'implementazione del provider di servizi. Se l'applicazione non può tollerare il blocco in una chiamata di funzione WSAIoctl o WSPIoctl , l'I/O sovrapposto dovrebbe essere consigliato per IOCTLs che sono particolarmente probabilità di bloccare.

Il SIO_ASSOCIATE_PORT_RESERVATION IOCTL può non riuscire con WSAEINTR o WSA_OPERATION_ABORTED nei casi seguenti:

La richiesta viene annullata da I/O Manager.
Il socket è chiuso.

La SIO_ASSOCIATE_PORT_RESERVATION IOCTL passata alla funzione WSAIoctl o WSPIoctl per una prenotazione di porta persistente può essere usata solo in un'applicazione quando l'utente viene connesso come membro del gruppo Administrators. Se SIO_ASSOCIATE_PORT_RESERVATION IOCTL viene usato in un'applicazione quando l'utente non è membro del gruppo Administrators, la chiamata alla funzione avrà esito negativo e viene restituito WSAEACCES . L'uso della SIO_ASSOCIATE_PORT_RESERVATION IOCTL può anche non riuscire a causa del controllo dell'account utente in Windows Vista e versioni successive. Se un'applicazione che usa questo IOCTL con una prenotazione di porta persistente 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 (RunAs administrator) per la riuscita di questa funzione.