WSCSetApplicationCategory 函数 (ws2spi.h)

**注意** 分层服务提供程序已弃用。 从 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 值。 应用程序由 PathExtra 参数的值组合标识。

[out] pPrevPermLspCat

一个指针,用于接收此应用程序的所有实例所允许的上一组允许的 LSP 类别。 此参数是可选的,可以为 NULL

[out] lpErrno

如果函数失败,则为指向错误代码的指针。

返回值

如果未发生错误, WSCSetApplicationCategory 将返回 ERROR_SUCCESS (零) 。 否则,它将返回 SOCKET_ERROR,并在 lpErrno 参数中返回特定的错误代码。

错误代码 含义
WSAEFAULT
一个或多个参数不在用户地址空间的有效部分中。
WSAEINVAL
一个或多个参数无效。
WSANO_RECOVERY
发生不可恢复的错误。 此错误在以下几种情况下返回:用户缺少访问 Winsock 注册表所需的管理权限,或者在打开 Winsock 目录条目或应用程序 ID 条目时发生故障。

备注

WSCSetApplicationCategory 用于设置与应用程序实例关联的 LSP 类别标志。 应用程序可以确定哪些 LSP 行为在应用程序的上下文中是可接受的。 因此,通过指定允许的 LSP 类别,应用程序只能允许加载那些实现可接受行为的分层服务提供程序。

当命令行用于区分托管在同一可执行文件中的应用程序或服务的不同实例时, 需要 Extra 参数。 每个实例可以有不同的应用程序分类需求。 Svchost.exe 和 Rundll32.exe 是两个示例,其中需要命令行来区分不同的进程实例。 对于 SvcHost.exe, -k <svcinstance> 开关定义进程实例。

对于服务,使用服务名称是不够的,因为 Winsock 目录对给定进程而言是全局性的,并且一个进程可以托管多个服务。

如果在同一应用程序上调用 WSCSetApplicationCategory 函数, (相同的完整路径、EXE 名称和参数多次) ,则类别是 ORed 在一起。 例如,如果使用 LSP_SYSTEM 对 “c:\foo.exe -param” 进行分类,然后使用 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 套接字调用和数据交互的方式对 LSP 进行分类。 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 充当代理并重定向数据包。
**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 上的应用程序缺少此清单文件,则作为管理员组成员(而不是内置管理员)登录的用户必须在增强的 shell 中执行应用程序,因为内置管理员 (RunAs 管理员) 才能使此功能成功。

任何文件安装或服务提供程序特定的配置必须由调用方执行。

要求

   
最低受支持的客户端 Windows Vista [仅限桌面应用]
最低受支持的服务器 Windows Server 2008 [仅限桌面应用]
目标平台 Windows
标头 ws2spi.h
Library Ws2_32.lib
DLL Ws2_32.dll

另请参阅

对分层服务提供程序和应用程序进行分类

WSAStartup

WSCGetApplicationCategory

WSCGetProviderInfo

WSCGetProviderInfo32

WSCSetProviderInfo

WSCSetProviderInfo32