Функция 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

Указатель на строку Юникода, содержащую путь загрузки к исполняемому образу для приложения. Эта строка соблюдает обычные правила разрешения путей и может содержать строки внедренной среды (например , %SystemRoot%).

[in] PathLength

Длина параметра Path в символах. Эта длина не включает завершающее значение NULL.

[in] Extra

Указатель на строку Юникода, представляющую аргументы командной строки, используемые при запуске приложения, указанного в параметре Path . Параметр Extra используется для различения нескольких отдельных экземпляров приложения при запуске с согласованной командной строкой. Это позволяет поддерживать различные классификации приложений для разных экземпляров Svchost.exe или Rundll32.exe. Если требуется только параметр Path и аргументы командной строки не требуются для дальнейшего различения экземпляров приложения, то параметру Extra следует присвоить значение NULL.

[in] ExtraLength

Длина параметра Extra в символах. Эта длина не включает завершающее значение NULL.

[in] PermittedLspCategories

Значение DWORD категорий LSP, которые разрешены для всех экземпляров этого приложения. Приложение определяется сочетанием значений параметров 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 является глобальным для данного процесса и в процессе может размещаться несколько служб.

Если функция WSCSetApplicationCategory вызывается в одном и том же приложении (один и тот же полный путь, exe-имя и параметры) несколько раз, то категории объединяются в ORed. Например, если вы классифицировали "c:\foo.exe -param" с LSP_SYSTEM, а затем снова вызвали функцию WSCSetApplicationCategory с LSP_REDIRECTOR, результирующая запись для этого приложения будет содержать LSP_SYSTEM | LSP_REDIRECTOR. Такое поведение предназначено для поддержки одного исполняемого файла, в котором размещается несколько приложений в одном EXE-файле (например, системные службы Windows svchost.exe).

Оконные сокеты определяют удостоверение приложения и извлекают разрешенные категории LSP во время первого вызова WSAStartup. Это будет набор разрешенных категорий LSP на время работы экземпляра приложения. Последующие изменения разрешенных категорий LSP для данного удостоверения приложения не будут внесены до следующего экземпляра приложения. Разрешенные категории LSP не изменяются в течение всего времени существования экземпляра приложения.

Winsock 2 поддерживает многоуровневые протоколы. Многоуровневый протокол — это протокол, который реализует только функции обмена данными более высокого уровня, используя при этом базовый транспортный стек для фактического обмена данными с удаленной конечной точкой. Примером многоуровневого протокола или многоуровневого поставщика услуг может быть уровень безопасности, который добавляет протокол в процесс установки подключения для выполнения проверки подлинности и установления взаимно согласованной схемы шифрования. Для такого протокола безопасности обычно требуются службы базового надежного транспортного протокола, такого как TCP или SPX. Термин базовый протокол относится к такому протоколу, как TCP или SPX, который может осуществлять обмен данными с удаленной конечной точкой. Термин многоуровневый протокол используется для описания протокола, который не может стоять отдельно.

Во время инициализации LSP должен предоставлять указатели на ряд функций Winsock SPI. Эти функции будут вызываться во время обычной обработки слоем непосредственно над LSP (другой LSP или Ws2_32.dll).

LSP, реализующий устанавливаемую файловую систему (IFS), может выборочно предоставлять указатели на функции, которые реализуются сами по себе, или передавать указатели, предоставляемые слоем непосредственно под LSP. LSP, отличные от IFS, так как они предоставляют собственные дескрипторы, должны реализовывать все функции SPI Winsock. Это связано с тем, что для каждого SPI потребуется, чтобы LSP сопоставил все созданные им дескриптор сокета с дескриптором нижнего поставщика (другой LSP или базовый протокол).

Однако все LSP выполняют определенную работу, выполняя дополнительную обработку только для подмножества функций Winsock SPI.

Категории LSP можно определить на основе подмножества функций SPI, которые реализует LSP, и характера дополнительной обработки, выполняемой для каждой из этих функций.

Классифицируя LSP, а также классифицируя приложения, использующие сокеты Winsock, можно выборочно определить, следует ли участвовать LSP в данном процессе во время выполнения.

В Windows Vista и более поздних версиях LSP можно классифицировать в зависимости от того, как он взаимодействует с вызовами и данными сокетов Windows. Категория 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 может вызываться только пользователем, вошедшего в систему как член группы Администраторы. Если WSCSetApplicationCategory вызывается пользователем, не включаемым в группу Администраторы, вызов функции завершится ошибкой и WSANO_RECOVERY возвращается в параметре lpErrno . Эта функция также может завершиться сбоем из-за контроля учетных записей (UAC). Если приложение, содержащее эту функцию, выполняется пользователем, вошедшего в систему как участник группы администраторов, отличный от встроенного администратора, этот вызов завершится ошибкой, если приложение не было отмечено в файле манифеста параметром requestedExecutionLevel , для которого задано значение requireAdministrator. Если в приложении в Windows Vista или Windows Server 2008 отсутствует этот файл манифеста, пользователь, вошедший в систему как член группы администраторов, отличный от встроенного администратора, должен выполнить приложение в расширенной оболочке в качестве встроенного администратора (администратора запуска от имени администратора), чтобы эта функция была успешно выполнена.

Вызывающий объект должен выполнить любую установку файлов или конфигурацию, зависят от поставщика услуг.

Требования


Минимальная версия клиента	Windows Vista [только классические приложения]
Минимальная версия сервера	Windows Server 2008 [только классические приложения]
Целевая платформа	Windows
Header	ws2spi.h
Библиотека	Ws2_32.lib
DLL	Ws2_32.dll