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

Статья
07/16/2024

Функция 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	Для выполнения этой операции недостаточно памяти.

Замечания

Функция NSPv2LookupServiceNextEx используется как часть архитектуры поставщика услуг пространства имен версии 2 (NSPv2), доступной в Windows Vista и более поздних версиях.

В Windows Vista и Windows Server 2008 функция NSPv2LookupServiceNextEx может использоваться только для операций с поставщиками пространств имен NS_EMAIL.

Поставщик передает структуру 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**. Дополнительные сведения см. в Query-Related структурах данных.

имя члена 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 [только классические приложения]
целевая платформа	Виндоус
заголовка	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.

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