WSCInstallProvider 函式 (ws2spi.h)

  • 發行項
**注意** 分層服務提供者已被取代。 從 Windows 8 和 Windows Server 2012 開始，請使用 Windows 篩選平台。
 
**WSCInstallProvider** 函式會將指定的傳輸提供者安裝到系統組態資料庫中。

語法

int WSCInstallProvider(
  [in]  LPGUID                    lpProviderId,
  [in]  const WCHAR               *lpszProviderDllPath,
  [in]  const LPWSAPROTOCOL_INFOW lpProtocolInfoList,
  [in]  DWORD                     dwNumberOfEntries,
  [out] LPINT                     lpErrno
);

參數

[in] lpProviderId

提供者的全域唯一識別碼指標 (GUID) 。

[in] lpszProviderDllPath

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

[in] lpProtocolInfoList

WSAProtocol_Info結構的陣列指標。 每個結構都會定義提供者支援的通訊協定、位址系列和通訊端類型。

[in] dwNumberOfEntries

lpProtocolInfoList陣列中的專案數目。

[out] lpErrno

如果函式失敗，則為錯誤碼的指標。

傳回值

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

錯誤碼 意義
WSAEFAULT
 一或多個引數不在使用者位址空間的有效部分。
WSAEINVAL
 一或多個引數無效。
WSAENOBUFS
 記憶體無法配置給緩衝區。
WSANO_RECOVERY
 發生無法復原的錯誤。 此錯誤會在數個情況下傳回，包括下列情況：提供者已安裝、使用者缺少寫入 Winsock 登錄所需的系統管理許可權，或建立或安裝類別目錄專案時發生失敗。
WSASYSCALLFAILURE
 不應該失敗的系統呼叫失敗。
WSA_NOT_ENOUGH_MEMORY
 記憶體不足。 當記憶體不足而無法配置新的目錄專案時，就會傳回此錯誤。

備註

WSCInstallProvider 是用來安裝單一傳輸服務提供者。 此常式會為指定的提供者建立必要的通用 Windows Sockets 2 組態資訊。 它適用于基底通訊協定、分層通訊協定和通訊協定鏈結。 如果已安裝分層服務提供者，則應該使用 WSCInstallProviderAndChains 。 WSCInstallProviderAndChains 可以使用單一函式呼叫來安裝分層通訊協定和一或多個通訊協定鏈結。 若要使用 WSCInstallProvider 完成相同的工作，需要多個函式呼叫。

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

lpProtocolInfoList參數包含要安裝的通訊協定專案清單。 WSCInstallProvider的呼叫端負責設定適當的通訊協定專案。 lpProtocolInfoList參數不得為Null。

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

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

 

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

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

呼叫端必須執行任何檔案安裝或服務提供者特定的組態。

規格需求

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

另請參閱

WSAEnumProtocols

WSAProtocol_Info

WSAProviderConfigChange

WSAStartup

WSCDeinstallProvider

WSCEnumProtocols