функция обратного вызова LPNSPV2LOOKUPSERVICEBEGIN (ws2spi.h)

Статья
08/28/2023

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

Значение	Значение
LUP_DEEP 0x0001	Запросы вниз по иерархии поставщика, а не только на первом уровне.
LUP_CONTAINERS 0x0002	Возвращает только контейнеры.
LUP_NOCONTAINERS 0x0004	Не возвращает контейнеры.
LUP_NEAREST 0x0008	По возможности возвращает результаты в порядке расстояния. Мера расстояния зависит от поставщика.
LUP_RETURN_NAME 0x0010	Получает имя lpszServiceInstanceName.
LUP_RETURN_TYPE 0x0020	Извлекает тип lpServiceClassId.
LUP_RETURN_VERSION 0x0040	Получает версию как lpVersion.
LUP_RETURN_COMMENT 0x0080	Извлекает комментарий как lpszComment.
LUP_RETURN_ADDR 0x0100	Извлекает адреса в формате lpcsaBuffer.
LUP_RETURN_BLOB 0x0200	Извлекает частные данные в виде lpBlob.
LUP_RETURN_ALIASES 0x0400	Все доступные сведения о псевдониме должны возвращаться в последовательных вызовах NSPv2LookupServiceNextEx, и для каждого возвращаемого псевдонима будет установлен флаг RESULT_IS_ALIAS.
LUP_RETURN_QUERY_STRING 0x0800	Извлекает строку запроса в виде lpszQueryString.
LUP_RETURN_ALL 0x0ff0	Извлекает сведения, включая имя, тип, версию, комментарий, адрес, большой двоичный объект, псевдонимы и строку запроса.
LUP_FLUSHCACHE 0x1000	Если у поставщика есть кэшированные сведения, игнорируйте кэш и запрашивайте само пространство имен.
LUP_FLUSHPREVIOUS 0x2000	Используется в качестве значения для параметра dwControlFlags в NSPv2LookupServiceNextEx. Установка этого флага указывает поставщику отменить последний результирующий набор, который был слишком большим для предоставленного буфера, и перейти к следующему результирующем набору.
LUP_NON_AUTHORITATIVE 0x4000	Указывает, что поставщик пространства имен должен включать не заслуживающие доверия результаты для имен.
LUP_RES_RESERVICE 0x8000	Указывает, находится ли основной ответ в удаленной или локальной части структуры CSADDR_INFO . Другая часть должна быть пригодной для использования в любом случае. Этот параметр применяется только к запросам экземпляра службы.
LUP_SECURE 0x8000	Указывает, что поставщик пространства имен должен использовать безопасный запрос. Этот параметр применяется только к запросам имен.
LUP_RETURN_PREFERRED_NAMES 0x10000	Указывает, что поставщик пространства имен должен возвращать только предпочтительные имена.
LUP_ADDRCONFIG 0x100000	Указывает, что поставщик пространства имен должен вернуть конфигурацию адреса.
LUP_DUAL_ADDR 0x200000	Указывает, что поставщик пространства имен должен возвращать два адреса. Этот параметр применяется только к сокетам с двумя режимами (сопоставленные адреса IPv6 и IPv4).
LUP_DISABLE_IDN_ENCODING 0x800000	Указывает, что поставщик пространства имен должен отключить автоматическое кодирование международных доменных имен. Это значение поддерживается в Windows 8 и Windows Server 2012

[out] lpvClientSessionArg

Указатель на сеанс клиента.

[out] lphLookup

Указатель на дескриптор, используемый в последующих вызовах NSPv2LookupServiceNextEx для получения набора результатов.

Возвращаемое значение

Функция должна возвращать NO_ERROR (ноль), если подпрограмма завершается успешно. Он должен вернуть SOCKET_ERROR (т. е. 1), если подпрограмма завершается сбоем, и она должна задать соответствующий код ошибки с помощью WSASetLastError.

Код ошибки	Значение
WSAEINVAL	Один или несколько параметров были недопустимыми или отсутствуют для этого поставщика.
WSANO_DATA	Имя найдено в базе данных, но оно не содержит правильных связанных данных, для которых разрешено.
WSASERVICE_NOT_FOUND	Служба неизвестна. Служба не найдена в указанном пространстве имен.
WSA_NOT_ENOUGH_MEMORY	Недостаточно памяти для выполнения этой операции.

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

См. также раздел

AFPROTOCOLS

NSPV2_ROUTINE

NSPv2Cleanup

NSPv2ClientSessionRundown

NSPv2LookupServiceEnd

NSPv2LookupServiceNextEx

имя 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.

Share via