WSCSetApplicationCategory 函式 (ws2spi.h)

發行項
08/28/2023

**注意** 分層服務提供者已被取代。從 Windows 8 和 Windows Server 2012 開始，請使用 Windows 篩選平台。

**WSCSetApplicationCategory** 函式會設定允許的分層服務提供者， (LSP) 與應用程式相關聯的類別。

語法

int WSCSetApplicationCategory(
  [in]  LPCWSTR Path,
  [in]  DWORD   PathLength,
  [in]  LPCWSTR Extra,
  [in]  DWORD   ExtraLength,
  [in]  DWORD   PermittedLspCategories,
  [out] DWORD   *pPrevPermLspCat,
  [out] LPINT   lpErrno
);

參數

[in] Path

Unicode 字串的指標，其中包含應用程式可執行檔映射的載入路徑。此字串會觀察路徑解析的一般規則，而且可以包含內嵌的環境字串 (，例如 %SystemRoot%) 。

[in] PathLength

Path參數的長度，以字元為單位。這個長度不包含終止 Null。

[in] Extra

Unicode 字串的指標，代表啟動 Path 參數中指定的應用程式時所使用的命令列引數。當以一致的命令列啟動時， Extra 參數可用來區分應用程式的多個不同實例。這是為了支援不同 Svchost.exe 或 Rundll32.exe 實例的不同應用程式分類。如果只需要 Path 參數，而且不需要任何命令列引數，才能進一步區分應用程式的實例，則 Extra 參數應該設定為 Null。

[in] ExtraLength

Extra參數的長度，以字元為單位。這個長度不包含終止 Null。

[in] PermittedLspCategories

此應用程式的所有實例都允許的 LSP 類別 DWORD 值。應用程式是由 Path 和 Extra 參數的值組合來識別。

[out] pPrevPermLspCat

指標，可接收此應用程式所有實例允許的先前一組允許的 LSP 類別。此參數是選擇性的，可以是 Null。

[out] lpErrno

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

傳回值

如果沒有發生錯誤， WSCSetApplicationCategory 會傳回 ERROR_SUCCESS (零) 。否則，它會傳回 SOCKET_ERROR，並在 lpErrno 參數中傳回特定的錯誤碼。

錯誤碼	意義
WSAEFAULT	一或多個引數不在使用者位址空間的有效部分。
WSAEINVAL	一或多個引數無效。
WSANO_RECOVERY	發生無法復原的錯誤。此錯誤會在數個情況下傳回：使用者缺少存取 Winsock 登錄所需的系統管理許可權，或開啟 Winsock 目錄專案或應用程式識別碼專案時發生失敗。

備註

WSCSetApplicationCategory 可用來設定與應用程式實例相關聯的 LSP 類別旗標。應用程式可以判斷應用程式內容中可接受的 LSP 行為。因此，透過指定允許的 LSP 類別，應用程式只能允許實作可接受行為的分層服務提供者載入。

當命令列用來區分裝載于相同可執行檔內之應用程式或服務的不同實例時，需要 Extra 參數。每個實例都可以有不同的應用程式分類需求。 Svchost.exe 和 Rundll32.exe 是兩個範例，其中需要命令列才能區分不同的進程實例。針對 SvcHost.exe，-k < svcinstance >參數會定義進程實例。

對於服務，使用服務名稱並不足夠，因為 Winsock Catalog 是指定進程的全域，而且進程可能會裝載數個服務。

如果在相同的應用程式上呼叫 WSCSetApplicationCategory 函式， (相同的 fullpath、EXE 名稱和參數多次) ，則類別會一起為 ORed。例如，如果您將「c:\foo.exe -param」分類為 LSP_SYSTEM，然後使用 LSP_REDIRECTOR再次呼叫 WSCSetApplicationCategory 函式，則此應用程式的結果專案包含LSP_SYSTEM |LSP_REDIRECTOR。此行為的設計目的是支援在單一 EXE (Windows 系統服務 svchost.exe 裝載多個應用程式的單一可執行檔，例如) 。

