функция WSCInstallProviderAndChains64_32 (ws2spi.h)
Функция WSCInstallProviderAndChains64_32 устанавливает указанный поставщик транспорта и его определенные цепочки протоколов в 32- и 64-разрядные базы данных конфигурации системы Winsock 2 на 64-разрядном компьютере. Эта функция гарантирует, что цепочки протоколов упорядочены в начале сведений о конфигурации поставщика транспорта, что делает ненужным отдельный вызов 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
Указатель на строку Юникода, содержащую путь загрузки к 64-разрядной библиотеке DLL поставщика. Эта строка соблюдает обычные правила разрешения пути и может содержать строки внедренной среды (например , %SystemRoot%). Такие строки среды расширяются, когда Ws2_32.dll должен впоследствии загрузить библиотеку DLL поставщика от имени приложения. После развертывания строк внедренной среды Ws2_32.dll передает полученную строку функции LoadLibrary , которая загружает поставщик в память. Дополнительные сведения см. в разделе LoadLibrary.
[in] lpszProviderDllPath32
Указатель на строку Юникода, содержащую полный путь к 32-разрядной библиотеке DLL поставщика. Эта строка соблюдает обычные правила разрешения пути и может содержать строки внедренной среды (например , %SystemRoot%). Такие строки среды расширяются, когда Ws2_32.dll впоследствии загружает библиотеку DLL поставщика от имени приложения. После развертывания строк внедренной среды Ws2_32.dll передает полученную строку в функцию LoadLibrary для загрузки поставщика в память. Дополнительные сведения см. в разделе LoadLibrary.
[in] lpszLspName
Указатель на строку Юникода, содержащую имя поставщика многоуровневых служб (LSP).
[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
Указатель на код ошибки, созданный вызовом, если функция завершается сбоем.
Возвращаемое значение
Если WSCInstallProviderAndChains64_32 выполнено успешно, возвращается ноль. В противном случае возвращается SOCKET_ERROR, а в параметре lpErrno возвращается определенный код ошибки.
| Код ошибки | Значение |
|---|---|
| Один или несколько аргументов не входят в допустимую часть адресного пространства пользователя. | |
| Один или несколько аргументов являются недопустимыми. Эта ошибка возвращается для следующих условий: параметр lpProviderId имеет значение **NULL**, параметр lpszProviderDllPath недопустим или длина пути слишком велика (**MAX_PATH** превышено), параметр lpszLspName недопустим или длина имени слишком велика (**WSAPROTOCOL_LEN** превышена), lpProtocolInfoList имеет значение non-*NULL**, а dwNumberOfEntries параметр равен нулю, повторяющийся идентификатор поставщика или многоуровневое имя поставщика услуг уже существуют в каталоге, или не удается найти совпадение для указанного протокола, семейства адресов и типа сокета. | |
|
У поставщика отсутствуют необходимые функциональные возможности. Поставщик, отличный от IFS, должен реализовывать все функции расширения Winsock 2 (AcceptEx, ConnectEx, DisconnectEx, TransmitFile, TransmitPackets и LPFN_WSARECVMSG (WSARecvMsg)). |
| Установка поставщика уже выполняется. | |
| Память не может быть выделена для буферов. | |
| Произошла неустранимая ошибка. Эта ошибка возвращается при нескольких условиях, включая следующее: поставщик уже установлен, параметр lpProtocolInfoList был **NULL** и базовый поставщик не найден, достигнута максимальная длина цепочки протоколов (**MAX_PROTOCOL_CHAIN**), у пользователя отсутствуют права администратора, необходимые для записи в реестр Winsock, или произошел сбой при создании или установке записи каталога. | |
| Системный вызов, который никогда не должен завершать ошибку, завершился сбоем. |
Комментарии
WSCInstallProviderAndChains64_32 — это расширенная версия базовой функции WSCInstallProvider64_32 , используемой для установки одного поставщика транспортных услуг. Если устанавливается многоуровневый поставщик служб, следует использовать WSCInstallProviderAndChains64_32 . WSCInstallProviderAndChains64_32 можно установить многоуровневый протокол и одну или несколько цепочек протоколов с одним вызовом функции. Для выполнения одной и той же работы с помощью WSCInstallProvider64_32 потребуется несколько вызовов функций.
Winsock 2 поддерживает многоуровневые протоколы. Многоуровневый протокол — это протокол, который реализует только функции связи более высокого уровня, полагаясь на базовый транспортный стек для фактического обмена данными с удаленной конечной точкой. Примером многоуровневого протокола может быть уровень безопасности, который добавляет протокол в процесс установления соединения для выполнения проверки подлинности и создания взаимно согласованной схемы шифрования. Для такого протокола безопасности обычно требуются службы базового надежного транспортного протокола, например TCP или SPX. Термин базовый протокол относится к такому протоколу, как TCP или SPX, который способен осуществлять обмен данными с удаленной конечной точкой. Термин многоуровневый протокол используется для описания протокола, который не может стоять отдельно. Затем цепочка протоколов будет определена как один или несколько многоуровневых протоколов, нанизанных вместе и привязанных к базовому протоколу. Базовый протокол содержит элемент ChainLenструктуры WSAProtocol_Info , для которого задано значение BASE_PROTOCOL которое определено как 1. Многоуровневый протокол содержит элемент ChainLenструктуры WSAPROTOCOL_INFO , для которого задано значение LAYERED_PROTOCOL которое равно нулю. Цепочка протоколов содержит элемент ChainLenструктуры WSAPROTOCOL_INFO , равный больше 1.
WSCInstallProviderAndChains64_32 — это 64-разрядная версия WSCInstallProviderAndChains. Поставщик устанавливается в 32-разрядный и 64-разрядный каталоги на 64-разрядных платформах. Это означает, что на 64-разрядных платформах поддерживаются два каталога Winsock и что как 32-разрядные, так и 64-разрядные процессы могут загружать LSP, установленный с этой функцией.
На 64-разрядном компьютере все вызовы, не предназначенные специально для 32-разрядной версии (например, все функции, которые не заканчиваются на "32"), работают в собственном 64-разрядном каталоге. Процессы, выполняемые на 64-разрядном компьютере, должны использовать WSCInstallProviderAndChains64_32 для работы как с 32-разрядным каталогом, так и с 64-разрядным каталогом, сохраняя совместимость. Определения и семантика конкретных 32-разрядных вызовов совпадают с собственными аналогами.
Если для lpProtocolInfoList задано значение NULL, эта функция создает цепочки протоколов, в которых поставщик накладывается на базовый протокол для каждого уникального типа протокола, определенного в семействе адресов, типе сокета и протоколе. Это исключает создание любых недоступных повторяющихся записей поставщика.
Если lpProtocolInfoList имеет значение, отличное от NULL , эта функция создает цепочки протоколов, получая самую верхнюю запись в сведениях о конфигурации, которая соответствует {семейство адресов, тип сокета, протокол} кортежа из каждого элемента в предоставленном массиве. Опять же, учитывается только кортеж {семейство адресов, тип сокета, протокол} ; все остальные элементы и дубликаты игнорируются.
После успешного завершения этого вызова все последующие вызовы WSAEnumProtocols, WSCEnumProtocols или WSCEnumProtocols32 будут возвращать только что созданные записи цепочки протоколов. Имейте в виду, что в средах Windows только экземпляры Ws_32.dll , созданные путем вызова WSAStartup после успешного завершения WSCInstallProviderAndChains64_32 будут включать новые записи при возврате WSAEnumProtocols, WSCEnumProtocols и WSCEnumProtocols32 .
При успешном выполнении WSCInstallProviderAndChains64_32 попытается предупредить все заинтересованные приложения, зарегистрированные для уведомления об изменении, вызвав WSAProviderConfigChange.
Функция WSCInstallProviderAndChains64_32 может вызываться только пользователем, вошедшего в систему как член группы "Администраторы". Если WSCInstallProviderAndChains64_32 вызывается пользователем, который не является членом группы Администраторы, вызов функции завершится ошибкой и WSANO_RECOVERY возвращается в параметре lpErrno . Для компьютеров под управлением Windows Vista или Windows Server 2008 эта функция также может завершиться сбоем из-за контроля учетных записей пользователей (UAC). Если приложение, содержащее эту функцию, выполняется пользователем, вошедшего в систему как член группы администраторов, отличный от встроенного администратора, этот вызов завершится ошибкой, если приложение не было отмечено в файле манифеста с параметром requestedExecutionLevel , для которого задано значение requireAdministrator. Если в приложении в Windows Vista или Windows Server 2008 отсутствует этот файл манифеста, пользователь, вошедший в систему как член группы администраторов, отличный от встроенного администратора, должен выполнить приложение в расширенной оболочке в качестве встроенного администратора (администратора запуска от имени администратора), чтобы эта функция была успешно выполнена.
Любая установка файла или настройка для конкретного поставщика должна выполняться вызывающим приложением.
Поставщики IFS и не-IFS
Поставщик IFS — это поставщик, который возвращает собственные дескрипторы операционной системы. Обычно эти дескрипторы связаны с драйверами протокола режима ядра. Например, базовые поставщики TCP/IPv4, UDP/IPv4, TCP/IPv6 и UDP/IPv6 являются поставщиками IFS, так как эти записи соответствуют компоненту режима ядра. Дескрипторы IFS можно использовать в вызовах функций **ReadFile**, **WriteFile**и **CancelIo**. Многоуровневый поставщик служб, являющийся поставщиком IFS, просто возвращает дескриптор сокета, созданный из нижнего поставщика (который также должен быть поставщиком IFS), непосредственно вызывающей приложению. Поставщик LSP IFS не может перехватывать уведомления о завершении для вызовов Winsock.Поставщик, отличный от IFS, создает промежуточный дескриптор с WPUCreateSocketHandle и возвращает этот дескриптор вызывающей. Это позволяет LSP, отличному от IFS, перехватывать события отправки и получения событий завершения перед вызывающими приложениями, чтобы разрешить постобработку (например, расшифровку полученного фрагмента данных). Дескриптор сокета, отличный от IFS, можно использовать в вызовах ReadFile и WriteFile, но нельзя использовать с CancelIo. Единственным гарантированным методом отмены операции с дескриптором, отличном от IFS, является закрытие сокета с помощью closesocket.
Пути для 32-разрядных и 64-разрядных библиотек DLL поставщика
lpszProviderDllPath представляет полный путь к 64-разрядной версии библиотеки DLL поставщика. Этот параметр может содержать строки внедренной среды (например , %SystemRoot%).lpszProviderDllPath32 представляет полный путь к 32-разрядной версии библиотеки DLL поставщика. Этот параметр может содержать строки внедренной среды (например , %SystemRoot%).
Если lpszProviderDllPath32 имеет значение NULL, то lpszProviderDllPath — это путь для 32- и 64-разрядных поставщиков. Когда выполняется 32-разрядный процесс на 64-разрядном компьютере (например, когда приложение Winsock загружает 32-разрядную версию LSP), он пытается загрузить 32-разрядный поставщик, указанный в lpszProviderDllPath. Если lpszProviderDllPath32 имеет значение NULL, то параметру lpszProviderDllPath необходимо задать значение %windir%\system32< dllname>. Если это не так, вызов завершается ошибкой WSAEINVAL. Если путь в lpszProviderDllPath имеет значение %windir%\system32< dllname> , если lpszProviderDllPath32 имеет значение NULL, вызов будет перенаправлен (с помощью перенаправителя файловой системы) в каталог, возвращенный GetSystemWow64Directory , где должен находиться 32-разрядный LSP. Для 64-разрядной версии Windows XP, Windows Server 2003 и Windows Vista этот каталог — %windir%\syswow64.
Требования
| Минимальная версия клиента | Windows Vista [только классические приложения] |
| Минимальная версия сервера | Windows Server 2008 [только классические приложения] |
| Целевая платформа | Windows |
| Header | ws2spi.h |
| Библиотека | Ws2_32.lib |
| DLL | Ws2_32.dll |