LPWSPSETSOCKOPT 回呼函式 (ws2spi.h)

發行項
03/04/2024

LPWSPSetSockOpt 函式會設定套接字選項。

語法

LPWSPSETSOCKOPT Lpwspsetsockopt;

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

參數

[in] s

識別套接字的描述項。

[in] level

定義選項的層級;支援的層級包括 SOL_SOCKET。如需詳細資訊，請參閱 Winsock 附錄。

[in] optname

要設定值的套接字選項。

[in] optval

緩衝區的指標，其中會提供所要求選項的值。

[in] optlen

optval 緩衝區的大小，以位元組為單位。

[out] lpErrno

錯誤碼的指標。

傳回值

如果沒有發生錯誤， LPWSPSetSockOpt 會傳回零。否則，會傳回 SOCKET_ERROR 值，而且 lpErrno 中提供特定的錯誤碼。

錯誤碼	意義
WSAENETDOWN	網路子系統失敗。
WSAEFAULT	optval 不在進程地址空間的有效部分，或 optlen 參數太小。
WSAEINPROGRESS	當回呼正在進行時，就會叫用函式。
WSAEINPROGRESS	封鎖 Windows Sockets 呼叫正在進行中，或者服務提供者仍在處理回呼函式。
WSAEINVAL	層級無效，或 optval 中的資訊無效。
WSAENETRESET	線上已中斷，因為持續活動偵測到作業正在進行時失敗。
WSAENOPROTOOPT	指定提供者的選項未知或不受支援。
WSAENOTCONN	設定 SO_KEEPALIVE 時，已重設連線。
WSAENOTSOCK	描述項不是套接字。

備註

LPWSPSetSockOpt 函式會以任何狀態設定與任何類型套接字相關聯的套接字選項目前值。雖然選項可以存在於多個通訊協定層級，但它們一律存在於最上層的套接字層級。選項會影響套接字作業，例如是否可以在套接字上傳送廣播訊息。

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

如需套接字選項的詳細資訊，請參閱 套接字選項。

level = SOL_SOCKET

值	類型	意義
SO_BROADCAST	BOOL	啟用套接字上廣播訊息的傳輸和接收。
SO_DEBUG	BOOL	記錄偵錯資訊。
SO_DONTLINGER	BOOL	保留的。
SO_DONTROUTE	BOOL	停用的路由：直接傳送至介面。設定此套接字選項會成功，但在AF_INET套接字上會被忽略;在具有 WSAENOPROTOOPT 的套接字AF_INET6失敗。 ATM 套接字不支援此選項， (會導致錯誤) 。
SO_GROUP_PRIORITY	int	保留的。
SO_KEEPALIVE	BOOL	傳送keep-alives。在 ATM 套接字上不支援 (會導致錯誤) 。
SO_LINGER	結構 linger	如果未傳送的數據存在，則會在關閉時閑置。
SO_OOBINLINE	BOOL	在一般數據流中接收 OOB 數據。
SO_RCVBUF	int	指定保留給接收的每一通訊端緩衝區總空間。這與SO_MAX_MSG_SIZE無關，而且不一定對應至 TCP 接收視窗的大小。
SO_REUSEADDR	BOOL	允許要繫結至已使用中位址的通訊端。 (請參閱 Bind.) 不適用於 ATM 套接字。
SO_SNDBUF	int	指定保留給傳送的每一通訊端緩衝區總空間。這與SO_MAX_MSG_SIZE無關，而且不一定對應至 TCP 傳送視窗的大小。
PVD_CONFIG	服務提供者相依	此物件會儲存與套接字相關聯之服務提供者的組態資訊。此數據結構的確切格式是服務提供者的特定格式。

以不支援的選項呼叫 LPWSPGetSockopt 會導致在 lpErrno 中傳回的 WSAENOPROTOOPT 錯誤碼。

SO_DEBUG

