Функция WSALookupServiceBeginW (winsock2.h)

Статья
11/20/2024

Функция WSALookupServiceBegin инициирует клиентский запрос, ограниченный данными, содержащимися в структуре WSAQUERYSET. WSALookupServiceBegin возвращает только дескриптор, который следует использовать последующими вызовами WSALookupServiceNext, чтобы получить фактические результаты.

Синтаксис

INT WSAAPI WSALookupServiceBeginW(
  [in]  LPWSAQUERYSETW lpqsRestrictions,
  [in]  DWORD          dwControlFlags,
  [out] LPHANDLE       lphLookup
);

Параметры

[in] lpqsRestrictions

Указатель на критерии поиска. Дополнительные сведения см. в примечаниях.

[in] dwControlFlags

Набор флагов, который управляет глубиной поиска.

Поддерживаемые значения для параметра 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	Все доступные сведения о псевдониме должны быть возвращены в последующих вызовах WSALookupServiceNext, а каждый псевдоним, возвращенный, будет иметь набор флагов RESULT_IS_ALIAS.
LUP_RETURN_QUERY_STRING 0x0800	Извлекает строку запроса, используемую для запроса.
LUP_RETURN_ALL 0x0FF0	Набор флагов, извлекающих все значения LUP_RETURN_*.
LUP_FLUSHPREVIOUS 0x1000	Используется в качестве значения для параметра dwControlFlags в WSALookupServiceNext. Задание этого флага указывает поставщику отменить последний результирующий набор, который был слишком большим для указанного буфера, и перейти к следующему результирующем набору.
LUP_FLUSHCACHE 0x2000	Если поставщик кэширует сведения, игнорирует кэш и запрашивает само пространство имен.
LUP_RES_SERVICE 0x8000	Это указывает, находится ли основной ответ в удаленной или локальной части структуры CSADDR_INFO. Другая часть должна быть пригодной для использования в любом случае.

[out] lphLookup

Дескриптор, используемый при вызове WSALookupServiceNext, чтобы начать получение набора результатов.

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

Возвращаемое значение равно нулю, если операция выполнена успешно. В противном случае возвращается значение SOCKET_ERROR, а определенный номер ошибки можно получить путем вызова WSAGetLastError.

Код ошибки	Значение
WSA_NOT_ENOUGH_MEMORY	Для выполнения операции недостаточно памяти.
WSAEINVAL	Один или несколько параметров отсутствуют или недопустимы для этого поставщика.
WSANO_DATA	Имя было найдено в базе данных, но данные, соответствующие заданным ограничениям, не были найдены.
WSANOTINITIALISED	WS2_32.DLL не инициализирована. Приложение должно сначала вызвать WSAStartup перед вызовом функций сокетов Windows.
WSASERVICE_NOT_FOUND	Такая служба не известна. Служба не может находиться в указанном пространстве имен. Эта ошибка возвращается для запроса на обнаружение службы Bluetooth, если удаленные устройства Bluetooth не найдены.

Замечания

Параметр lpqsRestrictions указывает на буфер, содержащий структуру WSAQUERYSET. Как минимум, dwSize члена WSAQUERYSET необходимо задать длину буфера перед вызовом функции WSALookupServiceBegin. Приложения могут ограничить запрос, указав другие члены в WSAQUERYSET.

В большинстве случаев приложения, заинтересованные только в определенном транспортном протоколе, должны ограничивать запрос по семейству адресов и протоколу с помощью dwNumberOfProtocols и lpafpProtocols членов WSAQUERYSET, а не путем указания пространства имен в элементе dwNameSpace.

Сведения о поддерживаемых протоколах сетевого транспорта можно повторно просмотреть с помощью enumProtocols, WSAEnumProtocols, WSCEnumProtocolsили функции WSCEnumProtocols32.

Кроме того, можно ограничить запрос одним пространством имен. Например, запрос, который требует только результаты из DNS (не результатов из файла локальных узлов и других служб именования), задайте элементу dwNameSpace значение NS_DNS. Например, обнаружение устройства Bluetooth присвоит элементу dwNameSpace NS_BTH.

Приложения также могут ограничить запрос определенным поставщиком пространства имен, указав указатель на GUID поставщика в элементе lpNSProviderId.

Сведения о поставщиках пространств имен на локальном компьютере можно получить с помощью WSAEnumNameSpaceProviders, WSAEnumNameSpaceProvidersEx, WSCEnumNameSpaceProviders32или функции WSCEnumNameSpaceProvidersEx32.

Если LUP_CONTAINERS указан в вызове, следует избежать других значений ограничений. Если указаны какие-либо значения, поставщик служб имен может решить, поддерживает ли оно это ограничение по контейнерам. Если он не может, он должен вернуть ошибку.

