setockopt 函式 (winsock.h)

發行項
08/27/2023

setockopt函式會設定通訊端選項。

語法

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

參數

[in] s

識別通訊端的描述項。

[in] level

選項定義的層級 (例如，SOL_SOCKET) 。

[in] optname

要設定值的通訊端選項 (例如，SO_BROADCAST) 。 optname參數必須是在指定層級內定義的通訊端選項，或未定義行為。

[in] optval

指定所要求選項值的緩衝區指標。

[in] optlen

optval參數所指向之緩衝區的大小，以位元組為單位。

傳回值

如果沒有發生錯誤， setockopt 會傳回零。否則，會傳回SOCKET_ERROR的值，而且可以呼叫 WSAGetLastError來擷取特定的錯誤碼。

錯誤碼	意義
WSANOTINITIALISED	使用此函式之前，必須先進行成功的 WSAStartup 呼叫。
WSAENETDOWN	網路子系統失敗。
WSAEFAULT	optval參數所指向的緩衝區不在進程位址空間的有效部分，或optlen參數太小。
WSAEINPROGRESS	封鎖的 Windows Sockets 1.1 呼叫正在進行中，或者服務提供者仍在處理回呼函式。
WSAEINVAL	level參數無效，或optval參數所指向之緩衝區中的資訊無效。
WSAENETRESET	設定 SO_KEEPALIVE 時，連線已逾時。
WSAENOPROTOOPT	指定提供者或通訊端 (選項未知或不支援，請參閱) SO_GROUP_PRIORITY限制。
WSAENOTCONN	設定 SO_KEEPALIVE 時，已重設連線。
WSAENOTSOCK	描述項不是通訊端。

備註