如果 Windows Sockets SPI 用戶端設定 了 SO_DEBUG 選項，則建議使用 Windows Sockets 服務提供者，但不需要提供輸出偵錯資訊。產生偵錯資訊和格式的機制超出此規格的範圍。

SO_GROUP_PRIORITY

保留的。

SO_KEEPALIVE

Windows Sockets SPI 用戶端可以藉由開啟 [SO_KEEPALIVE 套接字] 選項，要求 TCP/IP 提供者啟用在 TCP 連線上使用 keep-alive 封包。 Windows Sockets 提供者不需要支援使用 Keep-alives：如果是，精確語意是實作特定的，但應該符合 RFC 1122： 通訊層的需求第 4.2.3.6 節。 (此資源只能以英文提供。) 如果因為保持連線而中斷連線，則會將錯誤碼 WSAENETRESET 傳回套接字上任何進行中的呼叫，且任何後續呼叫都會失敗且 WSAENOTCONN 。

SO_LINGER

SO_LINGER控制在套接字上排入未傳送數據且執行 LPWSPCloseSocket 時所採取的動作。如需SO_LINGER設定影響 LPWSPCloseSocket 語意的說明，請參閱 LPWSPCloseSocket。 Windows Sockets SPI 用戶端會建立由 optval 參數指向的 LINGER 結構，並使用下列元素來設定所需的行為。

struct linger {
  u_short l_onoff;
  u_short l_linger;
}

若要啟用 SO_LINGER，Windows Sockets SPI 用戶端應該 將l_onoff 設定為非零值、 將l_linger 設定為零或所需的逾時，以秒為單位，然後呼叫 LPWSPSetSockOpt。若要啟用 SO_DONTLINGER，也就是停用 SO_LINGER，l_onoff 應設定為零，而且應該呼叫 LPWSPSetSockOpt 。請注意，不建議在非封鎖套接字上啟用非零逾時 SO_LINGER 。如需詳細資訊，請參閱 LPWSPCloseSocket。

啟用 SO_LINGER 也會停用 SO_DONTLINGER，反之亦然。請注意，如果 (停用SO_DONTLINGER，SO_LINGER 會在 ) 啟用，則不會指定逾時值。在此情況下，使用的逾時是相依的實作。如果先前已藉由啟用 SO_LINGER) 來建立套接字 (逾時，則服務提供者應該恢復這個逾時值。

SO_REUSEADDR

根據預設，套接字無法系結 (以取得詳細資訊，請參閱 LPWSPBind) 已使用中的本機位址。不過，有時候，建議您以這種方式重複使用位址。因為每個連線都是由本機和遠端位址的組合所唯一識別，所以只要遠端位址不同，將兩個套接字系結至相同的本機位址就沒有任何問題。若要通知 Windows Sockets 提供者，應該允許套接字上的 LPWSPBind 系結至已由另一個套接字使用的本機位址，Windows Sockets SPI 用戶端應該先設定 套接字的 SO_REUSEADDR 套接字選項，再發出 LPWSPBind。請注意，選項只會在 LPWSPBind 時解譯：因此不必要但無損害，若要在未繫結至現有位址的套接字上設定選項，並在 LPWSPBind 之後設定或重設選項對這個或任何其他套接字沒有任何作用。

SO_SNDBUF

當 Windows Sockets 實作支援 SO_RCVBUF 和 SO_SNDBUF 選項時，Windows Sockets SPI 用戶端可以要求不同的緩衝區大小， (較大或較小) 。即使服務提供者未提供要求的整個金額，呼叫仍可成功。 Windows Sockets SPI 用戶端必須使用相同的選項呼叫 LPWSPGetSockopt ，以確認實際提供的緩衝區大小。

PVD_CONFIG

此物件會儲存與套接字相關聯之服務提供者的組態資訊。此數據結構的確切格式是服務提供者特有的。

規格需求

需求	值
最低支援的用戶端	Windows 2000 Professional [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限桌面應用程式]
標頭	ws2spi.h