Функция обратного вызова LPNSPSPLOOKUPSERVICEBEGIN (ws2spi.h)
Функция NSPLookupServiceBegin инициирует клиентский запрос поставщика службы имен, ограниченный сведениями, содержащимися в структуре WSAQUERYSET .
NSPLookupServiceBegin возвращает только дескриптор, который должен использоваться при последующих вызовах NSPLookupServiceNext для получения фактических результатов. Так как эту операцию нельзя отменить, ее необходимо реализовать для быстрого выполнения. Хотя можно инициировать сетевой запрос, эта функция не должна требовать ответа для успешного возврата.
Синтаксис
LPNSPLOOKUPSERVICEBEGIN Lpnsplookupservicebegin;
INT Lpnsplookupservicebegin(
[in] LPGUID lpProviderId,
[in] LPWSAQUERYSETW lpqsRestrictions,
[in] LPWSASERVICECLASSINFOW lpServiceClassInfo,
[in] DWORD dwControlFlags,
[out] LPHANDLE lphLookup
)
{...}
Параметры
[in] lpProviderId
Указатель на идентификатор поставщика услуг имени для запроса.
[in] lpqsRestrictions
Указатель на условия поиска. См. заметки.
[in] lpServiceClassInfo
Указатель на структуру WSASERVICECLASSINFO , содержащую сведения о схеме для службы.
[in] dwControlFlags
Значение типа , определяющее глубину поиска.
| Значение | Значение |
|---|---|
|
Запросы вниз по иерархии поставщика, а не только на первом уровне. |
|
Возвращает только контейнеры. |
|
Не возвращает контейнеры. |
|
По возможности возвращает результаты в порядке расстояния. Мера расстояния зависит от поставщика. |
|
Получает имя **lpszServiceInstanceName**. |
|
Извлекает тип **lpServiceClassId**. |
|
Получает версию как **lpVersion**. |
|
Извлекает комментарий как **lpszComment**. |
|
Извлекает адреса в формате **lpcsaBuffer**. |
|
Извлекает частные данные в виде **lpBlob**. |
|
Все доступные сведения о псевдонимах должны возвращаться в последовательных вызовах NSPLookupServiceNext, и для каждого возвращаемого псевдонима будет установлен флаг **RESULT_IS_ALIAS**. |
|
Извлекает строку запроса в виде **lpszQueryString**. |
|
Извлекает сведения, включая имя, тип, версию, комментарий, адрес, большой двоичный объект, псевдонимы и строку запроса. |
|
Если у поставщика есть кэшированные сведения, игнорируйте кэш и запрашивайте само пространство имен. |
|
Используется в качестве значения для параметра dwControlFlags в NSPLookupServiceNext. Установка этого флага указывает поставщику отменить последний результирующий набор, который был слишком большим для предоставленного буфера, и перейти к следующему результирующем набору. |
|
Указывает, что поставщик пространства имен должен включать не заслуживающие доверия результаты для имен. |
|
Указывает, находится ли основной ответ в удаленной или локальной части структуры CSADDR_INFO . Другая часть должна быть пригодной для использования в любом случае. Этот параметр применяется только к запросам экземпляра службы. |
|
Указывает, что поставщик пространства имен должен использовать безопасный запрос. Этот параметр применяется только к запросам имен. |
|
Указывает, что поставщик пространства имен должен возвращать только предпочтительные имена. |
|
Указывает, что поставщик пространства имен должен вернуть конфигурацию адреса. |
|
Указывает, что поставщик пространства имен должен возвращать два адреса. Этот параметр применяется только к сокетам с двумя режимами (сопоставленные адреса IPv6 и IPv4). |
[out] lphLookup
Указатель на дескриптор, используемый в последующих вызовах NSPLookupServiceNext для получения набора результатов.
Возвращаемое значение
Функция должна возвращать NO_ERROR (ноль), если подпрограмма завершается успешно. Он должен вернуть SOCKET_ERROR (–1), если подпрограмма завершается сбоем, и она должна задать соответствующий код ошибки с помощью WSASetLastError.
| Код ошибки | Значение |
|---|---|
| Недостаточно памяти для выполнения этой операции. | |
| Один или несколько параметров были недопустимыми или отсутствуют для этого поставщика. | |
| Операция не поддерживается. Эта ошибка возвращается, если поставщик пространства имен не реализует эту функцию. | |
| Имя найдено в базе данных, но оно не содержит правильных связанных данных, для которых разрешено. | |
| Служба неизвестна. Служба не найдена в указанном пространстве имен. |
Комментарии
Если в вызове указано LUP_CONTAINERS, избегайте других значений ограничений. Если они предоставляются, поставщик службы имен должен решить, может ли он поддерживать это ограничение для контейнеров. В противном случае он должен возвращать ошибку.
Некоторые поставщики служб имен могут иметь другие средства поиска контейнеров. Например, все контейнеры могут иметь известный тип или набор хорошо известных типов, поэтому для их поиска можно создать ограничение запросов. Независимо от того, какие другие средства имеет поставщик службы имен для поиска контейнеров, приоритет имеют LUP_CONTAINERS и LUP_NOCONTAINERS . Таким образом, если задано ограничение запроса, включающее контейнеры, указание LUP_NOCONTAINERS будет препятствовать возврату элементов контейнера. Аналогичным образом, независимо от ограничения запроса, если задано LUP_CONTAINERS , должны возвращаться только контейнеры. Если пространство имен не поддерживает контейнеры и указано LUP_CONTAINERS , оно должно вернуть WSANO_DATA.
Предпочтительным методом получения контейнеров в другом контейнере является вызов:
dwStatus = NSPLookupServiceBegin(
lpqsRestrictions,
LUP_CONTAINERS,
lphLookup);
за которым следует необходимое количество вызовов NSPLookupServiceNext . При этом будут возвращены все контейнеры, содержащиеся непосредственно в начальном контексте; то есть это не глубокий запрос. С помощью этого можно сопоставить структуру адресного пространства, проходя по иерархии, возможно, перечисляя содержимое выбранных контейнеров. Последующие методы NSPLookupServiceBegin используют контейнеры, возвращенные при предыдущем вызове.
Формирование запросов
Как уже упоминалось, структура WSAQUERYSET используется в качестве входного параметра для NSPLookupServiceBegin для квалификации запроса. В следующей таблице перечислены имена членов WSAQUERYSET и описано, как WSAQUERYSET используется для создания запроса. Если элемент помечен как (необязательный), можно указать пустой указатель, указывающий, что параметр не будет использоваться в качестве условий поиска. Дополнительные сведения см. в разделе Структуры данных, связанные с запросами.
| Имя члена WSAQUERYSET | Интерпретация запросов |
|---|---|
| **dwSize** | Будет задано значение sizeof(WSAQUERYSET). Это механизм управления версиями. |
| **dwOutputFlags** | Игнорируется для запросов. |
| **lpszServiceInstanceName** | Необязательный элемент. Указанная строка содержит имя службы. Семантика для подстановочных знаков в строке не определена, но может поддерживаться определенными поставщиками пространства имен. |
| **lpServiceClassId** | Обязательный. GUID, соответствующий классу службы. |
| **lpVersion** | Необязательный элемент. Ссылается на нужный номер версии и предоставляет семантику сравнения версий (то есть версия должна соответствовать точно, или версия должна быть не меньше указанного значения). |
| **lpszComment** | Игнорируется для запросов. |
| **dwNameSpace** | Идентификатор одного пространства имен, в котором необходимо ограничить поиск, или **NS_ALL** для включения всех пространств имен. |
| **lpNSProviderId** | Необязательный элемент. Ссылается на GUID определенного поставщика пространства имен и ограничивает запрос только этим поставщиком. |
| **lpszContext** | Необязательный элемент. Задает начальную точку запроса в иерархическом пространстве имен. |
| **dwNumberOfProtocols** | Размер (в байтах) количества записей в массиве ограничения протокола может быть равен нулю. |
| **lpafpProtocols** | Необязательный элемент. Ссылки на массив структур AFPROTOCOLS . Будут возвращены только службы, использующие эти протоколы. Допустимо, чтобы значение **AF_UNSPEC** отображалось как значение семейства протоколов, обозначающее подстановочный знак. Поставщики пространств имен могут предоставлять сведения о любой службе, которая использует соответствующий протокол, независимо от семейства адресов. |
| **lpszQueryString** | Необязательный элемент. Некоторые пространства имен (например, whois++) поддерживают форматированные SQL-запросы, содержащиеся в простой текстовой строке. Этот параметр используется для указания этой строки. |
| **dwNumberOfCsAddrs** | Игнорируется для запросов. |
| **lpcsaBuffer** | Игнорируется для запросов. |
| **lpBlob** | Необязательный элемент. Указатель на сущность поставщика. |
Требования
| Минимальная версия клиента | Windows 2000 Professional [только классические приложения] |
| Минимальная версия сервера | Windows 2000 Server [только классические приложения] |
| Целевая платформа | Windows |
| Header | ws2spi.h |
См. также раздел
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по