WSCInstallProviderAndChains64_32函式 (ws2spi.h)

  • 發行項

WSCInstallProviderAndChains64_32函式會將指定的傳輸提供者及其特定通訊協定鏈結安裝在64位電腦上的32位和64位 Winsock 2 系統設定資料庫中。 此函式可確保通訊協定鏈結在傳輸提供者組態資訊的開頭排序，對 WSCWriteProviderOrder 不必要進行個別呼叫。

語法

int WSCInstallProviderAndChains64_32(
  [in]            LPGUID              lpProviderId,
  [in]            const LPWSTR        lpszProviderDllPath,
  [in]            const LPWSTR        lpszProviderDllPath32,
  [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 字串的指標，其中包含提供者 64 位 DLL 的載入路徑。 此字串會觀察路徑解析的一般規則，而且可以包含內嵌的環境字串 (，例如 %SystemRoot%) 。 當 Ws2_32.dll 之後必須代表應用程式載入提供者 DLL 時，就會展開這類環境字串。 展開任何內嵌的環境字串之後， Ws2_32.dll 會將產生的字串傳遞至 LoadLibrary 函式，以將提供者載入記憶體中。 如需詳細資訊，請參閱 LoadLibrary。

**注意** 如果 lpszProviderDllPath32 設定為 **NULL**， 則 lpszProviderDllPath 必須設定為 %windir%\system32\<dllname>。 如果沒有，呼叫會失敗，並傳回 WSAEINVAL 錯誤碼。
 

[in] lpszProviderDllPath32

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

**注意** 如果此參數設定為 **NULL**，則 64 位提供者必須存在於 %windir%\system32 資料夾中，而 32 位提供者必須位於 %windir%\syswow64 資料夾中。
 

[in] lpszLspName

Unicode 字串的指標，其中包含分層服務提供者的名稱， (LSP) 。

[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

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

傳回值

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

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

備註

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

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

WSCInstallProviderAndChains64_32 是64位版本的 WSCInstallProviderAndChains。 它會將提供者安裝在64位平臺上的32位和64位目錄。 這表示在64位平臺上，會維護兩個Winsock目錄，而且32位和64位進程都能夠載入隨此函式安裝的 LSP。

在 64 位電腦上，所有未特別針對 32 位 (設計的呼叫，例如，未在 “32” ) 中結束的所有函式都會在原生 64 位目錄上運作。 在 64 位電腦上執行的進程必須使用 WSCInstallProviderAndChains64_32 ，在 32 位目錄和 64 位目錄上運作，並保留相容性。 特定32位呼叫的定義和語意與其原生對應專案相同。

**注意** 在 64 位平臺上，沒有 **WSCInstallProviderAndChains** 函式只能在 64 位目錄中安裝。 在 64 位平臺上，必須同時安裝 32 位和 64 位版本的 LSP。 對於必須只安裝在 64 位 Winsock 目錄中的提供者，可以使用 WSCInstallProvider 函 式。
 

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

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

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

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

 

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

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

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

IFS 和非 IFS 提供者

IFS 提供者是傳回原生操作系統句柄的提供者。 這些句柄通常與核心模式通訊協定驅動程式相關聯。 例如，基底 TCP/IPv4、UDP/IPv4、TCP/IPv6 和 UDP/IPv6 是 IFS 提供者，因為這些專案會對應至核心模式元件。 IFS 句柄可用於 **ReadFile**、**WriteFile**和 **CancelIo** 函數調用中。 屬於 IFS 提供者的分層服務提供者只會傳回從較低提供者建立的套接字句柄， (這也必須是 IFS 提供者) 直接傳送至呼叫應用程式。 IFS LSP 無法攔截 Winsock 呼叫的完成通知。

非 IFS 提供者是使用 WPUCreateSocketHandle 建立中繼句柄，並將此句柄傳回給呼叫端。 這可讓非 IFS LSP 在呼叫應用程式之前攔截傳送和接收完成事件，以允許後續處理 (例如，將收到的數據區塊解密) 。 非 IFS 套接字句柄可用於 對 ReadFile 和 WriteFile 的呼叫，但無法與 CancelIo 搭配使用。 取消非 IFS 句柄上作業的唯一保證方法是關閉具有 closesocket 的套接字。

32 位和 64 位提供者 DLL 的路徑

lpszProviderDllPath 代表提供者 DLL 64 位版本的完整路徑。 此參數可以包含內嵌的環境字串 (，例如 %SystemRoot%) 。

lpszProviderDllPath32 代表提供者 DLL 32 位版本的完整路徑。 此參數可以包含內嵌的環境字串 (，例如 %SystemRoot%) 。

如果 lpszProviderDllPath32 為 NULL， 則 lpszProviderDllPath 是 32 和 64 位提供者的路徑。 例如，當64位電腦上的32位進程執行 (例如，當Winsock應用程式載入32位版本的LSP) 時，它會嘗試載入 lpszProviderDllPath 中指定的32位提供者。 如果 lpszProviderDllPath32 為 NULL，則 lpszProviderDllPath 參數必須設定為 %windir%\system32<dllname>。 如果不是這種情況，則呼叫會因為 WSAEINVAL 而失敗。 如果 lpszProviderDllPath 中的路徑是 %windir%\system32<dllname> 當 lpszProviderDllPath32 為 NULL 時，系統會使用文件系統重新導向器將呼叫重新導向 () 至 32 位 LSP 所在的 GetSystemWow64Directory 所傳回的目錄。 針對 Windows XP 64 位版本 Windows Server 2003 和 Windows Vista，此目錄為 %windir%\syswow64。

規格需求

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

另請參閱

LoadLibrary

傳輸組態和安裝

傳輸服務提供者

WPUCreateSocketHandle

WSAStartup

WSCEnumProtocols

WSCEnumProtocols32

WSCInstallProvider64_32

WSCInstallProviderAndChains

WSCWriteProviderOrder