функция обратного вызова LPNSPV2LOOKUPSERVICEBEGIN (ws2spi.h)
Функция NSPv2LookupServiceBegin инициирует клиентский запрос поставщика службы пространства имен версии 2, ограниченного сведениями, содержащимися в структуре WSAQUERYSET2 .
Синтаксис
LPNSPV2LOOKUPSERVICEBEGIN Lpnspv2lookupservicebegin;
INT Lpnspv2lookupservicebegin(
[in] LPGUID lpProviderId,
[in] LPWSAQUERYSET2W lpqsRestrictions,
[in] DWORD dwControlFlags,
[out] LPVOID lpvClientSessionArg,
[out] LPHANDLE lphLookup
)
{...}
Параметры
[in] lpProviderId
Указатель на идентификатор для запрашиваемого поставщика службы пространства имен.
[in] lpqsRestrictions
Указатель на условия поиска. См. заметки.
[in] dwControlFlags
Набор флагов, влияющих на поиск. Этот параметр может быть сочетанием следующих значений, определенных в файле заголовка Winsock2.h .
| Значение | Значение |
|---|---|
|
Запросы вниз по иерархии поставщика, а не только на первом уровне. |
|
Возвращает только контейнеры. |
|
Не возвращает контейнеры. |
|
По возможности возвращает результаты в порядке расстояния. Мера расстояния зависит от поставщика. |
|
Получает имя **lpszServiceInstanceName**. |
|
Извлекает тип **lpServiceClassId**. |
|
Получает версию как **lpVersion**. |
|
Извлекает комментарий как **lpszComment**. |
|
Извлекает адреса в формате **lpcsaBuffer**. |
|
Извлекает частные данные в виде **lpBlob**. |
|
Все доступные сведения о псевдониме должны возвращаться в последовательных вызовах NSPv2LookupServiceNextEx, и для каждого возвращаемого псевдонима будет установлен флаг **RESULT_IS_ALIAS**. |
|
Извлекает строку запроса в виде **lpszQueryString**. |
|
Извлекает сведения, включая имя, тип, версию, комментарий, адрес, большой двоичный объект, псевдонимы и строку запроса. |
|
Если у поставщика есть кэшированные сведения, игнорируйте кэш и запрашивайте само пространство имен. |
|
Используется в качестве значения для параметра dwControlFlags в NSPv2LookupServiceNextEx. Установка этого флага указывает поставщику отменить последний результирующий набор, который был слишком большим для предоставленного буфера, и перейти к следующему результирующем набору. |
|
Указывает, что поставщик пространства имен должен включать не заслуживающие доверия результаты для имен. |
|
Указывает, находится ли основной ответ в удаленной или локальной части структуры CSADDR_INFO . Другая часть должна быть пригодной для использования в любом случае. Этот параметр применяется только к запросам экземпляра службы. |
|
Указывает, что поставщик пространства имен должен использовать безопасный запрос. Этот параметр применяется только к запросам имен. |
|
Указывает, что поставщик пространства имен должен возвращать только предпочтительные имена. |
|
Указывает, что поставщик пространства имен должен вернуть конфигурацию адреса. |
|
Указывает, что поставщик пространства имен должен возвращать два адреса. Этот параметр применяется только к сокетам с двумя режимами (сопоставленные адреса IPv6 и IPv4). |
|
Указывает, что поставщик пространства имен должен отключить автоматическое кодирование международных доменных имен.
Это значение поддерживается в Windows 8 и Windows Server 2012 |
[out] lpvClientSessionArg
Указатель на сеанс клиента.
[out] lphLookup
Указатель на дескриптор, используемый в последующих вызовах NSPv2LookupServiceNextEx для получения набора результатов.
Возвращаемое значение
Функция должна возвращать NO_ERROR (ноль), если подпрограмма завершается успешно. Он должен вернуть SOCKET_ERROR (т. е. 1), если подпрограмма завершается сбоем, и она должна задать соответствующий код ошибки с помощью WSASetLastError.
| Код ошибки | Значение |
|---|---|
| Один или несколько параметров были недопустимыми или отсутствуют для этого поставщика. | |
| Имя найдено в базе данных, но оно не содержит правильных связанных данных, для которых разрешено. | |
| Служба неизвестна. Служба не найдена в указанном пространстве имен. | |
| Недостаточно памяти для выполнения этой операции. |
Комментарии
Функция NSPv2LookupServiceBegin используется как часть архитектуры поставщика службы пространства имен версии 2 (NSPv2), доступной в Windows Vista и более поздних версиях.
В Windows Vista и Windows Server 2008 функция NSPv2LookupServiceBegin может использоваться только для операций с поставщиками NS_EMAIL пространств имен.
Функция NSPv2LookupServiceBegin возвращает только дескриптор, который должен использоваться последующими вызовами NSPv2LookupServiceNextEx для получения фактических результатов. Так как эту операцию нельзя отменить, ее необходимо реализовать для быстрого выполнения. Хотя можно инициировать сетевой запрос, эта функция не должна требовать ответа для успешного возврата.
Функция NSPv2Startup вызывается каждый раз, когда новый клиентский процесс начинает использовать поставщик пространства имен. Поставщики могут использовать аргумент сеанса клиента, на который указывает параметр ppvClientSessionArg , для хранения сведений об этом сеансе. Если для аргумента сеанса клиента в вызове функции NSPv2Startup было указано значение, то этот же аргумент сеанса клиента передается в параметре lpvClientSessionArg в функцию NSPv2LookupServiceBegin .
Если в вызове указано LUP_CONTAINERS, избегайте других значений ограничений. Если они предоставляются, поставщик службы имен должен решить, может ли он поддерживать это ограничение для контейнеров. В противном случае он должен вернуть ошибку.
Некоторые поставщики служб имен могут использовать другие способы поиска контейнеров. Например, все контейнеры могут иметь известный тип или набор хорошо известных типов, поэтому для их поиска можно создать ограничение запросов. Независимо от того, какие другие означают, что поставщик службы имен имеет для поиска контейнеров, LUP_CONTAINERS и LUP_NOCONTAINERS имеют приоритет. Таким образом, если задано ограничение запроса, включающее контейнеры, указание LUP_NOCONTAINERS предотвратит возврат элементов контейнера. Аналогичным образом, независимо от ограничения запроса, если задано LUP_CONTAINERS , должны возвращаться только контейнеры. Если пространство имен не поддерживает контейнеры и указано LUP_CONTAINERS , оно должно вернуть WSANO_DATA.
Предпочтительным методом получения контейнеров в другом контейнере является вызов:
dwStatus = NSPv2LookupServiceBegin(
lpProviderId,
lpqsRestrictions,
LUP_CONTAINERS,
lpClientSession,
lphLookup);
за которым следует необходимое количество вызовов NSPv2LookupServiceNextEx . При этом будут возвращены все контейнеры, содержащиеся непосредственно в начальном контексте; то есть это не глубокий запрос. С помощью этого можно сопоставить структуру адресного пространства путем обхода иерархии, например перечисления содержимого выбранных контейнеров. При последующих использовании NSPv2LookupServiceBegin используются контейнеры, возвращенные из предыдущего вызова.
Формирование запросов
Структура WSAQUERYSET2 используется в качестве входного параметра для NSPv2LookupServiceBegin для уточнения запроса. В следующей таблице перечислены имена членов **WSAQUERYSET2*** и описано, как **WSAQUERYSET2** используется для создания запроса. Члены, помеченные как необязательные и зависящие от требований поставщика NSPv2, могут быть предоставлены в виде указателя **NULL**, если они не будут использоваться поставщиком пространства имен в качестве условия поиска. Дополнительные сведения см. в разделе Структуры данных, связанные с запросами.| имя WSAQUERYSET2 участника | Интерпретация запроса |
|---|---|
| **dwSize** | Будет задано значение sizeof(WSAQUERYSET2). Это механизм управления версиями. |
| **lpszServiceInstanceName** | Строка, содержащая имя службы. Семантика для подстановочных знаков в строке не определена, но может поддерживаться определенными поставщиками пространства имен. Этот член является необязательным и зависит от требований поставщика службы NSPv2. |
| **lpVersion** | Требуемый номер версии, обеспечивающий семантику сравнения версий (то есть версия должна точно соответствовать или версия не должна быть меньше указанного значения). Этот член является необязательным и зависит от требований поставщика службы NSPv2. |
| **lpszComment** | Этот элемент игнорируется для запросов. |
| **dwNameSpace** | Идентификатор одного пространства имен, в котором необходимо ограничить поиск, или **NS_ALL** для включения всех пространств имен. |
| **lpNSProviderId** | GUID определенного поставщика пространства имен, который ограничивает запрос только этим поставщиком. Этот член является необязательным и зависит от требований поставщика службы NSPv2. |
| **lpszContext** | Начальная точка запроса в иерархическом пространстве имен. Этот член является необязательным и зависит от требований поставщика службы NSPv2. |
| **dwNumberOfProtocols** | Размер (в байтах) количества записей в массиве ограничений протокола. Этот элемент может быть равен нулю. |
| **lpafpProtocols** | Массив структур AFPROTOCOLS . Будут возвращены только службы, использующие эти протоколы. Допускается, чтобы значение **AF_UNSPEC** отображалось как значение семейства протоколов, обозначающее подстановочный знак. Поставщики пространств имен могут предоставлять сведения о любой службе, которая использует соответствующий протокол, независимо от семейства адресов. Этот член является необязательным и зависит от требований поставщика службы NSPv2. |
| **lpszQueryString** | Некоторые пространства имен (например, whois++) поддерживают форматированные запросы, подобные SQL, содержащиеся в простой текстовой строке. Этот параметр используется для указания этой строки. Этот член является необязательным и зависит от требований поставщика службы NSPv2. |
| **dwNumberOfCsAddrs** | Этот элемент игнорируется для запросов. |
| **lpcsaBuffer** | Этот элемент игнорируется для запросов. |
| **dwOutputFlags** | Этот элемент игнорируется для запросов. |
| **lpBlob** | Указатель на сущность конкретного поставщика. Этот член является необязательным и зависит от требований поставщика службы NSPv2. |
Требования
| Требование | Значение |
|---|---|
| Минимальная версия клиента | Windows Vista [только классические приложения] |
| Минимальная версия сервера | Windows Server 2008 [только классические приложения] |
| Целевая платформа | Windows |
| Header | ws2spi.h |