LPNSPV2LOOKUPSERVICENEXTEX função de retorno de chamada (ws2spi.h)
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 de 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 instruirá o provedor a descartar o último conjunto de resultados, que era muito grande, e passar 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 retornado
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 do erro | Significado |
|---|---|
|
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 a maior variedade possível de aplicativos. |
|
|
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 a maior variedade possível de aplicativos. |
|
| O buffer lpqsResults era muito pequeno para conter um conjunto WSAQUERYSET . | |
| Um ou mais parâmetros são inválidos ou ausentes para esse provedor. | |
| O identificador de pesquisa especificado é inválido. | |
| O nome foi encontrado no banco de dados, mas nenhum dado, correspondente às restrições determinadas, foi localizado. | |
| O serviço é desconhecido. O serviço não pode ser encontrado no namespace especificado. | |
| Não há memória suficiente disponível para executar essa operação. |
Comentários
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 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 da hora NSPv2LookupServiceBegin e as do NSPv2LookupServiceNextEx . Portanto, os sinalizadores em NSPv2LookupServiceNextEx nunca podem aumentar a quantidade de dados retornados além do que foi solicitado em NSPv2LookupServiceBegin, embora não seja um erro especificar mais ou menos sinalizadores. Os sinalizadores especificados em um determinado NSPv2LookupServiceNextEx aplicam-se somente a essa chamada.
Os LUP_FLUSHPREVIOUS e LUP_RES_SERVICEdwControlFlags 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 esteja disponível. Nenhum erro é gerado.
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 que você obtém 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 WSAQUERYSET2 .
A estrutura WSAQUERYSET2 apontada pelo parâmetro lpqsResults retornado só é útil no mesmo contexto de processo, pois 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 realizar marshaling dos dados retornados na estrutura 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. Basta passar uma cópia da estrutura WSAQUERYSET2 é insuficiente, pois somente ponteiros para os dados serão passados e os dados reais não estarão disponí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, consulte Estruturas de dados relacionadas à consulta.| 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** | Esse membro é indefinido para resultados. |
| **lpafpProtocols** | Esse 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 **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 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
| Cliente mínimo com suporte | Windows Vista [somente aplicativos da área de trabalho] |
| Servidor mínimo com suporte | Windows Server 2008 [somente aplicativos da área de trabalho] |
| Plataforma de Destino | Windows |
| Cabeçalho | ws2spi.h |
Confira também
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de