Função WSALookupServiceNextA (winsock2.h)
A função WSALookupServiceNext é chamada depois de obter um identificador de uma chamada anterior para WSALookupServiceBegin para recuperar as informações de serviço solicitadas.
O provedor passará uma estrutura WSAQUERYSET no buffer lpqsResults . O cliente deve continuar a chamar essa função até retornar WSA_E_NO_MORE, indicando que todo O WSAQUERYSET foi retornado.
Sintaxe
INT WSAAPI WSALookupServiceNextA(
[in] HANDLE hLookup,
[in] DWORD dwControlFlags,
[in, out] LPDWORD lpdwBufferLength,
[out] LPWSAQUERYSETA lpqsResults
);
Parâmetros
[in] hLookup
Um identificador retornado da chamada anterior para WSALookupServiceBegin.
[in] dwControlFlags
Um conjunto de sinalizadores que controla a operação. Os valores passados no parâmetro dwControlFlags para a função WSALookupServiceBegin determinam os critérios possíveis. Todos os valores passados no parâmetro dwControlFlags para a função WSALookupServiceNext restringem ainda mais os critérios para a pesquisa de serviço.
Atualmente, LUP_FLUSHPREVIOUS é definido como um meio de lidar com um conjunto de resultados muito grande. Se um aplicativo não fornecer (ou não) 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.
Os valores com suporte para o parâmetro dwControlFlags são definidos no arquivo de cabeçalho Winsock2.h e podem ser uma combinação das opções a seguir.
| Sinalizador | Significado |
|---|---|
|
Consulta profundamente em vez de apenas o primeiro nível. |
|
Retorna somente contêineres. |
|
Não retorne contêineres. |
|
Se possível, retorna resultados na ordem de distância. A medida de distância é específica do provedor. |
|
Recupera o nome como lpszServiceInstanceName. |
|
Recupera o tipo como lpServiceClassId. |
|
Recupera a versão como lpVersion. |
|
Recupera o comentário como lpszComment. |
|
Recupera os endereços como lpcsaBuffer. |
|
Recupera os dados privados como lpBlob. |
|
Todas as informações de alias disponíveis devem ser retornadas em chamadas sucessivas para WSALookupServiceNext, e cada alias retornado terá o sinalizador RESULT_IS_ALIAS definido. |
|
Recupera a cadeia de caracteres de consulta usada para a solicitação. |
|
Um conjunto de sinalizadores que recupera todos os valores de LUP_RETURN_*. |
|
Usado como um valor para o parâmetro dwControlFlags em WSALookupServiceNext. Definir esse sinalizador instrui o provedor a descartar o último conjunto de resultados, que era muito grande para o buffer especificado, e passar para o próximo conjunto de resultados. |
|
Se o provedor estiver armazenando informações em cache, ignorará o cache e consultará o próprio namespace. |
|
Isso indica se a resposta principal está na parte remota ou local da estrutura CSADDR_INFO . A outra parte precisa ser utilizável em ambos os casos. |
[in, out] lpdwBufferLength
Na entrada, o número de bytes contidos no buffer apontado por lpqsResults. Na saída, se a função falhar e o erro for WSAEFAULT, ele conterá o número mínimo de bytes a serem passados para o lpqsResults recuperar o registro.
[out] lpqsResults
Um ponteiro para um bloco de memória, que conterá um conjunto de resultados em uma estrutura WSAQUERYSET no retorno.
Valor retornado
O valor retornado será zero se a operação tiver sido bem-sucedida. Caso contrário, o valor SOCKET_ERROR será retornado e um número de erro específico poderá ser recuperado chamando WSAGetLastError.
| Código do erro | Significado |
|---|---|
| Uma chamada para WSALookupServiceEnd foi feita enquanto essa chamada ainda estava sendo processada. A chamada foi cancelada. Os dados no buffer lpqsResults são indefinidos. No Windows Sockets versão 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á. No entanto, para o Windows Sockets versão 2, os aplicativos devem marcar para WSAECANCELLED e WSA_E_CANCELLED para obter a compatibilidade mais ampla possível com provedores de namespace que usam qualquer um deles. | |
| Não há mais dados disponíveis. No Windows Sockets versão 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á. No entanto, para o Windows Sockets versão 2, os aplicativos devem marcar para WSAENOMORE e WSA_E_NO_MORE para a compatibilidade mais ampla possível com provedores de espaço de nome que usam qualquer um deles. | |
| O buffer lpqsResults era muito pequeno para conter um conjunto WSAQUERYSET . | |
| Um ou mais parâmetros necessários eram inválidos ou ausentes. | |
| O identificador de pesquisa especificado é inválido. | |
| O WS2_32.DLL não foi inicializado. O aplicativo deve primeiro chamar WSAStartup antes de chamar qualquer função do Windows Sockets. | |
| O nome foi encontrado no banco de dados, mas nenhum dado correspondente às restrições determinadas foi localizado. | |
| Não havia memória suficiente para executar a operação. |
Comentários
O parâmetro dwControlFlags especificado nessa função e os especificados no momento do WSALookupServiceBegin são tratados como restrições para fins de combinação. As restrições são combinadas entre as da hora WSALookupServiceBegin e as do horário WSALookupServiceNext . Portanto, os sinalizadores em WSALookupServiceNext nunca podem aumentar a quantidade de dados retornados além do que foi solicitado em WSALookupServiceBegin, embora não seja um erro especificar mais ou menos sinalizadores. Os sinalizadores especificados em um determinado WSALookupServiceNext se aplicam somente a essa chamada.
Os LUP_FLUSHPREVIOUS e LUP_RES_SERVICE dwControlFlags são exceções à regra de restrições combinadas (porque são sinalizadores de comportamento em vez de sinalizadores de restrição). Se qualquer um desses sinalizadores for usado no WSALookupServiceNext , eles terão seu efeito definido, independentemente da configuração dos mesmos sinalizadores em WSALookupServiceBegin.
Por exemplo, se LUP_RETURN_VERSION for especificado em WSALookupServiceBegin , o provedor de serviços recuperará registros, incluindo a versão. Se LUP_RETURN_VERSION NÃO for especificado em WSALookupServiceNext, 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 WSALookupServiceBegin , mas for especificado em WSALookupServiceNext, as informações retornadas não incluirão os dados privados. Nenhum erro é gerado.
Se a função WSALookupServiceNext falhar com um erro de WSAEFAULT, isso indicará que o buffer apontado pelo parâmetro lpqsResults era muito pequeno para conter os resultados da consulta. Um novo buffer para um WSAQUERYSET deve ser fornecido com um tamanho especificado pelo valor apontado pelo parâmetro lpdwBufferLength . Esse novo buffer para o WSAQUERYSET precisa ter alguns dos membros do WSAQUERYSET especificados antes de chamar a função WSALookupServiceNext novamente. No mínimo, o membro dwSize do WSAQUERYSET deve ser definido como o novo tamanho do buffer.
Resultados da consulta
A tabela a seguir descreve como os resultados da consulta são representados na estrutura WSAQUERYSET .| Membro WSAQUERYSET | Interpretação de resultado |
|---|---|
| dwSize | Será definido como sizeof( WSAQUERYSET). Isso é usado como um mecanismo de controle de versão. |
| dwOutputFlags | RESULT_IS_ALIAS sinalizador indica que esse é um resultado de alias. |
| Lpszserviceinstancename | A cadeia de caracteres referenciada contém o nome do serviço. |
| lpServiceClassId | O GUID correspondente à classe de serviço. |
| lpVersion | Faz referência ao número de versão da instância de serviço específica. |
| lpszComment | Cadeia de caracteres de comentário opcional especificada pela instância de serviço. |
| Dwnamespace | Namespace no qual a instância de serviço foi encontrada. |
| lpNSProviderId | Identifica o provedor de namespace específico que forneceu esse resultado de consulta. |
| lpszContext | Especifica o ponto de contexto em um namespace hierárquico no qual o serviço está localizado. |
| dwNumberOfProtocols | Indefinido para resultados. |
| lpafpProtocols | 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 parâmetro 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 parâmetro será NULL ou apontará para uma cadeia de caracteres de comprimento zero. |
| dwNumberOfCsAddrs | Indica 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. |
| Lpblob | (Opcional) Esse é um ponteiro para uma entidade específica do provedor. |
Windows Phone 8: a função WSALookupServiceNextW tem suporte para aplicativos da Windows Phone Store no Windows Phone 8 e posterior.
Windows 8.1 e Windows Server 2012 R2: a função WSALookupServiceNextW tem suporte para aplicativos da Windows Store em Windows 8.1, Windows Server 2012 R2 e posterior.
Observação
O cabeçalho winsock2.h define WSALookupServiceNext como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.
Requisitos
| Cliente mínimo com suporte | Windows 8.1, Windows Vista [aplicativos da área de trabalho | Aplicativos UWP] |
| Servidor mínimo com suporte | Windows Server 2003 [aplicativos da área de trabalho | Aplicativos UWP] |
| Plataforma de Destino | Windows |
| Cabeçalho | winsock2.h |
| Biblioteca | Ws2_32.lib |
| DLL | Ws2_32.dll |