Funzione di callback LPWSPSETSOCKOPT (ws2spi.h)

Articolo
08/28/2023

La funzione LPWSPSetSockOpt imposta un'opzione socket.

Sintassi

LPWSPSETSOCKOPT Lpwspsetsockopt;

int Lpwspsetsockopt(
  [in]  SOCKET s,
  [in]  int level,
  [in]  int optname,
  [in]  const char *optval,
  [in]  int optlen,
  [out] LPINT lpErrno
)
{...}

Parametri

[in] s

Descrittore che identifica un socket.

[in] level

Livello in cui è definita l'opzione; I livelli supportati includono SOL_SOCKET. Per altre informazioni, vedere Winsock Disock.

[in] optname

Opzione socket per cui deve essere impostato il valore.

[in] optval

Puntatore al buffer in cui viene fornito il valore per l'opzione richiesta.

[in] optlen

Dimensione, in byte, del buffer optval .

[out] lpErrno

Puntatore al codice di errore.

Valore restituito

Se non si verifica alcun errore, LPWSPSetSockOpt restituisce zero. In caso contrario, viene restituito un valore di SOCKET_ERROR e in lpErrno è disponibile un codice di errore specifico.

Codice di errore	Significato
WSAENETDOWN	Il sottosistema di rete non è riuscito.
WSAEFAULT	Il valore optval non è incluso in una parte valida dello spazio indirizzi del processo o il parametro optlen è troppo piccolo.
WSAEINPROGRESS	La funzione viene richiamata quando è in corso un callback.
WSAEINPROGRESS	Il blocco della chiamata a Windows Sockets è in corso oppure il provider di servizi sta ancora elaborando una funzione di callback.
WSAEINVAL	Il livello non è valido o le informazioni in optval non sono valide.
WSAENETRESET	La connessione è stata interrotta a causa dell'attività keep-alive che rileva un errore durante l'operazione in corso.
WSAENOPROTOOPT	L'opzione è sconosciuta o non supportata per il provider specificato.
WSAENOTCONN	La connessione è stata reimpostata quando viene impostata SO_KEEPALIVE .
WSAENOTSOCK	Il descrittore non è un socket.

Commenti

La funzione LPWSPSetSockOpt imposta il valore corrente per un'opzione socket associata a un socket di qualsiasi tipo, in qualsiasi stato. Anche se le opzioni possono esistere a più livelli di protocollo, sono sempre presenti a livello di socket superiore. Le opzioni influiscono sulle operazioni socket, ad esempio se i messaggi di trasmissione possono essere inviati sul socket.

Esistono due tipi di opzioni socket: opzioni booleane che abilitano o disabilitano una funzionalità o un comportamento e le opzioni che richiedono un valore intero o una struttura. Per abilitare un'opzione booleana, optval punta a un numero intero diverso da zero. Per disabilitare l'opzione, optval punta a un numero intero uguale a zero. Il parametro optlen deve essere uguale a sizeof (int) per le opzioni booleane. Per altre opzioni, optval punta a un numero intero o a una struttura che contiene il valore desiderato per l'opzione e optlen è la lunghezza dell'intero o della struttura.

Per altre informazioni sulle opzioni socket, vedere Opzioni socket.

level = SOL_SOCKET

Valore	Type	Significato
SO_BROADCAST	BOOL	Consente la trasmissione e la ricezione dei messaggi trasmessi sul socket.
SO_DEBUG	BOOL	Registra le informazioni di debug.
SO_DONTLINGER	BOOL	Riservato.
SO_DONTROUTE	BOOL	Routing disabilitato: inviare direttamente a un'interfaccia. L'impostazione di questa opzione socket ha esito positivo, ma viene ignorata nei socket AF_INET; ha esito negativo sui socket AF_INET6 con WSAENOPROTOOPT . Questa opzione non è supportata nei socket ATM (genera un errore).
SO_GROUP_PRIORITY	INT	Riservato.
SO_KEEPALIVE	BOOL	Invia keep-alive. Non supportato nei socket ATM (genera un errore).
SO_LINGER	struct linger	Si verifica una chiusura se sono presenti dati non inviati.
SO_OOBINLINE	BOOL	Riceve i dati OOB nel normale flusso di dati.
SO_RCVBUF	INT	Specifica lo spazio totale di buffer per socket che deve essere riservato alle ricezioni. Non è correlato a SO_MAX_MSG_SIZE e non corrisponde necessariamente alle dimensioni della finestra di ricezione TCP.
SO_REUSEADDR	BOOL	Consente al socket di essere associato a un indirizzo già in uso. Vedere Bind. Non applicabile ai socket ATM.
SO_SNDBUF	INT	Specifica lo spazio totale di buffer per socket che deve essere riservato agli invii. Non è correlato a SO_MAX_MSG_SIZE e non corrisponde necessariamente alle dimensioni di una finestra di invio TCP.
PVD_CONFIG	Dipendente dal provider di servizi	Questo oggetto archivia le informazioni di configurazione per il provider di servizi associato al socket s. Il formato esatto di questa struttura di dati è specifico del provider di servizi.

