codice di controllo SIO_ADDRESS_LIST_QUERY

Articolo
06/12/2023

Descrizione

Il codice di controllo SIO_ADDRESS_LIST_QUERY ottiene un elenco di indirizzi di trasporto locali della famiglia di protocolli del socket a cui l'applicazione può associare. L'elenco di indirizzi varia in base alla famiglia di indirizzi e alcuni indirizzi vengono esclusi dall'elenco.

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

int WSAIoctl(
  (socket) s,            // descriptor identifying a socket
  SIO_ADDRESS_LIST_QUERY,            // dwIoControlCode
  NULL,                              // lpvInBuffer
  0,                                 // cbInBuffer
  (LPVOID) lpvOutBuffer,          // output buffer
  (DWORD) cbOutBuffer,            // size of 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_ADDRESS_LIST_QUERY,            // dwIoControlCode
  NULL,                              // lpvInBuffer
  0,                                 // cbInBuffer
  (LPVOID) lpvOutBuffer,          // output buffer
  (DWORD) cbOutBuffer,            // size of 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_ADDRESS_LIST_QUERY per questa operazione.

lpvInBuffer

Puntatore al buffer di input. Questo parametro non viene usato per questa operazione.

cbInBuffer

Dimensioni, in byte, del buffer di input. Questo parametro non viene usato per questa operazione.

lpvOutBuffer

Puntatore al buffer di output.

cbOutBuffer

Dimensioni, in byte, del buffer di output.

lpcbBytesReturned

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

lpvOverlapped

Puntatore a una struttura WSAOVERLAPPED .

Se il 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 fa riferimento (non lo stesso puntatore) fino a quando la funzione WPUQueueApc restituisce.

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 sull'errore estese, chiamare WSAGetLastError.

Codice di errore	Significato
WSA_IO_PENDING	Un'operazione sovrapposta è stata avviata correttamente e il completamento verrà indicato in un secondo momento.
WSA_OPERATION_ABORTED	Un'operazione sovrapposta è stata annullata a causa della chiusura del socket o dell'esecuzione del comando IOCTL SIO_FLUSH .
WSAEFAULT	Il parametro lpOverlapped o lpCompletionRoutine non è totalmente contenuto in una parte valida dello spazio degli indirizzi utente.
WSAEINPROGRESS	La funzione viene richiamata quando un callback è in corso.
WSAEINTR	Un'operazione di blocco è stata interrotta.
WSAEINVAL	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. Questo errore viene restituito se il parametro cbInBuffer non è impostato su NULL.
WSAENETDOWN	Il sottosistema di rete non è riuscito.
WSAENOBUFS	Nessun spazio buffer disponibile.
WSAENOPROTOOPT	L'opzione socket non è supportata nel protocollo specificato.
WSAENOTSOCK	Il descrittore s non è un socket.
WSAEOPNOTSUPP	Il comando IOCTL specificato non è supportato. Questo errore viene restituito se il SIO_ADDRESS_LIST_QUERY IOCTL non è supportato dal provider di trasporto.

Commenti

Il SIO_ADDRESS_LIST_QUERY IOCTL è supportato in Windows 2000 e versioni successive del sistema operativo.

Per la famiglia di indirizzi AF_INET6, tutti gli indirizzi vengono restituiti ad eccezione dei seguenti:

Qualsiasi indirizzo IP in cui lo stato del rilevamento degli indirizzi duplicati (DAD) non è IpDadStatePreferred.
Qualsiasi indirizzo IP con un livello di ambito inferiore a ScopeLevelSubnet in un'interfaccia in cui il tipo di interfaccia è IF_TYPE_SOFTWARE_LOOPBACK. Ciò significa che gli indirizzi link-local (fe80:*) e loopback (::1) sulle interfacce di IF_TYPE_SOFTWARE_LOOPBACK tipo vengono esclusi, ma non se questi indirizzi si trovano in un'interfaccia con un tipo diverso.

Per la famiglia di indirizzi AF_INET , tutti gli indirizzi vengono restituiti ad eccezione dei seguenti:

Qualsiasi indirizzo IP in cui lo stato del rilevamento degli indirizzi duplicati (DAD) non è IpDadStatePreferred.
Qualsiasi indirizzo IP in un'interfaccia in cui il tipo di interfaccia è IF_TYPE_SOFTWARE_LOOPBACK e il collegamento è locale. Ciò significa che gli indirizzi link-local (169.254.) e loopback (127.) sulle interfacce di IF_TYPE_SOFTWARE_LOOPBACK tipo sono esclusi, ma non se questi indirizzi si trovano in un'interfaccia con un tipo diverso.

Per altre informazioni sullo stato daD, vedere la documentazione dell'helper IP sulla struttura IP_DAD_STATE enumerazione e IP_ADAPTER_UNICAST_ADDRESS e sulla documentazione MIB sulla struttura MIB_UNICASTIPADDRESS_ROW. Per altre informazioni sul tipo di interfaccia, vedere la documentazione dell'helper IP sulla struttura IP_ADAPTER_ADDRESSES e la funzione GetAdaptersAddresses e la documentazione MIB sulla struttura MIB_IF_ROW2 . Per altre informazioni sul livello di ambito, vedere la documentazione dell'helper IP sulla struttura IP_ADAPTER_ADDRESSES e sull'enumerazione SCOPE_LEVEL .

L'elenco restituito nel buffer di output a cui punta il parametro lpvOutBuffer è sotto forma di una struttura SOCKET_ADDRESS_LIST .

Se il buffer di output specificato nel parametro lpvOutBuffer non è sufficiente per contenere l'elenco indirizzi, SOCKET_ERROR viene restituito come risultato di questo IOCTL e WSAGetLastError restituisce WSAEFAULT. Le dimensioni necessarie, in byte, per il buffer di output vengono restituite nel parametro lpcbBytesReturned in questo caso. Si noti che il codice di errore WSAEFAULT viene restituito anche se il parametro lpvInBuffer, lpvOutBuffer o lpcbBytesReturned non è completamente contenuto in una parte valida dello spazio degli indirizzi utente.

Il SIO_ADDRESS_LIST_QUERY IOCTL viene in genere chiamato in modo sincrono con il parametro lpvOverlapped impostato su NULL, poiché viene restituito immediatamente l'elenco di indirizzi.

Nota Negli ambienti Plug-n Play di Windows è possibile aggiungere e rimuovere gli indirizzi in modo dinamico. Pertanto, le applicazioni non possono basarsi sulle informazioni restituite da SIO_ADDRESS_LIST_QUERY per essere persistenti. Le applicazioni possono registrarsi per le notifiche di modifica degli indirizzi tramite l'evento IOCTL SIO_ADDRESS_LIST_CHANGE che fornisce la notifica tramite l'evento I/O sovrapposto o FD_ADDRESS_LIST_CHANGE . La sequenza di azioni seguente può essere usata per garantire che l'applicazione disponga sempre di informazioni sull'elenco indirizzi correnti:

Rilasciare il SIO_ADDRESS_LIST_CHANGE IOCTL
Rilasciare il SIO_ADDRESS_LIST_QUERY IOCTL
Ogni volta che la chiamata IOCTL SIO_ADDRESS_LIST_CHANGE notifica all'applicazione di una modifica dell'elenco indirizzi (tramite operazioni di I/O sovrapposte o segnalando FD_ADDRESS_LIST_CHANGE evento), l'intera sequenza di azioni deve essere ripetuta.

In Microsoft Windows Software Development Kit (SDK) rilasciato per Windows Vista e versioni successive, l'organizzazione dei file di intestazione è stata modificata e il codice di controllo SIO_ADDRESS_LIST_QUERY viene definito nel file di intestazione Ws2def.h . Si noti che il file di intestazione Ws2def.h viene automaticamente incluso in Winsock2.h e non deve mai essere usato direttamente.