У некоторых поставщиков служб имен могут быть другие средства поиска контейнеров. Например, контейнеры могут быть некоторых известных типов или набора известных типов, поэтому для их поиска можно создать ограничение запроса. Независимо от того, что другое означает, что поставщик служб имен имеет для размещения контейнеров, LUP_CONTAINERS и LUP_NOCONTAINERS имеет приоритет. Таким образом, если задано ограничение запроса, включающее контейнеры, указывающее LUP_NOCONTAINERS, не позволит возвращать элементы контейнера. Аналогичным образом, независимо от ограничения запроса, если LUP_CONTAINERS задано, возвращаются только контейнеры. Если пространство имен не поддерживает контейнеры и LUP_CONTAINERS указано, он должен просто возвращать WSANO_DATA.

Предпочтительный метод получения контейнеров в другом контейнере — это вызов:

dwStatus = WSALookupServiceBegin(
      lpqsRestrictions,
      LUP_CONTAINERS,
      lphLookup);

За этим вызовом следует необходимое количество вызовов WSALookupServiceNext. При этом будут возвращены все контейнеры, содержащиеся сразу в начальном контексте; то есть это не глубокий запрос. С помощью этого можно сопоставить структуру адресного пространства, пройдя по иерархии, возможно, перечислив содержимое выбранных контейнеров. Последующие использование WSALookupServiceBegin использовать контейнеры, возвращенные из предыдущего вызова.

Как упоминалось выше , структура WSAQUERYSET используется в качестве входного параметра для WSALookupBegin для определения запроса. В следующей таблице показано, как используется WSAQUERYSET для создания запроса. Если параметр помечается как (необязательно) можно указать указатель NULL, указывающий, что параметр не будет использоваться в качестве критерия поиска. Дополнительные сведения см. в разделе Query-Related Структуры данных.

Член WSAQUERYSET	Интерпретация запросов
dwSize	Необходимо задать значение sizeof(WSAQUERYSET). Это механизм управления версиями.
dwOutputFlags	Игнорируется для запросов.
lpszServiceInstanceName	(Необязательно) Ссылка на строку содержит имя службы. Семантика подстановочных знаков в строке не определена, но может поддерживаться определенными поставщиками пространств имен.
lpServiceClassId	(обязательно) GUID, соответствующий классу службы.
lpVersion	(Необязательно) Ссылается на нужный номер версии и предоставляет семантику сравнения версий (то есть версия должна соответствовать точно, или версия должна быть не меньше указанного значения).
lpszComment	Игнорируется для запросов.
dwNameSpace См. следующее примечание.	Идентификатор одного пространства имен, в котором необходимо ограничить поиск или NS_ALL включить все пространства имен.
lpNSProviderId	(Необязательно) Ссылается на GUID конкретного поставщика пространств имен и ограничивает запрос только этому поставщику.
lpszContext	(Необязательно) Указывает начальную точку запроса в иерархическом пространстве имен.
dwNumberOfProtocols	Размер массива ограничений протокола может быть равен нулю.
lpafpProtocols	(Необязательно) Ссылается на массив структуры AFPROTOCOLS. Будут возвращены только службы, использующие эти протоколы.
lpszQueryString	(Необязательно) Некоторые пространства имен (например, whois++) поддерживают обогащенные запросы, такие как SQL, содержащиеся в простой текстовой строке. Этот параметр используется для указания этой строки.
dwNumberOfCsAddrs	Игнорируется для запросов.
lpcsaBuffer	Игнорируется для запросов.
lpBlob	(Необязательно) Это указатель на сущность для конкретного поставщика.

Важные В большинстве случаев приложения, заинтересованные только в определенном транспортном протоколе, должны ограничивать запрос по семейству адресов и протоколу, а не по пространству имен. Это позволит приложению, которое должно находить службу TCP/IP, например, обрабатывать запрос всеми доступными пространствами имен, такими как файл локальных узлов, DNS и NIS.

Windows Phone 8: функция WSALookupServiceBeginW поддерживается для приложений Магазина Windows Phone в Windows Phone 8 и более поздних версиях.

Windows 8.1 и Windows Server 2012 R2: функция WSALookupServiceBeginW поддерживается для приложений Магазина Windows в Windows 8.1, Windows Server 2012 R2 и более поздних версий.

Заметка

Заголовок winsock2.h определяет WSALookupServiceBegin как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОДа. Сочетание использования псевдонима, нейтрального для кодирования, с кодом, не зависящим от кодирования, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в соглашениях о прототипах функций.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows 8.1, Windows Vista [классические приложения \| Приложения UWP]
минимальный поддерживаемый сервер	Windows Server 2003 [классические приложения \| Приложения UWP]
целевая платформа	Виндоус
заголовка	winsock2.h
библиотеки	Ws2_32.lib
DLL	Ws2_32.dll