Se si chiama LPWSPGetSockopt con un'opzione non supportata, verrà restituito un codice di errore WSAENOPROTOOPT restituito in lpErrno.

SO_DEBUG

I provider di servizi Windows Sockets sono invitati, ma non necessari, a fornire informazioni di debug di output se l'opzione SO_DEBUG è impostata da un client SPI Windows Sockets. Il meccanismo per generare le informazioni di debug e il formato non rientrano nell'ambito di questa specifica.

SO_GROUP_PRIORITY

Riservato.

SO_KEEPALIVE

Un client SPI di Windows Sockets può richiedere che un provider TCP/IP consenta l'uso di pacchetti keep-alive sulle connessioni TCP attivando l'opzione socket SO_KEEPALIVE . Un provider Windows Sockets non deve supportare l'uso di keep-alive: se lo fa, la semantica precisa è specifica, ma deve essere conforme alla sezione 4.2.3.6 di RFC 1122: Requisiti per gli host Internet- Livelli di comunicazione. Questa risorsa può essere disponibile solo in inglese. Se una connessione viene eliminata come risultato del mantenimento del codice di errore WSAENETRESET viene restituita a qualsiasi chiamata in corso nel socket e le chiamate successive avranno esito negativo con WSAENOTCONN .

SO_LINGER

SO_LINGER controlla l'azione eseguita quando i dati non inviati vengono accodati su un socket e viene eseguito un LPWSPCloseSocket . Per una descrizione del modo in cui le impostazioni di SO_LINGER influiscono sulla semantica di LPWSPCloseSocket, vedere LPWSPCloseSocket. Il client SPI di Windows Sockets imposta il comportamento desiderato creando una struttura LINGER, puntata dal parametro optval , con gli elementi seguenti.

struct linger {
  u_short l_onoff;
  u_short l_linger;
}

Per abilitare SO_LINGER, un client SPI di Windows Sockets deve impostare l_onoff su un valore diverso da zero, impostare l_linger su zero o sul timeout desiderato, in secondi e chiamare LPWSPSetSockOpt. Per abilitare SO_DONTLINGER, ovvero disabilitare SO_LINGER, l_onoff deve essere impostato su zero e deve essere chiamato LPWSPSetSockOpt . Tenere presente che l'abilitazione di SO_LINGER con un timeout diverso da zero in un socket non sbloccante non è consigliabile. Per altre informazioni, vedere LPWSPCloseSocket.

L'abilitazione di SO_LINGER disabilita anche SO_DONTLINGER e viceversa. Tenere presente che se SO_DONTLINGER è disabilitato ,ovvero SO_LINGER è abilitato, non viene specificato alcun valore di timeout. In questo caso, il timeout usato dipende dall'implementazione. Se è stato stabilito un timeout precedente per un socket ( abilitando SO_LINGER), questo valore di timeout deve essere ripristinato dal provider di servizi.

SO_REUSEADDR

Per impostazione predefinita, non è possibile associare un socket (per altre informazioni, vedere LPWSPBind) a un indirizzo locale già in uso. In occasione, tuttavia, potrebbe essere opportuno riutilizzare un indirizzo in questo modo. Poiché ogni connessione viene identificata in modo univoco dalla combinazione di indirizzi locali e remoti, non esiste alcun problema con due socket associati allo stesso indirizzo locale purché gli indirizzi remoti siano diversi. Per informare il provider Windows Sockets che un LPWSPBind in un socket deve essere consentito di associare a un indirizzo locale già usato da un altro socket, il client SPI di Windows Sockets deve impostare l'opzione di socket SO_REUSEADDR per il socket prima di emettere LPWSPBind. Tenere presente che l'opzione viene interpretata solo al momento dell'LPWSPBind: è pertanto non necessaria, ma innocua, per impostare l'opzione su un socket che non deve essere associata a un indirizzo esistente e impostare o reimpostare l'opzione dopo LPWSPBind non ha alcun effetto su questo o su qualsiasi altro socket.

SO_SNDBUF

Quando un'implementazione di Windows Sockets supporta le opzioni di SO_RCVBUF e SO_SNDBUF , un client SPI di Windows Sockets può richiedere dimensioni del buffer diverse (più grandi o più piccole). La chiamata può avere esito positivo anche se il provider di servizi non ha reso disponibile l'intero importo richiesto. Un client SPI di Windows Sockets deve chiamare LPWSPGetSockopt con la stessa opzione per verificare la dimensione del buffer effettivamente fornita.

PVD_CONFIG

Questo oggetto archivia le informazioni di configurazione per il provider di servizi associato a socket s. Il formato esatto di questa struttura di dati è specifico del provider di servizi.

Requisiti

Requisito	Valore
Client minimo supportato	Windows 2000 Professional [solo app desktop]
Server minimo supportato	Windows 2000 Server [solo app desktop]
Intestazione	ws2spi.h