Функция WSCInstallProviderAndChains (ws2spi.h)
Примечание
Многоуровневые поставщики служб являются устаревшими. Начиная с Windows 8 и Windows Server 2012, используйте платформу фильтрации Windows. Функция WSCInstallProviderAndChains устанавливает указанный 32-разрядный поставщик транспорта, а также определенные цепочки протоколов в базу данных конфигурации системы Winsock 2 на 32-разрядном компьютере. Эта функция гарантирует, что цепочки протоколов упорядочены в начале сведений о конфигурации поставщика транспорта, гарантируя, что отдельный вызов WSCWriteProviderOrder не требуется.
Синтаксис
int WSCInstallProviderAndChains(
[in] LPGUID lpProviderId,
[in] const LPWSTR lpszProviderDllPath,
[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
Указатель на строку Юникода, содержащую путь загрузки к библиотеке DLL поставщика. Эта строка соблюдает обычные правила разрешения пути и может содержать строки внедренной среды (например, %SystemRoot%. Такие строки среды расширяются всякий раз , когдаWs2_32.dll впоследствии загружает библиотеку DLL поставщика от имени приложения. После развертывания строк внедренной среды Ws2_32.dll передает полученную строку в функцию LoadLibrary для загрузки поставщика в память. Дополнительные сведения см. в разделе LoadLibrary.
[in] lpszLspName
Указатель на строку Юникода, содержащую имя поставщика сокета.
[in] dwServiceFlags
Флаги службы для типа создаваемой фиктивной записи каталога.
Фиктивная запись — это структура WSAProtocol_Info с элементом ChainLen , равным 0. Фактическая запись каталога LSP будет ссылаться на идентификатор этой фиктивной записи в ее члене ProtocolChain .
Возможные флаги, которые можно задать для этого параметра:
[in] lpProtocolInfoList
Указатель на массив WSAProtocol_Info структур. Каждая структура определяет протокол, семейство адресов и тип сокета, поддерживаемые поставщиком. Проверяемые элементы структуры WSAPROTOCOL_INFO : iProtocol, iAddressFamily и iSocketType.
[in] dwNumberOfEntries
Количество записей в массиве lpProtocolInfoList .
[out, optional] lpdwCatalogEntryId
Получает указатель на только что установленную "фиктивную" запись для поставщика транспорта в базе данных конфигурации системы Winsock 2. Этот идентификатор используется для установки записей каталога для LSP.
[out] lpErrno
Указатель, который получает код ошибки, созданный вызовом, если функция завершается сбоем.
Возвращаемое значение
If
WSCInstallProviderAndChains успешно возвращает ноль. В противном случае возвращается SOCKET_ERROR, а в параметре lpErrno возвращается определенный код ошибки.
| Код ошибки | Значение |
|---|---|
| Один или несколько аргументов не входят в допустимую часть адресного пространства пользователя. | |
| Один или несколько аргументов являются недопустимыми. Эта ошибка возвращается для следующих условий: параметр lpProviderId имеет значение **NULL**, параметр lpszProviderDllPath недопустим или длина пути слишком велика (**MAX_PATH** превышено), параметр lpszLspName недопустим или длина имени слишком велика (**WSAPROTOCOL_LEN** превышена), lpProtocolInfoList имеет значение non-*NULL**, а dwNumberOfEntries параметр равен нулю, повторяющийся идентификатор поставщика или многоуровневое имя поставщика услуг уже существуют в каталоге, или не удается найти совпадение для указанного протокола, семейства адресов и типа сокета. | |
| Установка поставщика уже выполняется. | |
| У поставщика отсутствуют необходимые функциональные возможности. | |
| Память не может быть выделена для буферов. | |
| Произошла неустранимая ошибка. Эта ошибка возвращается при нескольких условиях, включая следующее: поставщик уже установлен, параметр lpProtocolInfoList был **NULL** и базовый поставщик не найден, достигнута максимальная длина цепочки протоколов (**MAX_PROTOCOL_CHAIN**), у пользователя отсутствуют права администратора, необходимые для записи в реестр Winsock, или произошел сбой при создании или установке записи каталога. | |
| Системный вызов, который никогда не должен завершать ошибку, завершился сбоем. |
Комментарии
WSCInstallProviderAndChains — это расширенная версия базовой функции WSCInstallProvider , используемой для установки одного поставщика транспортных служб. Если устанавливается поставщик многоуровневой службы, следует использовать WSCInstallProviderAndChains . WSCInstallProviderAndChains может установить многоуровневый протокол и одну или несколько цепочек протоколов с одним вызовом функции. Для выполнения той же работы с помощью WSCInstallProvider потребуется несколько вызовов функций.
Winsock 2 поддерживает многоуровневые протоколы. Многоуровневый протокол — это протокол, который реализует только функции связи более высокого уровня, полагаясь на базовый транспортный стек для фактического обмена данными с удаленной конечной точкой. Примером многоуровневого протокола может быть уровень безопасности, который добавляет протокол в процесс установления соединения для выполнения проверки подлинности и создания взаимно согласованной схемы шифрования. Для такого протокола безопасности обычно требуются службы базового надежного транспортного протокола, например TCP или SPX. Термин базовый протокол относится к такому протоколу, как TCP или SPX, который способен осуществлять обмен данными с удаленной конечной точкой. Термин многоуровневый протокол используется для описания протокола, который не может стоять отдельно. Затем цепочка протоколов будет определена как один или несколько многоуровневых протоколов, нанизанных вместе и привязанных к базовому протоколу. Базовый протокол содержит элемент ChainLenструктуры WSAProtocol_Info , для которого задано значение BASE_PROTOCOL которое определено как 1. Многоуровневый протокол содержит элемент ChainLenструктуры WSAPROTOCOL_INFO , для которого задано значение LAYERED_PROTOCOL которое равно нулю. Цепочка протоколов содержит элемент ChainLenструктуры WSAPROTOCOL_INFO , равный больше 1.
Если для lpProtocolInfoList задано значение NULL, эта функция создает цепочки протоколов, в которых поставщик накладывается на базовый протокол для каждого уникального типа протокола, определенного в семействе адресов, типе сокета и протоколе. Это исключает создание любых недоступных повторяющихся записей поставщика.
Если lpProtocolInfoList имеет значение, отличное от NULL , эта функция создает цепочки протоколов, получая самую верхнюю запись в сведениях о конфигурации, которая соответствует семейству адресов, типу сокета и протоколу из каждого элемента в предоставленном массиве. Опять же, учитываются только семейство адресов, тип сокета и протокол; все остальные элементы и дубликаты игнорируются.
После успешного завершения этого вызова все последующие вызовы WSAEnumProtocols или WSCEnumProtocols будут возвращать только что созданные записи цепочки протоколов. Имейте в виду, что в средах Windows только экземпляры Ws_32.dll , созданные путем вызова WSAStartup после успешного завершения WSCInstallProviderAndChains , будут включать новые записи при возврате WSAEnumProtocols и WSCEnumProtocols .
При успешном выполнении WSCInstallProviderAndChains попытается предупредить все заинтересованные приложения, зарегистрированные для уведомления об изменении, вызвав WSAProviderConfigChange.
Функция WSCInstallProviderAndChains может вызываться только пользователем, вошедшим в систему как член группы администраторов. Если WSCInstallProviderAndChains вызывается пользователем, не членом группы Администраторы, вызов функции завершится ошибкой и WSANO_RECOVERY возвращается в параметре lpErrno . Для компьютеров под управлением Windows Vista или Windows Server 2008 эта функция также может завершиться сбоем из-за контроля учетных записей пользователей (UAC). Если приложение, содержащее эту функцию, выполняется пользователем, вошедшего в систему как член группы администраторов, отличный от встроенного администратора, этот вызов завершится ошибкой, если приложение не было отмечено в файле манифеста с параметром requestedExecutionLevel , для которого задано значение requireAdministrator. Если в приложении в Windows Vista или Windows Server 2008 отсутствует этот файл манифеста, пользователь, вошедший в систему как член группы администраторов, отличный от встроенного администратора, должен выполнить приложение в расширенной оболочке в качестве встроенного администратора (администратора запуска от имени администратора), чтобы эта функция была успешно выполнена.
Любая установка файла или настройка для конкретного поставщика должна выполняться вызывающим приложением.
Требования
| Требование | Значение |
|---|---|
| Минимальная версия клиента | Windows Vista [только классические приложения] |
| Минимальная версия сервера | Windows Server 2008 [только классические приложения] |
| Целевая платформа | Windows |
| Header | ws2spi.h |
| Библиотека | Ws2_32.lib |
| DLL | Ws2_32.dll |