LPNSPV2LOOKUPSERVICENEXTEX função de retorno de chamada (ws2spi.h)

Artigo
07/16/2024

A função NSPv2LookupServiceNextEx é chamada depois de obter um identificador de uma chamada anterior para NSPv2LookupServiceBegin para recuperar as informações solicitadas de um provedor de serviços do namespace versão 2.

Sintaxe

LPNSPV2LOOKUPSERVICENEXTEX Lpnspv2lookupservicenextex;

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

Parâmetros

[in] hAsyncCall

Um identificador retornado da chamada anterior para NSPv2LookupServiceBegin usado para chamadas assíncronas.

[in] hLookup

Um identificador retornado da chamada anterior para NSPv2LookupServiceBegin .

[in] dwControlFlags

Os sinalizadores usados para controlar a próxima operação. Atualmente, apenas LUP_FLUSHPREVIOUS é definido como um meio de lidar com um conjunto de resultados muito grande. Se um aplicativo não puder fornecer um buffer grande o suficiente, a configuração LUP_FLUSHPREVIOUS instrui o provedor a descartar o último conjunto de resultados, que era muito grande, e mover para o próximo conjunto para essa chamada.

[in, out] lpdwBufferLength

O tamanho, em bytes, na entrada, contido no buffer apontado por lpqsResults. Na saída, se a função falhar e o erro for WSAEFAULT, ele conterá o tamanho mínimo, em bytes a serem passados para o lpqsResults recuperar o registro.

[out] lpqsResults

Um ponteiro para um bloco de memória que conterá, no retorno, um conjunto de resultados em uma estrutura WSAQUERYSET2.

Valor de retorno

A função deverá retornar NO_ERROR (zero) se a rotina for bem-sucedida. Ele deverá retornar SOCKET_ERROR (ou seja, 1) se a rotina falhar e precisar definir o código de erro apropriado usando WSASetLastError.

Código de erro	Significado
WSA_E_CANCELLED	Uma chamada para NSPv2LookupServiceEnd foi feita enquanto essa chamada ainda estava sendo processada. A chamada foi cancelada. Os dados no buffer lpqsResults são indefinidos. No Windows Sockets 2, códigos de erro conflitantes são definidos para WSAECANCELLED (10103) e WSA_E_CANCELLED (10111). O código de erro WSAECANCELLED será removido em uma versão futura e somente WSA_E_CANCELLED permanecerá. Os provedores de namespace devem usar o código de erro WSA_E_CANCELLED para manter a compatibilidade com o intervalo de aplicativos mais amplo possível.
WSA_E_NO_MORE	Não há mais dados disponíveis. No Windows Sockets 2, códigos de erro conflitantes são definidos para WSAENOMORE (10102) e WSA_E_NO_MORE (10110). O código de erro WSAENOMORE será removido em uma versão futura e somente WSA_E_NO_MORE permanecerá. Os provedores de namespace devem usar o código de erro WSA_E_NO_MORE para manter a compatibilidade com o maior intervalo possível de aplicativos.
WSAEFAULT	O buffer lpqsResults era muito pequeno para conter um conjunto de WSAQUERYSET .
WSAEINVAL	Um ou mais parâmetros são inválidos ou ausentes para esse provedor.
WSA_INVALID_HANDLE	O identificador de pesquisa especificado é inválido.
WSANO_DATA	O nome foi encontrado no banco de dados, mas nenhum dado, que corresponde às restrições determinadas, foi localizado.
WSASERVICE_NOT_FOUND	O serviço é desconhecido. O serviço não pode ser encontrado no namespace especificado.
WSA_NOT_ENOUGH_MEMORY	Não há memória suficiente disponível para executar essa operação.

Observações

A função NSPv2LookupServiceNextEx é usada como parte da arquitetura do provedor de serviços de namespace versão 2 (NSPv2) disponível no Windows Vista e posterior.

No Windows Vista e no Windows Server 2008, a função NSPv2LookupServiceNextEx só pode ser usada para operações em provedores de namespace NS_EMAIL.