視窗通訊端會決定應用程式的身分識別，並在第一次呼叫 WSAStartup期間擷取允許的 LSP 類別。這會是應用程式實例期間允許的 LSP 類別集。在應用程式下一個實例之前，將不會挑選給定應用程式身分識別的允許 LSP 類別後續變更。允許的 LSP 類別在應用程式實例的存留期內不可變動。

Winsock 2 可容納分層通訊協定。分層通訊協定是只實作較高層級通訊函式的通訊協定，同時依賴基礎傳輸堆疊來與遠端端點實際交換資料。分層通訊協定或分層服務提供者的範例是一個安全性層，可將通訊協定新增至連線建立程式，以執行驗證，並建立相互同意的加密配置。這類安全性通訊協定通常需要基礎可靠傳輸通訊協定的服務，例如 TCP 或 SPX。基底通訊協定一詞是指 TCP 或 SPX 等通訊協定，其能夠與遠端端點執行資料通訊。分層通訊協定一詞是用來描述無法獨立通訊協定的通訊協定。

在 LSP 初始化期間，LSP 必須提供一些 Winsock SPI 函式的指標。這些函式會在正常處理期間由 LSP 正上方的層呼叫， (另一個 LSP 或 Ws2_32.dll) 。

實作可安裝檔案系統的 LSP (IFS) 可以選擇性地選擇提供本身實作之函式的指標，或傳回圖層直接在 LSP 下方提供的指標。非 IFS LSP，因為它們提供自己的控制碼，所以必須實作所有的 Winsock SPI 函式。這是因為每個 SPI 都需要 LSP 將它建立的所有通訊端控制碼對應至較低提供者的通訊端控制碼， (另一個 LSP 或基底通訊協定) 。

不過，所有 LSP 只要對 Winsock SPI 函式的子集執行額外的處理，即可執行其特定工作。

您可以根據 LSP 實作的 SPI 函式子集，以及針對每個函式執行的額外處理本質來定義 LSP 類別。

藉由分類 LSP，以及分類使用 Winsock 通訊端的應用程式，可以選擇性地判斷 LSP 是否應該在執行時間參與指定的進程。

在 Windows Vista 和更新版本上，LSP 可以根據它如何與 Windows Sockets 呼叫和資料互動來分類。 LSP 類別是 Winsock SPI 函式子集上可識別的行為群組。例如，HTTP 內容篩選會分類為數據偵測器， (LSP_INSPECTOR 類別目錄) 。 LSP_INSPECTOR類別會檢查 (，但不會將) 參數變更為資料傳輸 SPI 函式。應用程式可以查詢 LSP 的類別，並選擇不要根據 LSP 類別和應用程式允許的 LSP 類別集載入 LSP。

下表列出可分類 LSP 的類別。

LSP 類別	描述
LSP_CRYPTO_COMPRESS	LSP 是密碼編譯或資料壓縮提供者。
LSP_FIREWALL	LSP 是防火牆提供者。
LSP_LOCAL_CACHE	LSP 是本機快取提供者。
LSP_INBOUND_MODIFY	LSP 會修改輸入資料。
LSP_INSPECTOR	LSP 會檢查或篩選資料。
LSP_OUTBOUND_MODIFY	LSP 會修改輸出資料。
LSP_PROXY	LSP 可作為 Proxy，並重新導向封包。
LSP_REDIRECTOR	LSP 是網路重新導向器。
LSP_SYSTEM	LSP 可用於服務和系統進程。

LSP 可能屬於多個類別。例如，防火牆/安全性 LSP 可能同時屬於偵測器 (LSP_INSPECTOR) 和防火牆 (LSP_FIREWALL) 類別。

如果 LSP 沒有類別目錄設定，則會被視為在 [所有其他] 類別中。此 LSP 類別不會載入服務或系統進程 (例如 lsass、winlogon 和許多 svchost 進程) 。

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

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

規格需求


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