Функция WSALookupServiceBeginA (winsock2.h)
Функция WSALookupServiceBegin инициирует клиентский запрос, ограниченный сведениями, содержащимися в структуре WSAQUERYSET . WSALookupServiceBegin возвращает только дескриптор, который должен использоваться последующими вызовами WSALookupServiceNext для получения фактических результатов.
Синтаксис
INT WSAAPI WSALookupServiceBeginA(
[in] LPWSAQUERYSETA lpqsRestrictions,
[in] DWORD dwControlFlags,
[out] LPHANDLE lphLookup
);
Параметры
[in] lpqsRestrictions
Указатель на условия поиска. Дополнительные сведения см. в разделе Примечания.
[in] dwControlFlags
Набор флагов, которые управляют глубиной поиска.
Поддерживаемые значения для параметра dwControlFlags определяются в файле заголовка Winsock2.h и могут быть комбинацией следующих параметров.
| Flag | Значение |
|---|---|
|
Запросы глубокие, а не только на первом уровне. |
|
Возвращает только контейнеры. |
|
Не возвращайте контейнеры. |
|
По возможности возвращает результаты в порядке расстояния. Мера расстояния зависит от поставщика. |
|
Извлекает имя lpszServiceInstanceName. |
|
Извлекает тип lpServiceClassId. |
|
Получает версию как lpVersion. |
|
Извлекает комментарий как lpszComment. |
|
Извлекает адреса в виде lpcsaBuffer. |
|
Извлекает частные данные как lpBlob. |
|
Все доступные сведения о псевдониме должны возвращаться в последовательных вызовах WSALookupServiceNext, и для каждого возвращаемого псевдонима будет установлен флаг RESULT_IS_ALIAS. |
|
Извлекает строку запроса, используемую для запроса. |
|
Набор флагов, который извлекает все значения LUP_RETURN_*. |
|
Используется в качестве значения для параметра dwControlFlags в WSALookupServiceNext. Установка этого флага указывает поставщику отменить последний результирующий набор, который был слишком велик для указанного буфера, и перейти к следующему результирующем набору. |
|
Если поставщик кэширования данных, игнорирует кэш и запрашивает само пространство имен. |
|
Это указывает, находится ли основной ответ в удаленной или локальной части структуры CSADDR_INFO . Другая часть должна быть пригодной для использования в любом случае. |
[out] lphLookup
Дескриптор, используемый при вызове WSALookupServiceNext , чтобы приступить к получению набора результатов.
Возвращаемое значение
Возвращаемое значение равно нулю, если операция прошла успешно. В противном случае возвращается значение SOCKET_ERROR, а конкретный номер ошибки можно получить, вызвав WSAGetLastError.
| Код ошибки | Значение |
|---|---|
| Недостаточно памяти для выполнения операции. | |
| Один или несколько параметров отсутствуют или недопустимы для этого поставщика. | |
| Имя найдено в базе данных, но данные, соответствующие заданным ограничениям, не найдены. | |
| WS2_32.DLL не инициализирована. Приложение должно сначала вызвать WSAStartup , прежде чем вызывать какие-либо функции windows Sockets. | |
|
Такая служба не известна. Служба не найдена в указанном пространстве имен.
Эта ошибка возвращается для запроса на обнаружение службы Bluetooth, если удаленные устройства Bluetooth не найдены. |
Комментарии
Параметр lpqsRestrictions указывает на буфер, содержащий структуру WSAQUERYSET . Как минимум, перед вызовом функции WSALookupServiceBeginчлену dwSizeWSAQUERYSET необходимо задать длину буфера. Приложения могут ограничить запрос, указав другие члены в WSAQUERYSET.
В большинстве случаев приложения, заинтересованные только в определенном транспортном протоколе, должны ограничивать свой запрос по семейству адресов и протоколу, используя члены dwNumberOfProtocols и lpafpProtocolsWSAQUERYSET , а не путем указания пространства имен в элементе dwNameSpace .
Сведения о поддерживаемых протоколах сетевого транспорта можно получить с помощью функции EnumProtocols, WSAEnumProtocols, WSCEnumProtocols или WSCEnumProtocols32 .
Можно также ограничить запрос одним пространством имен. Например, запрос, который требует только результаты из DNS (но не из локального файла hosts и других служб именования), задает для элемента 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 , указывающий, что параметр не будет использоваться в качестве условий поиска. Дополнительные сведения см. в разделе Структуры данных, связанные с запросами .
| Член 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 | (Необязательно) Это указатель на сущность поставщика. |
Windows 8.1 и Windows Server 2012 R2. Функция WSALookupServiceBeginW поддерживается для приложений Магазина Windows на Windows 8.1, Windows Server 2012 R2 и более поздних версий.
Примечание
Заголовок winsock2.h определяет WSALookupServiceBegin как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора UNICODE. Сочетание использования псевдонима, не зависящий от кодировки, с кодом, не зависящим от кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.
Требования
| Требование | Значение |
|---|---|
| Минимальная версия клиента | Windows 8.1, Windows Vista [классические приложения | Приложения UWP] |
| Минимальная версия сервера | Windows Server 2003 [классические приложения | Приложения UWP] |
| Целевая платформа | Windows |
| Header | winsock2.h |
| Библиотека | Ws2_32.lib |
| DLL | Ws2_32.dll |
См. также раздел
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по