Поделиться через


Функция обратного вызова 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

Значение типа , определяющее глубину поиска.

Значение Значение
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
Все доступные сведения о псевдонимах должны возвращаться в последовательных вызовах NSPLookupServiceNext, и для каждого возвращаемого псевдонима будет установлен флаг **RESULT_IS_ALIAS**.
LUP_RETURN_QUERY_STRING
0x0800
Извлекает строку запроса в виде **lpszQueryString**.
LUP_RETURN_ALL
0x0ff0
Извлекает сведения, включая имя, тип, версию, комментарий, адрес, большой двоичный объект, псевдонимы и строку запроса.
LUP_FLUSHCACHE
0x1000
Если у поставщика есть кэшированные сведения, игнорируйте кэш и запрашивайте само пространство имен.
LUP_FLUSHPREVIOUS
0x2000
Используется в качестве значения для параметра dwControlFlags в NSPLookupServiceNext. Установка этого флага указывает поставщику отменить последний результирующий набор, который был слишком большим для предоставленного буфера, и перейти к следующему результирующем набору.
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).

[out] lphLookup

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

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

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

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

Комментарии

Если в вызове указано 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

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

AFPROTOCOLS

NSPLookupServiceEnd

NSPLookupServiceNext

NSP_ROUTINE

WSAQUERYSET

WSASERVICECLASSINFO

WSASetLastError