funzione setockopt (winsock.h)

Articolo
08/27/2023

La funzione setockopt imposta un'opzione socket.

Sintassi

int setsockopt(
  [in] SOCKET     s,
  [in] int        level,
  [in] int        optname,
  [in] const char *optval,
  [in] int        optlen
);

Parametri

[in] s

Descrittore che identifica un socket.

[in] level

Livello a cui viene definita l'opzione , ad esempio SOL_SOCKET.

[in] optname

Opzione socket per la quale deve essere impostato il valore ,ad esempio SO_BROADCAST. Il parametro optname deve essere un'opzione socket definita all'interno del livello specificato o il comportamento non definito.

[in] optval

Puntatore al buffer in cui viene specificato il valore dell'opzione richiesta.

[in] optlen

Dimensioni, in byte, del buffer a cui punta il parametro optval .

Valore restituito

Se non si verifica alcun errore, setockopt restituisce zero. In caso contrario, viene restituito un valore di SOCKET_ERROR e un codice di errore specifico può essere recuperato chiamando WSAGetLastError.

Codice di errore	Significato
WSANOTINITIALISED	Prima di usare questa funzione, è necessario eseguire una chiamata WSAStartup riuscita.
WSAENETDOWN	Il sottosistema di rete non è riuscito.
WSAEFAULT	Il buffer a cui punta il parametro optval non si trova in una parte valida dello spazio degli indirizzi del processo o il parametro optlen è troppo piccolo.
WSAEINPROGRESS	Una chiamata windows Sockets 1.1 bloccata è in corso oppure il provider di servizi sta ancora elaborando una funzione di callback.
WSAEINVAL	Il parametro di livello non è valido o le informazioni nel buffer a cui punta il parametro optval non sono valide.
WSAENETRESET	La connessione è scaduta quando viene impostata SO_KEEPALIVE .
WSAENOPROTOOPT	L'opzione è sconosciuta o non supportata per il provider o il socket specificato (vedere limitazioni SO_GROUP_PRIORITY).
WSAENOTCONN	La connessione è stata reimpostata quando viene impostata SO_KEEPALIVE .
WSAENOTSOCK	Il descrittore non è un socket.

Commenti

La funzione setockopt 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 dati OOB (dati OOB) vengono ricevuti nel normale flusso di dati e se i messaggi di trasmissione possono essere inviati nel socket.

Nota Se la funzione setockopt viene chiamata prima della funzione di associazione , le opzioni TCP/IP non verranno controllate tramite TCP/IP fino a quando non si verifica l'associazione . In questo caso, la chiamata alla funzione setockopt avrà sempre esito positivo, ma la chiamata alla funzione di associazione può avere esito negativo a causa di una chiamata setockopt anticipata.

Nota Se viene aperto un socket, viene eseguita una chiamata setockopt e viene eseguita una chiamata sendto , Windows Sockets esegue una chiamata di funzione di associazione implicita.

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

Le tabelle seguenti elencano alcune delle opzioni comuni supportate dalla funzione setockopt . La colonna Type identifica il tipo di dati indirizzato dal parametro optval . La colonna Description fornisce alcune informazioni di base sull'opzione socket. Per altri elenchi completi di opzioni socket e informazioni più dettagliate (valori predefiniti, ad esempio), vedere gli argomenti dettagliati in Opzioni socket.

Livello = SOL_SOCKET