O provedor passará uma estrutura de WSAQUERYSET2 no buffer lpqsResults. O cliente deve chamar a função NSPv2LookupServiceNextEx até retornar WSA_E_NOMORE, indicando que todas as estruturas WSAQUERYSET2 foram retornadas.

Os dwControlFlags especificados nessa função e os especificados no momento de NSPv2LookupServiceBegin são tratados como "restrições" para fins de combinação. As restrições são combinadas entre as tempo de NSPv2LookupServiceBegin e as de NSPv2LookupServiceNextEx. Portanto, os sinalizadores em NSPv2LookupServiceNextEx nunca podem aumentar a quantidade de dados retornados além do solicitado em NSPv2LookupServiceBegin, embora não seja um erro especificar mais ou menos sinalizadores. Os sinalizadores especificados em um determinado NSPv2LookupServiceNextEx se aplicam somente a essa chamada.

Os dwControlFlagsLUP_FLUSHPREVIOUS e LUP_RES_SERVICE são exceções à regra de restrições combinadas (porque são sinalizadores de comportamento em vez de sinalizadores de "restrição"). Se um dos sinalizadores for usado em NSPv2LookupServiceNextEx, eles terão seu efeito definido independentemente da configuração dos mesmos sinalizadores em NSPv2LookupServiceBegin.

Por exemplo, se LUP_RETURN_VERSION for especificado em NSPv2LookupServiceBegin, o provedor de serviços recuperará registros, incluindo a versão. Se LUP_RETURN_VERSION não for especificado em NSPv2LookupServiceNextEx, as informações retornadas não incluirão a versão, mesmo que ela estivesse disponível. Nenhum erro é gerado.

Além disso, por exemplo, se LUP_RETURN_BLOB não for especificado em NSPv2LookupServiceBegin, mas for especificado em NSPv2LookupServiceNextEx, as informações retornadas não incluirão os dados privados. Nenhum erro é gerado.

A função NSPv2LookupServiceNextEx normalmente é chamada pelo menos duas vezes. A primeira vez para obter o tamanho do buffer necessário para receber o WSAQUERYSET2 apontado pelo parâmetro lpqsResults e a segunda vez para obter o conjunto de resultados da consulta real. Na primeira chamada, o provedor NSPv2 deve retornar o tamanho necessário para os resultados do WSAQUERYSET2.

A estrutura de WSAQUERYSET2 apontada pelo parâmetro lpqsResults retornado é útil apenas no mesmo contexto de processo, já que vários dos membros na estrutura WSAQUERYSET2 contêm ponteiros para os dados reais retornados. Se o resultado da consulta precisar ser passado para outro processo (usando RPC, por exemplo), será necessário serializar e fazer marshaling dos dados retornados na estrutura de WSAQUERYSET2 apontada pelo parâmetro lpqsResults incluindo os dados apontados pelos membros na estrutura WSAQUERYSET2. Os dados precisam ser serializados em um formulário que possa ser passado entre os limites do processo. Apenas passar uma cópia da estrutura de WSAQUERYSET2 é insuficiente, pois somente ponteiros para dados serão passados e os dados reais ficarão indisponíveis para outros processos.

Resultados da consulta

A tabela a seguir lista WSAQUERYSET2 e descreve como os resultados da consulta são representados na estrutura **WSAQUERYSET2**. Para obter mais informações, consulteestruturas de dados do Query-Related.

