setockopt 函式 (winsock.h)

  • 發行項

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 中設定單一類別的單一屬性。 應用程式會指定要設定的類別、屬性和屬性類型。 應用程式預期會為傳遞的參數配置必要大小的緩衝區。

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

另請參閱

IPPROTO_IP通訊端選項

IPPROTO_IPV6通訊端選項

IPPROTO_RM通訊端選項

IPPROTO_TCP通訊端選項

IPPROTO_UDP通訊端選項

NSPROTO_IPX通訊端選項

SOL_APPLETALK通訊端選項

SOL_IRLMP通訊端選項

SOL_SOCKET通訊端選項

通訊端選項

WSAAsyncSelect

WSAEventSelect

WSAIoctl

Winsock 函式

bind

getsockopt

ioctlsocket

socket