Valore	Tipo	Descrizione
SO_BROADCAST	BOOL	Configura un socket per l'invio di dati di trasmissione.
SO_CONDITIONAL_ACCEPT	BOOL	Consente di accettare o rifiutare le connessioni in ingresso dall'applicazione, non dallo stack di protocolli.
SO_DEBUG	BOOL	Abilita l'output di debug. I provider Microsoft attualmente non generano alcuna informazione di debug.
SO_DONTLINGER	BOOL	Non blocca l'attesa per l'invio di dati non inviati. L'impostazione di questa opzione equivale a impostare SO_LINGER con l_onoff impostata su zero.
SO_DONTROUTE	BOOL	Imposta se i dati in uscita devono essere inviati all'interfaccia a cui il socket è associato e non a un route su un'altra interfaccia. Questa opzione non è supportata nei socket ATM (genera un errore).
SO_GROUP_PRIORITY	INT	Riservato.
SO_KEEPALIVE	BOOL	Abilita l'invio di pacchetti keep-alive per una connessione socket. Non supportato nei socket ATM (genera un errore).
SO_LINGER	INDUGIARE	Si verifica una chiusura se i dati non sono presenti.
SO_OOBINLINE	BOOL	Indica che i dati non associati devono essere restituiti in linea con dati regolari. Questa opzione è valida solo per i protocolli orientati alla connessione che supportano i dati out-of-band. Per una discussione di questo argomento, vedere Protocol Independent Out-Of-Band Data(Dati out-of-band indipendenti dal protocollo).
SO_RCVBUF	INT	Specifica lo spazio totale di buffer per socket che deve essere riservato alle ricezioni.
SO_REUSEADDR	BOOL	Consente al socket di essere associato a un indirizzo già in uso. Per altre informazioni, vedere binding. Non applicabile ai socket ATM.
SO_EXCLUSIVEADDRUSE	BOOL	Abilita l'associazione di un socket per l'accesso esclusivo. Non richiede privilegi amministrativi.
SO_RCVTIMEO	DWORD	Imposta il timeout, in millisecondi, per bloccare le chiamate di ricezione.
SO_SNDBUF	INT	Specifica lo spazio totale di buffer per socket che deve essere riservato agli invii.
SO_SNDTIMEO	DWORD	Timeout, in millisecondi, per bloccare le chiamate di invio.
SO_UPDATE_ACCEPT_CONTEXT	INT	Aggiornamenti il socket di accettazione con il contesto del socket di ascolto.
PVD_CONFIG	Provider di servizi dipendente	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.

Per informazioni più complete e dettagliate sulle opzioni di socket per SOL_SOCKET di livello = , vedere opzioni socket SOL_SOCKET.

Livello = IPPROTO_TCP

Vedere TCP_NODELAY nelle opzioni del socket IPPROTO_TCP. Vedere anche questo argomento per informazioni più complete e dettagliate sulle opzioni di socket per il livello = IPPROTO_TCP.

Livello = NSPROTO_IPX

Valore	Tipo	Descrizione
IPX_PTYPE	INT	Imposta il tipo di pacchetto IPX.
IPX_FILTERPTYPE	INT	Imposta il tipo di pacchetto di filtro di ricezione
IPX_STOPFILTERPTYPE	INT	Arresta il filtro del set di tipi di filtro con IPX_FILTERTYPE
IPX_DSTYPE	INT	Imposta il valore del campo del flusso di dati nell'intestazione SPX in ogni pacchetto inviato.
IPX_EXTENDED_ADDRESS	BOOL	Imposta se l'indirizzamento esteso è abilitato.
IPX_RECVHDR	BOOL	Imposta se l'intestazione del protocollo viene inviata su tutte le intestazioni di ricezione.
IPX_RECEIVE_BROADCAST	BOOL	Indica che i pacchetti di trasmissione sono probabilmente nel socket. Impostare su TRUE per impostazione predefinita. Le applicazioni che non usano le trasmissioni devono impostare su FALSE per migliorare le prestazioni del sistema.
IPX_IMMEDIATESPXACK	BOOL	Indirizza le connessioni SPX non per ritardare l'invio di un ACK. Le applicazioni senza traffico indietro e indietro devono impostare questa opzione su TRUE per aumentare le prestazioni.

Per informazioni più complete e dettagliate sulle opzioni di socket per il livello = NSPROTO_IPX, vedere opzioni socket NSPROTO_IPX.

Le opzioni BSD non supportate per setockopt sono visualizzate nella tabella seguente.

