共用方式為

WSCInstallProviderAndChains 函式 (ws2spi.h)

  • 發行項

注意

分層服務提供者已被取代。 從 Windows 8 和 Windows Server 2012 開始，請使用 Windows 篩選平臺。 WSCInstallProviderAndChains 函式會將指定的 32 位傳輸提供者及其特定通訊協定鏈結安裝到 32 位電腦上的 Winsock 2 系統組態資料庫。 此函式可確保通訊協定鏈結在傳輸提供者組態資訊的開頭排序，確保不需要個別呼叫 WriteProviderOrder 。

語法

int WSCInstallProviderAndChains(
  [in]            LPGUID              lpProviderId,
  [in]            const LPWSTR        lpszProviderDllPath,
  [in]            const LPWSTR        lpszLspName,
  [in]            DWORD               dwServiceFlags,
  [in]            LPWSAPROTOCOL_INFOW lpProtocolInfoList,
  [in]            DWORD               dwNumberOfEntries,
  [out, optional] LPDWORD             lpdwCatalogEntryId,
  [out]           LPINT               lpErrno
);

參數

[in] lpProviderId

提供者特定全域唯一標識符的指標， (GUID) 。

[in] lpszProviderDllPath

Unicode 字串的指標，其中包含提供者 DLL 的載入路徑。 此字串會觀察路徑解析的一般規則，而且可以包含內嵌的環境字串 (%SystemRoot%，例如) 。 每當 Ws2_32.dll 代表應用程式載入提供者 DLL 時，就會展開這類環境字串。 展開任何內嵌的環境字串之後， Ws2_32.dll 將產生的字串傳遞至 LoadLibrary 函式，以將提供者載入記憶體中。 如需詳細資訊，請參閱 LoadLibrary。

[in] lpszLspName

Unicode 字串的指標，其中包含套接字提供者的名稱。

[in] dwServiceFlags

要建立之「虛擬」目錄項目類型的服務旗標。

虛擬專案是 一個WSAProtocol_Info 結構， 而 ChainLen 成員設定為 0。 實際的 LSP 目錄項目會參考其 ProtocolChain 成員中此虛擬專案的標識碼。

您可以為此參數設定的可能旗標如下：

值 意義
XP1_IFS_HANDLES
 目錄專案適用於可安裝文件系統 (IFS) LSP，其會傳回 IFS 特定的套接字句柄。 這些句柄會直接傳回給呼叫的應用程式。 IFS LSP 無法攔截 Winsock 呼叫完成，而且不需要實作或可供使用的所有 Winsock 函式。

[in] lpProtocolInfoList

WSAProtocol_Info 結構的陣列指標。 每個結構都會定義提供者支持的通訊協定、位址系列和套接字類型。 所檢查 WSAPROTOCOL_INFO 結構的成員包括 iProtocol、 iAddressFamily 和 iSocketType。

[in] dwNumberOfEntries

lpProtocolInfoList 陣列中的項目數。

[out, optional] lpdwCatalogEntryId

接收 Winsock 2 系統組態資料庫中傳輸提供者新安裝的「虛擬」項目指標。 此標識碼是用來安裝 LSP 的目錄專案。

[out] lpErrno

如果函式失敗，則為接收呼叫所產生的錯誤碼的指標。

傳回值

如果
WSCInstallProviderAndChains 成功，它會傳回零。 否則，它會 傳回SOCKET_ERROR，並在 lpErrno 參數中傳回特定的錯誤碼。

錯誤碼 意義
WSAEFAULT
 一或多個自變數不在用戶位址空間的有效部分中。
WSAEINVAL
 一或多個引數無效。 下列條件會傳回此錯誤：lpProviderId 參數為 **NULL**， lpszProviderDllPath 參數無效，或路徑長度太大， (**MAX_PATH** 超過) ，lpszLspName 參數無效，或名稱長度太大， (**WSAPROTOCOL_LEN** 超過) ，lpProtocolInfoList 會設定為非**NULL**，而 dwNumberOfEntries參數為零、目錄中已經存在重複的提供者標識碼或分層服務提供者名稱，或找不到指定的通訊協定、位址系列和套接字類型的相符專案。
WSAEINPROGRESS
 提供者安裝正在進行中。
WSAEINVALIDPROCTABLE
 提供者缺少必要的功能。
WSAENOBUFS
 記憶體無法配置給緩衝區。
WSANO_RECOVERY
 發生無法復原的錯誤。 此錯誤會在下列幾種情況下傳回：提供者已安裝、 lpProtocolInfoList 參數為 **NULL**，而且找不到基底提供者、達到通訊協定鏈結長度上限 (**MAX_PROTOCOL_CHAIN**) 、使用者缺少寫入 Winsock 登錄所需的系統管理許可權，或在建立或安裝類別目錄專案時發生失敗。
