Функция 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 и могут быть комбинацией следующих параметров.

[out] lphLookup

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

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

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

Комментарии

Параметр 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 , указывающий, что параметр не будет использоваться в качестве условий поиска. Дополнительные сведения см. в разделе Структуры данных, связанные с запросами .

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

Требования

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

Bluetooth и WSALookupServiceBegin

EnumProtocols

WSAEnumNameSpaceProviders

WSAEnumNameSpaceProvidersEx

WSAEnumProtocols

WSALookupServiceEnd

WSALookupServiceNext

WSAQUERYSET

WSCEnumNameSpaceProviders32

WSCEnumNameSpaceProvidersEx32

WSCEnumProtocols

WSCEnumProtocols32