Valore	Tipo	Descrizione
SO_ACCEPTCONN	BOOL	Restituisce se un socket è in modalità di ascolto. Questa opzione è valida solo per i protocolli orientati alla connessione. Questa opzione socket non è supportata per l'impostazione.
SO_RCVLOWAT	INT	Opzione socket da BSD UNIX inclusa per la compatibilità con le versioni precedenti. Questa opzione imposta il numero minimo di byte da elaborare per le operazioni di input socket.
SO_SNDLOWAT	INT	Opzione socket da BSD UNIX inclusa per la compatibilità con le versioni precedenti. Questa opzione imposta il numero minimo di byte da elaborare per le operazioni di output del socket.
SO_TYPE	INT	Restituisce il tipo di socket per il socket specificato (SOCK_STREAM o SOCK_DGRAM, ad esempio Questa opzione socket non è supportata per l'impostazione del tipo di socket.

Nota Quando si emette una chiamata Winsock bloccante, ad esempio setockopt, Winsock potrebbe dover attendere un evento di rete prima che la chiamata possa essere completata. Winsock esegue un'attesa avvisabile in questa situazione, che può essere interrotta da una chiamata di routine asincrona pianificata nello stesso thread. L'emissione di un'altra chiamata winsock bloccata all'interno di un APC che ha interrotto una chiamata winsock in corso sullo stesso thread comporterà un comportamento non definito e non deve mai essere tentato dai client Winsock.

Codice di esempio

Nell'esempio seguente viene illustrata la funzione setockopt .

#ifndef UNICODE
#define UNICODE
#endif

#ifndef WIN32_LEAN_AND_MEAN
#define WIN32_LEAN_AND_MEAN
#endif

#include <winsock2.h>
#include <Ws2tcpip.h>
#include <stdio.h>

// Link with ws2_32.lib
#pragma comment(lib, "Ws2_32.lib")

int main()
{

    //---------------------------------------
    // Declare variables
    WSADATA wsaData;

    SOCKET ListenSocket;
    sockaddr_in service;

    int iResult = 0;

    BOOL bOptVal = FALSE;
    int bOptLen = sizeof (BOOL);

    int iOptVal = 0;
    int iOptLen = sizeof (int);

    //---------------------------------------
    // Initialize Winsock
    iResult = WSAStartup(MAKEWORD(2, 2), &wsaData);
    if (iResult != NO_ERROR) {
        wprintf(L"Error at WSAStartup()\n");
        return 1;
    }
    //---------------------------------------
    // Create a listening socket
    ListenSocket = socket(AF_INET, SOCK_STREAM, IPPROTO_TCP);
    if (ListenSocket == INVALID_SOCKET) {
        wprintf(L"socket function failed with error: %u\n", WSAGetLastError());
        WSACleanup();
        return 1;
    }
    //---------------------------------------
    // Bind the socket to the local IP address
    // and port 27015
    hostent *thisHost;
    char *ip;
    u_short port;
    port = 27015;
    thisHost = gethostbyname("");
    ip = inet_ntoa(*(struct in_addr *) *thisHost->h_addr_list);

    service.sin_family = AF_INET;
    service.sin_addr.s_addr = inet_addr(ip);
    service.sin_port = htons(port);

    iResult = bind(ListenSocket, (SOCKADDR *) & service, sizeof (service));
    if (iResult == SOCKET_ERROR) {
        wprintf(L"bind failed with error %u\n", WSAGetLastError());
        closesocket(ListenSocket);
        WSACleanup();
        return 1;
    }
    //---------------------------------------
    // Initialize variables and call setsockopt. 
    // The SO_KEEPALIVE parameter is a socket option 
    // that makes the socket send keepalive messages
    // on the session. The SO_KEEPALIVE socket option
    // requires a boolean value to be passed to the
    // setsockopt function. If TRUE, the socket is
    // configured to send keepalive messages, if FALSE
    // the socket configured to NOT send keepalive messages.
    // This section of code tests the setsockopt function
    // by checking the status of SO_KEEPALIVE on the socket
    // using the getsockopt function.

    bOptVal = TRUE;

    iResult = getsockopt(ListenSocket, SOL_SOCKET, SO_KEEPALIVE, (char *) &iOptVal, &iOptLen);
    if (iResult == SOCKET_ERROR) {
        wprintf(L"getsockopt for SO_KEEPALIVE failed with error: %u\n", WSAGetLastError());
    } else
        wprintf(L"SO_KEEPALIVE Value: %ld\n", iOptVal);

    iResult = setsockopt(ListenSocket, SOL_SOCKET, SO_KEEPALIVE, (char *) &bOptVal, bOptLen);
    if (iResult == SOCKET_ERROR) {
        wprintf(L"setsockopt for SO_KEEPALIVE failed with error: %u\n", WSAGetLastError());
    } else
        wprintf(L"Set SO_KEEPALIVE: ON\n");

    iResult = getsockopt(ListenSocket, SOL_SOCKET, SO_KEEPALIVE, (char *) &iOptVal, &iOptLen);
    if (iResult == SOCKET_ERROR) {
        wprintf(L"getsockopt for SO_KEEPALIVE failed with error: %u\n", WSAGetLastError());
    } else
        wprintf(L"SO_KEEPALIVE Value: %ld\n", iOptVal);

    closesocket(ListenSocket);
    WSACleanup();
    return 0;
}

Note per i socket IrDA

Quando si sviluppano applicazioni con socket Windows per IrDA, tenere presente quanto segue:

Il file di intestazione Af_irda.h deve essere incluso in modo esplicito.
IrDA offre l'opzione socket seguente:

Valore Type Significato

IRLMP_IAS_SET *IAS_SET Imposta gli attributi IAS

Valore	Type	Significato
IRLMP_IAS_SET	*IAS_SET	Imposta gli attributi IAS

L'opzione socket IRLMP_IAS_SET consente all'applicazione di impostare un singolo attributo di una singola classe nello IAS locale. L'applicazione specifica la classe da impostare, l'attributo e il tipo di attributo. L'applicazione deve allocare un buffer delle dimensioni necessarie per i parametri passati.

IrDA fornisce un database IAS che archivia le informazioni basate su IrDA. L'accesso limitato al database IAS è disponibile tramite l'interfaccia Windows Sockets 2, ma tale accesso non viene normalmente usato dalle applicazioni ed esiste principalmente per supportare connessioni a dispositivi non Windows non conformi alle convenzioni IrDA di Windows Sockets 2.

La struttura seguente, IAS_SET, viene usata con l'opzione setockopt di IRLMP_IAS_SET per gestire il database IAS locale:


// #include <Af_irda.h> for this struct

typedef struct _IAS_SET {
    u_char      irdaClassName[IAS_MAX_CLASSNAME];
    char      irdaAttribName[IAS_MAX_ATTRIBNAME];
    u_long    irdaAttribType;
    union
    {
              LONG irdaAttribInt;
              struct
              {
                   u_long   Len;
                   u_char    OctetSeq[IAS_MAX_OCTET_STRING];
              } irdaAttribOctetSeq;
              struct
              {
                   u_long    Len;
                   u_long    CharSet;
                   u_char    UsrStr[IAS_MAX_USER_STRING];
              } irdaAttribUsrStr;
    } irdaAttribute;
} IAS_SET, *PIAS_SET, FAR *LPIASSET;

La struttura seguente, IAS_QUERY, viene usata con l'opzione setockopt di IRLMP_IAS_QUERY per eseguire query sul database IAS di un peer:


// #include <Af_irda.h> for this struct

typedef struct _WINDOWS_IAS_QUERY {
        u_char   irdaDeviceID[4];
        char     irdaClassName[IAS_MAX_CLASSNAME];
        char     irdaAttribName[IAS_MAX_ATTRIBNAME];
        u_long   irdaAttribType;
        union
        {
                  LONG    irdaAttribInt;
                  struct
                  {
                          u_long  Len;
                          u_char  OctetSeq[IAS_MAX_OCTET_STRING];
                  } irdaAttribOctetSeq;
                  struct
                  {
                          u_long  Len;
                          u_long  CharSet;
                          u_char  UsrStr[IAS_MAX_USER_STRING];
                  } irdaAttribUsrStr;
        } irdaAttribute;
} IAS_QUERY, *PIAS_QUERY, FAR *LPIASQUERY;

Molte opzioni di socket a livello di SO_ non sono significative per IrDA. Solo SO_LINGER è supportato in modo specifico.

Windows Phone 8: questa funzione è supportata per le app Windows Phone Store in Windows Phone 8 e versioni successive.

Windows 8.1 e Windows Server 2012 R2: questa funzione è supportata per le app di Windows Store in Windows 8.1, Windows Server 2012 R2 e versioni successive.

Requisiti


Client minimo supportato	Windows 8.1, Windows Vista [app desktop \| App UWP]
Server minimo supportato	Windows Server 2003 [app desktop \| App UWP]
Piattaforma di destinazione	Windows
Intestazione	winsock.h (include Winsock2.h)
Libreria	Ws2_32.lib
DLL	Ws2_32.dll