функция обратного вызова LPNSPV2LOOKUPSERVICENEXTEX (ws2spi.h)

Статья
08/28/2023

Функция NSPv2LookupServiceNextEx вызывается после получения дескриптора из предыдущего вызова NSPv2LookupServiceBegin для получения запрошенных сведений от поставщика службы пространства имен версии 2.

Синтаксис

LPNSPV2LOOKUPSERVICENEXTEX Lpnspv2lookupservicenextex;

void Lpnspv2lookupservicenextex(
  [in]      HANDLE hAsyncCall,
  [in]      HANDLE hLookup,
  [in]      DWORD dwControlFlags,
  [in, out] LPDWORD lpdwBufferLength,
  [out]     LPWSAQUERYSET2W lpqsResults
)
{...}

Параметры

[in] hAsyncCall

Дескриптор, возвращенный при предыдущем вызове NSPv2LookupServiceBegin , используемый для асинхронных вызовов.

[in] hLookup

Дескриптор, возвращенный при предыдущем вызове NSPv2LookupServiceBegin.

[in] dwControlFlags

Флаги, используемые для управления следующей операцией. В настоящее время только LUP_FLUSHPREVIOUS определяется как средство обработки слишком большого результирующих наборов. Если приложение не может предоставить достаточно большой буфер, настройка LUP_FLUSHPREVIOUS указывает поставщику отменить последний результирующий набор, который был слишком большим, и перейти к следующему набору для этого вызова.

[in, out] lpdwBufferLength

Размер входных данных в байтах, который содержится в буфере, на который указывает lpqsResults. В выходных данных, если функция завершается сбоем и ошибка WSAEFAULT, она содержит минимальный размер в байтах для передачи lpqsResults для получения записи.

[out] lpqsResults

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

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

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

Код ошибки	Значение
WSA_E_CANCELLED	Во время обработки этого вызова был выполнен вызов NSPv2LookupServiceEnd . Звонок отменен. Данные в буфере lpqsResults неопределенны. В сокетах Windows 2 конфликтующие коды ошибок определяются для WSAECANCELLED (10103) и WSA_E_CANCELLED (10111). Код ошибки WSAECANCELLED будет удален в следующей версии и останется только WSA_E_CANCELLED. Поставщики пространств имен должны использовать код ошибки WSA_E_CANCELLED для обеспечения совместимости с максимально широким диапазоном приложений.
WSA_E_NO_MORE	Больше нет доступных данных. В сокетах Windows 2 конфликтующие коды ошибок определяются для WSAENOMORE (10102) и WSA_E_NO_MORE (10110). Код ошибки WSAENOMORE будет удален в следующей версии и останется только WSA_E_NO_MORE. Поставщики пространств имен должны использовать код ошибки WSA_E_NO_MORE для обеспечения совместимости с максимально широким диапазоном приложений.
WSAEFAULT	Буфер lpqsResults был слишком мал, чтобы содержать набор WSAQUERYSET .
WSAEINVAL	Один или несколько параметров недопустимы или отсутствуют для этого поставщика.
WSA_INVALID_HANDLE	Указанный дескриптор подстановки недопустим.
WSANO_DATA	Имя найдено в базе данных, но данные, соответствующие заданным ограничениям, не найдены.
WSASERVICE_NOT_FOUND	Служба неизвестна. Служба не найдена в указанном пространстве имен.
WSA_NOT_ENOUGH_MEMORY	Недостаточно памяти для выполнения этой операции.

Поставщик передает структуру WSAQUERYSET2 в буфере lpqsResults . Клиент должен вызывать функцию NSPv2LookupServiceNextEx , пока не вернет WSA_E_NOMORE, указывая, что возвращены все WSAQUERYSET2 структуры.

DwControlFlags, указанные в этой функции, и те, которые указаны во время NSPv2LookupServiceBegin, обрабатываются как "ограничения" для целей сочетания. Ограничения объединяются между ограничениями во время NSPv2LookupServiceBegin и во время NSPv2LookupServiceNextEx . Таким образом, флаги NSPv2LookupServiceNextEx никогда не могут увеличить объем возвращаемых данных сверх того, что было запрошено в NSPv2LookupServiceBegin, хотя указание большего или меньшего количества флагов не является ошибкой. Флаги, указанные в заданном NSPv2LookupServiceNextEx , применяются только к данному вызову.

DwControlFlagsLUP_FLUSHPREVIOUS и LUP_RES_SERVICE являются исключениями из правила объединенных ограничений (так как они являются флагами поведения, а не флагами ограничений). Если в NSPv2LookupServiceNextEx используется какой-либо из флагов, они имеют определенный эффект независимо от настройки одних и того же флага в NSPv2LookupServiceBegin.

Например, если LUP_RETURN_VERSION указан в NSPv2LookupServiceBegin, поставщик услуг извлекает записи, включая версию. Если LUP_RETURN_VERSION не указан в NSPv2LookupServiceNextEx, возвращаемые сведения не включают версию, даже если она была доступна. Ошибка не возникает.

Кроме того, например, если LUP_RETURN_BLOB не указан в NSPv2LookupServiceBegin, но указан в NSPv2LookupServiceNextEx, возвращаемые сведения не включают частные данные. Ошибка не возникает.

Обычно функция NSPv2LookupServiceNextEx вызывается как минимум дважды. Первый раз для получения размера буфера, необходимого для получения WSAQUERYSET2 , на который указывает параметр lpqsResults , а второй — для получения фактического результирующий набор запроса. При первом вызове поставщик NSPv2 должен вернуть размер, необходимый для результатов WSAQUERYSET2 .