WSAQUERYSET2 nome do membro	Interpretação de resultado
dwSize	O tamanho, em bytes, de WSAQUERYSET2 estrutura. Isso é usado como um mecanismo de controle de versão.
lpszServiceInstanceName	Uma cadeia de caracteres que contém o nome do serviço.
lpVersion	Faz referência ao número de versão da instância de serviço específica.
lpszComment	Uma cadeia de caracteres de comentário fornecida pela instância de serviço. Esse membro é opcional, dependendo dos requisitos do provedor de serviços NSPv2.
dwNameSpace	O identificador de namespace no qual o nome ou instância de serviço foi encontrado.
lpNSProviderId	O provedor de namespace específico que forneceu esse resultado de consulta.
lpszContext	O ponto de contexto em um namespace hierárquico no qual o serviço está localizado.
dwNumberOfProtocols	Este membro é indefinido para resultados.
lpafpProtocols	Este membro é indefinido para resultados. Todas as informações de protocolo necessárias estão nas estruturas de CSADDR_INFO.
lpszQueryString	Quando dwControlFlags inclui LUP_RETURN_QUERY_STRING, esse membro retorna o restante não preparado do lpszServiceInstanceName especificado na consulta original. Por exemplo, em um namespace que identifica serviços por nomes hierárquicos que especificam um nome de host e um caminho de arquivo dentro desse host, o endereço retornado pode ser o endereço do host e o restante não preparado pode ser o caminho do arquivo. Se o lpszServiceInstanceName for totalmente analisado e LUP_RETURN_QUERY_STRING for usado, esse membro será nulo ou apontará para uma cadeia de caracteres de comprimento zero.
dwNumberOfCsAddrs	O número de elementos na matriz de estruturas CSADDR_INFO.
lpcsaBuffer	Um ponteiro para uma matriz de estruturas de CSADDR_INFO, com um endereço de transporte completo contido em cada elemento.
dwOutputFlags	O sinalizador RESULT_IS_ALIAS indica que esse é um resultado de alias.
lpBlob	Um ponteiro para uma entidade específica do provedor. Esse membro é opcional, dependendo dos requisitos do provedor de serviços NSPv2.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows Vista [somente aplicativos da área de trabalho]
servidor com suporte mínimo	Windows Server 2008 [somente aplicativos da área de trabalho]
da Plataforma de Destino	Windows
cabeçalho	ws2spi.h

Consulte também

CSADDR_INFO

NSPV2_ROUTINE

NSPv2Cleanup

NSPv2ClientSessionRundown

NSPv2LookupServiceBegin

NSPv2LookupServiceEnd

NSPv2SetServiceEx

NSPv2Startup

WSAQUERYSET2

WSASetLastError

WSAQUERYSET2 nome do membro	Interpretação de resultado
dwSize	O tamanho, em bytes, de WSAQUERYSET2 estrutura. Isso é usado como um mecanismo de controle de versão.
lpszServiceInstanceName	Uma cadeia de caracteres que contém o nome do serviço.
lpVersion	Faz referência ao número de versão da instância de serviço específica.
lpszComment	Uma cadeia de caracteres de comentário fornecida pela instância de serviço. Esse membro é opcional, dependendo dos requisitos do provedor de serviços NSPv2.
dwNameSpace	O identificador de namespace no qual o nome ou instância de serviço foi encontrado.
lpNSProviderId	O provedor de namespace específico que forneceu esse resultado de consulta.
lpszContext	O ponto de contexto em um namespace hierárquico no qual o serviço está localizado.
dwNumberOfProtocols	Este membro é indefinido para resultados.
lpafpProtocols	Este membro é indefinido para resultados. Todas as informações de protocolo necessárias estão nas estruturas de CSADDR_INFO.
lpszQueryString	Quando dwControlFlags inclui LUP_RETURN_QUERY_STRING, esse membro retorna o restante não preparado do lpszServiceInstanceName especificado na consulta original. Por exemplo, em um namespace que identifica serviços por nomes hierárquicos que especificam um nome de host e um caminho de arquivo dentro desse host, o endereço retornado pode ser o endereço do host e o restante não preparado pode ser o caminho do arquivo. Se o lpszServiceInstanceName for totalmente analisado e LUP_RETURN_QUERY_STRING for usado, esse membro será nulo ou apontará para uma cadeia de caracteres de comprimento zero.
dwNumberOfCsAddrs	O número de elementos na matriz de estruturas CSADDR_INFO.
lpcsaBuffer	Um ponteiro para uma matriz de estruturas de CSADDR_INFO, com um endereço de transporte completo contido em cada elemento.
dwOutputFlags	O sinalizador RESULT_IS_ALIAS indica que esse é um resultado de alias.
lpBlob	Um ponteiro para uma entidade específica do provedor. Esse membro é opcional, dependendo dos requisitos do provedor de serviços NSPv2.

Compartilhar via