WSASYSCALLFAILURE
 應該永遠不會失敗的系統呼叫失敗。

備註

WSCInstallProviderAndChains 是用來安裝單一傳輸服務提供者的基本 WSCInstallProvider 函 式增強版本。 如果已安裝分層服務提供者，則應該使用 WSCInstallProviderAndChains 。 WSCInstallProviderAndChains 可以使用單一函數調用來安裝分層通訊協定和一或多個通訊協定鏈結。 若要使用 WSCInstallProvider 完成相同的工作，需要多個函數調用。

Winsock 2 可容納分層通訊協定。 分層通訊協定是只實作較高層級通訊功能的通訊功能，同時依賴基礎傳輸堆疊來與遠端端點實際交換數據。 分層通訊協定的範例是一個安全性層，可將通訊協定新增至聯機建立程式，以執行驗證，並建立相互同意的加密配置。 這類安全性通訊協定通常需要基礎可靠傳輸通訊協議的服務，例如 TCP 或 SPX。 基底通訊協定一詞是指通訊協定，例如 TCP 或 SPX，其能夠與遠端端端點執行數據通訊。 分層通訊協定一詞是用來描述無法獨立通訊協定的通訊協定。 接著，通訊協定鏈結會定義為一或多個分層通訊協定，並依基底通訊協定錨定。 基底通訊協定的 ChainLen 成員 WSAProtocol_Info結構設定 為 1 BASE_PROTOCOL 。 分層通訊協定的 ChainLen 成員 WSAPROTOCOL_INFO 結構設定為 LAYERED_PROTOCOL 定義為零。 通訊協議鏈結將 WSAPROTOCOL_INFO 結構的 ChainLen 成員設定為大於 1。

如果 lpProtocolInfoList 設定為 NULL，此函式會建立通訊協定鏈結，其中提供者會針對位址系列、套接字類型和通訊協定所定義的每個唯一通訊協定類型，分層在基底通訊協定上。 這可消除建立任何無法存取的重複提供者專案。

如果 lpProtocolInfoList 設定為非 NULL 值，則此函式會藉由從所提供陣列中的每個元素取得符合位址系列、套接字類型和通訊協定的組態資訊中的最上層專案，以建立通訊協定鏈結。 同樣地，只會考慮位址系列、套接字類型和通訊協定;會忽略所有其他成員和重複專案。

成功完成此呼叫之後，任何後續對 WSAEnumProtocols 或 WSCEnumProtocols 的呼叫都會傳回新建立的通訊協定鏈結專案。 請注意，在 Windows 環境中，只有在 WSCInstallProviderAndChains 成功完成之後呼叫 WSAStartup 所建立的Ws_32.dll 實例才會在 WSAEnumProtocols 和 WSCEnumProtocols 傳回時包含新的專案。

注意WSAEnumProtocols 函式不會列舉分層通訊協議專案，而 WSCEnumProtocols 則不會列舉。

 

成功時， WSCInstallProviderAndChains 會呼叫 WSAProviderConfigChange，嘗試警示已註冊通知變更的所有相關應用程式。

WSCInstallProviderAndChains 函式只能由以 Administrators 群組成員身分登入的使用者呼叫。 如果 WSCInstallProviderAndChains 是由不是 Administrators 群組成員的使用者呼叫，則函數調用將會失敗，並在 lpErrno 參數中傳回WSANO_RECOVERY。 對於執行 Windows Vista 或 Windows Server 2008 的電腦，此函式也可能因為使用者帳戶控制 (UAC) 而失敗。 如果包含此函式的應用程式是由以內建系統管理員以外的 Administrators 群組成員身分登入的使用者所執行，除非應用程式已在指令清單檔案中標示 為 requestedExecutionLevel 設定為 requireAdministrator，否則此呼叫將會失敗。 如果 Windows Vista 或 Windows Server 2008 上的應用程式缺少此指令清單檔，則以系統管理員群組成員的身分登入的用戶必須接著在增強殼層中執行應用程式，因為內建的 Administrator (RunAs 系統管理員) ，此函式才能成功。

呼叫端應用程式必須執行任何檔案安裝或提供者特定的組態。

規格需求

需求 值
最低支援的用戶端 Windows Vista [僅限傳統型應用程式]
最低支援的伺服器 Windows Server 2008 [僅限傳統型應用程式]
目標平台 Windows
標頭 ws2spi.h
程式庫 Ws2_32.lib
Dll Ws2_32.dll

另請參閱

LoadLibrary

傳輸組態和安裝

傳輸服務提供者

WSAEnumProtocols

WSAProviderConfigChange

WSAStartup

WSCEnumProtocols

WSCInstallProvider

WSCWriteProviderOrder