Структура WSAQUERYSET2 , на которую указывает возвращаемый параметр lpqsResults , полезна только в том же контексте процесса, так как несколько элементов в структуре WSAQUERYSET2 содержат указатели на фактические возвращаемые данные. Если результат запроса необходимо передать в другой процесс (например, с помощью RPC), необходимо будет сериализовать и маршалировать данные, возвращаемые в структуре WSAQUERYSET2 , на которую указывает параметр lpqsResults , включая данные, на которые указывают члены структуры WSAQUERYSET2 . Данные необходимо сериализовать в форме, которую можно передавать через границы процесса. Простой передачи копии структуры WSAQUERYSET2 недостаточно, так как будут передаваться только указатели на данные, а фактические данные будут недоступны для других процессов.

Результаты запроса

В следующей таблице перечислены WSAQUERYSET2 и описано, как результаты запроса представлены в структуре **WSAQUERYSET2**. Дополнительные сведения см. в разделе Структуры данных, связанные с запросами.

имя члена WSAQUERYSET2	Интерпретация результатов
dwSize	Размер структуры WSAQUERYSET2 в байтах. Используется в качестве механизма управления версиями.
lpszServiceInstanceName	Строка, содержащая имя службы.
lpVersion	Ссылается на номер версии конкретного экземпляра службы.
lpszComment	Строка комментария, предоставляемая экземпляром службы. Этот член является необязательным и зависит от требований поставщика служб NSPv2.
dwNameSpace	Идентификатор пространства имен, в котором было найдено имя или экземпляр службы.
lpNSProviderId	Конкретный поставщик пространства имен, который предоставил этот результат запроса.
lpszContext	Точка контекста в иерархическом пространстве имен, в котором находится служба.
dwNumberOfProtocols	Этот член не определен для результатов.
lpafpProtocols	Этот член не определен для результатов. Все необходимые сведения о протоколе содержатся в CSADDR_INFO структурах.
lpszQueryString	Если dwControlFlags включает LUP_RETURN_QUERY_STRING, этот член возвращает необпараченный остаток lpszServiceInstanceName, указанный в исходном запросе. Например, в пространстве имен, которое идентифицирует службы по иерархическим именам, указывающим имя узла и путь к файлу в этом узле, возвращаемым адресом может быть адрес узла, а непараметризованный остаток может быть путем к файлу. Если lpszServiceInstanceName полностью проанализировано и используется LUP_RETURN_QUERY_STRING, этот член имеет значение NULL или указывает на строку нулевой длины.
dwNumberOfCsAddrs	Количество элементов в массиве CSADDR_INFO структур.
lpcsaBuffer	Указатель на массив CSADDR_INFO структур с одним полным транспортным адресом, содержащимся в каждом элементе.
dwOutputFlags	Флаг RESULT_IS_ALIAS указывает, что это псевдоним результата.
lpBlob	Указатель на сущность конкретного поставщика. Этот член является необязательным и зависит от требований поставщика службы NSPv2.

Требования


Минимальная версия клиента	Windows Vista [только классические приложения]
Минимальная версия сервера	Windows Server 2008 [только классические приложения]
Целевая платформа	Windows
Header	ws2spi.h

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

CSADDR_INFO

NSPV2_ROUTINE

NSPv2Cleanup

NSPv2ClientSessionRundown

NSPv2LookupServiceBegin

NSPv2LookupServiceEnd

имя члена WSAQUERYSET2	Интерпретация результатов
dwSize	Размер структуры WSAQUERYSET2 в байтах. Используется в качестве механизма управления версиями.
lpszServiceInstanceName	Строка, содержащая имя службы.
lpVersion	Ссылается на номер версии конкретного экземпляра службы.
lpszComment	Строка комментария, предоставляемая экземпляром службы. Этот член является необязательным и зависит от требований поставщика служб NSPv2.
dwNameSpace	Идентификатор пространства имен, в котором было найдено имя или экземпляр службы.
lpNSProviderId	Конкретный поставщик пространства имен, который предоставил этот результат запроса.
lpszContext	Точка контекста в иерархическом пространстве имен, в котором находится служба.
dwNumberOfProtocols	Этот член не определен для результатов.
lpafpProtocols	Этот член не определен для результатов. Все необходимые сведения о протоколе содержатся в CSADDR_INFO структурах.
lpszQueryString	Если dwControlFlags включает LUP_RETURN_QUERY_STRING, этот член возвращает необпараченный остаток lpszServiceInstanceName, указанный в исходном запросе. Например, в пространстве имен, которое идентифицирует службы по иерархическим именам, указывающим имя узла и путь к файлу в этом узле, возвращаемым адресом может быть адрес узла, а непараметризованный остаток может быть путем к файлу. Если lpszServiceInstanceName полностью проанализировано и используется LUP_RETURN_QUERY_STRING, этот член имеет значение NULL или указывает на строку нулевой длины.
dwNumberOfCsAddrs	Количество элементов в массиве CSADDR_INFO структур.
lpcsaBuffer	Указатель на массив CSADDR_INFO структур с одним полным транспортным адресом, содержащимся в каждом элементе.
dwOutputFlags	Флаг RESULT_IS_ALIAS указывает, что это псевдоним результата.
lpBlob	Указатель на сущность конкретного поставщика. Этот член является необязательным и зависит от требований поставщика службы NSPv2.

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