setockopt函式會以任何狀態設定與任何類型通訊端相關聯的通訊端選項目前值。雖然選項可以存在於多個通訊協定層級，但它們一律存在於最上層的通訊端層級。選項會影響通訊端作業，例如是否在一般資料流程中收到) 的加速資料 (OOB 資料，以及是否可以在通訊端上傳送廣播訊息。

注意如果在系結函式之前呼叫setockopt函式，則在系結發生之前，將不會使用 TCP/IP 檢查 TCP/IP 選項。在此情況下， setockopt 函式呼叫一律會成功，但系結函式呼叫可能會因為早期 setockopt 呼叫失敗而失敗。

注意如果開啟通訊端， 就會進行 setockopt 呼叫，然後進行 sendto 呼叫，Windows Sockets 會執行隱含系結函式呼叫。

通訊端選項有兩種類型：可啟用或停用特徵或行為的布林選項，以及需要整數值或結構的選項。若要啟用布林值選項， optval 參數會指向非零整數。若要停用選項 optval 指向等於零的整數。 optlen參數應該等於 sizeof(int) 布林選項。對於其他選項， optval 會指向包含選項所需值的整數或結構， 而 optlen 是整數或結構的長度。

下表列出 setockopt 函式支援的一些常見選項。 Type 資料行會識別 optval 參數所定址的資料類型。 [描述] 資料行提供有關通訊端選項的一些基本資訊。如需更完整的通訊端選項清單，以及 (預設值的詳細資訊，例如) ，請參閱通訊端選項底下的詳細主題。

水準 = SOL_SOCKET

值	類型	描述
SO_BROADCAST	BOOL	設定用於傳送廣播資料的通訊端。
SO_CONDITIONAL_ACCEPT	BOOL	啟用連入連線是由應用程式接受或拒絕，而不是由通訊協定堆疊接受或拒絕。
SO_DEBUG	BOOL	啟用偵錯輸出。 Microsoft 提供者目前不會輸出任何偵錯資訊。
SO_DONTLINGER	BOOL	不會封鎖關閉等候未傳送的資料。設定此選項相當於將 l_onoff 設定為零的SO_LINGER。
SO_DONTROUTE	BOOL	設定通訊端系結至介面的傳出資料是否應該傳送，而不是在其他介面上路由傳送。 ATM 通訊端不支援此選項， (會導致錯誤) 。
SO_GROUP_PRIORITY	int	保留的。
SO_KEEPALIVE	BOOL	啟用傳送通訊端連線的 Keep-alive 封包。在 ATM 通訊端上不支援 (會導致錯誤) 。
SO_LINGER	縈繞	如果未傳送的資料存在，則會在關閉時閒置。
SO_OOBINLINE	BOOL	表示應該以一般資料內嵌方式傳回超出界限的資料。此選項僅適用于支援頻外資料的連線導向通訊協定。如需本主題的討論，請參閱通訊協定獨立頻外資料。
SO_RCVBUF	int	指定保留給接收的每一通訊端緩衝區總空間。
SO_REUSEADDR	BOOL	允許要繫結至已使用中位址的通訊端。如需詳細資訊，請參閱 bind。不適用於 ATM 通訊端。
SO_EXCLUSIVEADDRUSE	BOOL	啟用將繫結至獨佔存取的通訊端。不需要系統管理許可權。
SO_RCVTIMEO	DWORD	設定封鎖接收呼叫的逾時，以毫秒為單位。
SO_SNDBUF	int	指定保留給傳送的每一通訊端緩衝區總空間。
SO_SNDTIMEO	DWORD	用於封鎖傳送呼叫的逾時以毫秒為單位。
SO_UPDATE_ACCEPT_CONTEXT	int	使用接聽通訊端的內容更新接受通訊端。
PVD_CONFIG	服務提供者相依	此物件會儲存與通訊端相關聯之服務提供者的組態資訊。此資料結構的確切格式是服務提供者的特定格式。

如需層級 = SOL_SOCKET通訊端選項的更完整和詳細資訊，請參閱SOL_SOCKET通訊端選項。

水準 = IPPROTO_TCP

請參閱IPPROTO_TCP通訊端選項中的TCP_NODELAY。另請參閱該主題，以取得層級 = IPPROTO_TCP之通訊端選項的更完整和詳細資訊。

水準 = NSPROTO_IPX

值	類型	描述
IPX_PTYPE	int	設定 IPX 封包類型。
IPX_FILTERPTYPE	int	設定接收篩選封包類型
IPX_STOPFILTERPTYPE	int	停止篩選具有IPX_FILTERTYPE的篩選類型集
IPX_DSTYPE	int	設定每個已傳送封包之 SPX 標頭中的資料流程欄位值。
IPX_EXTENDED_ADDRESS	BOOL	設定是否啟用擴充定址。
IPX_RECVHDR	BOOL	設定是否在所有接收標頭上傳送通訊協定標頭。
IPX_RECEIVE_BROADCAST	BOOL	表示廣播封包可能位於通訊端上。預設設定為 TRUE 。不使用廣播的應用程式應該將此設定為 FALSE ，以提升系統效能。
IPX_IMMEDIATESPXACK	BOOL	指示 SPX 連線在傳送 ACK 之前不會延遲。沒有來回流量的應用程式應該將此設定為 TRUE ，以提升效能。

如需層級 = NSPROTO_IPX通訊端選項的更完整和詳細資訊，請參閱NSPROTO_IPX通訊端選項。

下表顯示 setockopt 不支援的 BSD 選項。

值	類型	描述
SO_ACCEPTCONN	BOOL	傳回通訊端是否處於接聽模式。此選項僅適用于連線導向通訊協定。設定不支援此通訊端選項。
SO_RCVLOWAT	int	來自 BSD UNIX 的通訊端選項，用於回溯相容性。此選項會設定通訊端輸入作業所要處理的位元組數目下限。
SO_SNDLOWAT	int	來自 BSD UNIX 的通訊端選項，用於回溯相容性。此選項會設定要處理通訊端輸出作業的最小位元組數目。
SO_TYPE	int	傳回指定通訊端 (SOCK_STREAM 或SOCK_DGRAM的通訊端類型，例如，設定通訊端類型不支援此通訊端選項。

注意發出封鎖的 Winsock 呼叫，例如 setockopt時，Winsock 可能需要等候網路事件，才能完成呼叫。 Winsock 會在這種情況中執行可警示的等候，而非同步程序呼叫 (APC) 排程在同一個執行緒上，可能會中斷。在 APC 內發出另一個封鎖 Winsock 呼叫，中斷相同執行緒上持續封鎖 Winsock 呼叫會導致未定義的行為，而且永遠不會由 Winsock 用戶端嘗試。

範例程式碼

下列範例示範 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;
}

IrDA 通訊端注意事項

使用適用于 IrDA 的 Windows 通訊端開發應用程式時，請注意下列事項：

必須明確包含 Af_irda.h 標頭檔。
IrDA 提供下列通訊端選項：

值類型意義

IRLMP_IAS_SET *IAS_SET 設定 IAS 屬性

值	類型	意義
IRLMP_IAS_SET	*IAS_SET	設定 IAS 屬性

IRLMP_IAS_SET通訊端選項可讓應用程式在本機 IAS 中設定單一類別的單一屬性。應用程式會指定要設定的類別、屬性和屬性類型。應用程式預期會為傳遞的參數配置必要大小的緩衝區。

IrDA 提供 IAS 資料庫，可儲存以 IrDA 為基礎的資訊。 IAS 資料庫的存取權有限，可透過 Windows Sockets 2 介面取得，但這類存取通常不會供應用程式使用，主要是為了支援與不符合 Windows Sockets 2 IrDA 慣例之非 Windows 裝置的連線。

下列結構 IAS_SET會與 IRLMP_IAS_SET setockopt 選項搭配使用，以管理本機 IAS 資料庫：


// #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;

下列結構 IAS_QUERY會與 IRLMP_IAS_QUERY setockopt 選項搭配使用，以查詢對等的 IAS 資料庫：


// #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;

許多SO_層級通訊端選項對 IrDA 沒有意義。僅支援SO_LINGER。

Windows Phone 8：Windows Phone 8 和更新版本Windows Phone市集應用程式支援此函式。

Windows 8.1和Windows Server 2012 R2：Windows 市集應用程式支援此功能，Windows 8.1、Windows Server 2012 R2 及更新版本。

規格需求


最低支援的用戶端	Windows 8.1、Windows Vista [傳統型應用程式 \|UWP 應用程式]
最低支援的伺服器	Windows Server 2003 [傳統型應用程式 \|UWP 應用程式]
目標平台	Windows
標頭	winsock.h (包含 Winsock2.h)
程式庫	Ws2_32.lib
Dll	Ws2_32.dll