Função WSALookupServiceBeginA (winsock2.h)
A função WSALookupServiceBegin inicia uma consulta de cliente restrita pelas informações contidas em uma estrutura WSAQUERYSET . WSALookupServiceBegin retorna apenas um identificador, que deve ser usado por chamadas subsequentes para WSALookupServiceNext para obter os resultados reais.
Sintaxe
INT WSAAPI WSALookupServiceBeginA(
[in] LPWSAQUERYSETA lpqsRestrictions,
[in] DWORD dwControlFlags,
[out] LPHANDLE lphLookup
);
Parâmetros
[in] lpqsRestrictions
Um ponteiro para os critérios de pesquisa. Consulte os Comentários para obter os detalhes.
[in] dwControlFlags
Um conjunto de sinalizadores que controla a profundidade da pesquisa.
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. |
[out] lphLookup
Um identificador a ser usado ao chamar WSALookupServiceNext para começar a recuperar o conjunto de resultados.
Retornar valor
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 |
|---|---|
| Não havia memória suficiente para executar a operação. | |
| Um ou mais parâmetros estavam ausentes ou inválidos para esse provedor. | |
| O nome foi encontrado no banco de dados, mas nenhum dado correspondente às restrições determinadas foi localizado. | |
| O WS2_32.DLL não foi inicializado. O aplicativo deve primeiro chamar WSAStartup antes de chamar qualquer função do Windows Sockets. | |
|
Nenhum serviço desse tipo é conhecido. O serviço não pode ser encontrado no namespace especificado.
Esse erro será retornado para uma solicitação de descoberta de serviço bluetooth se nenhum dispositivo Bluetooth remoto tiver sido encontrado. |
Comentários
O parâmetro lpqsRestrictions aponta para um buffer que contém uma estrutura WSAQUERYSET . No mínimo, o membro dwSize do WSAQUERYSET deve ser definido com o comprimento do buffer antes de chamar a função WSALookupServiceBegin . Os aplicativos podem restringir a consulta especificando outros membros no WSAQUERYSET.
Na maioria dos casos, os aplicativos interessados apenas em um protocolo de transporte específico devem restringir sua consulta por família de endereços e protocolo usando os membros dwNumberOfProtocols e lpafpProtocols do WSAQUERYSET em vez de especificar o namespace no membro dwNameSpace .
As informações sobre protocolos de transporte de rede com suporte podem ser retreidas usando a função EnumProtocols, WSAEnumProtocols, WSCEnumProtocols ou WSCEnumProtocols32 .
Também é possível restringir a consulta a um único namespace. Por exemplo, uma consulta que deseja apenas resultados do DNS (não resultados do arquivo de hosts locais e outros serviços de nomenclatura) definiria o membro dwNameSpace como NS_DNS. Por exemplo, uma descoberta de dispositivo Bluetooth definiria o membro dwNameSpace como NS_BTH.
Os aplicativos também podem restringir a consulta a um provedor de namespace específico especificando um ponteiro para o GUID do provedor no membro lpNSProviderId .
As informações sobre provedores de namespace no computador local podem ser recuperadas usando a função WSAEnumNameSpaceProviders, WSAEnumNameSpaceProvidersEx, WSCEnumNameSpaceProviders32 ou WSCEnumNameSpaceProvidersEx32 .
Se LUP_CONTAINERS for especificado em uma chamada, outros valores de restrição deverão ser evitados. Se algum for especificado, cabe ao provedor de serviços de nome decidir se ele pode dar suporte a essa restrição sobre os contêineres. Se não puder, ele deverá retornar um erro.
Alguns provedores de serviços de nome podem ter outros meios de localizar contêineres. Por exemplo, todos os contêineres podem ser de algum tipo conhecido ou de um conjunto de tipos conhecidos e, portanto, uma restrição de consulta pode ser criada para encontrá-los. Não importa o que outro significa que o provedor de serviços de nome tem para localizar contêineres, LUP_CONTAINERS e LUP_NOCONTAINERS têm precedência. Portanto, se uma restrição de consulta for fornecida que inclua contêineres, especificar LUP_NOCONTAINERS impedirá que os itens de contêiner sejam retornados. Da mesma forma, independentemente da restrição de consulta, se LUP_CONTAINERS for fornecida, somente os contêineres deverão ser retornados. Se um namespace não der suporte a contêineres e LUP_CONTAINERS for especificado, ele deverá simplesmente retornar WSANO_DATA.
O método preferencial para obter os contêineres dentro de outro contêiner é a chamada:
dwStatus = WSALookupServiceBegin(
lpqsRestrictions,
LUP_CONTAINERS,
lphLookup);
Essa chamada é seguida pelo número necessário de chamadas WSALookupServiceNext . Isso retornará todos os contêineres contidos imediatamente no contexto inicial; ou seja, não é uma consulta profunda. Com isso, é possível mapear a estrutura de espaço de endereço percorrendo a hierarquia, talvez enumerando o conteúdo dos contêineres selecionados. Os usos subsequentes de WSALookupServiceBegin usam os contêineres retornados de uma chamada anterior.
Conforme mencionado acima, uma estrutura WSAQUERYSET é usada como um parâmetro de entrada para WSALookupBegin para qualificar a consulta. A tabela a seguir indica como o WSAQUERYSET é usado para construir uma consulta. Quando um parâmetro é marcado como (opcional) um ponteiro NULL pode ser especificado, indicando que o parâmetro não será usado como critério de pesquisa. Consulte a seção Estruturas de dados relacionadas à consulta para obter informações adicionais.
| Membro WSAQUERYSET | Interpretação de consulta |
|---|---|
| dwSize | Deve ser definido como sizeof(WSAQUERYSET). Esse é um mecanismo de controle de versão. |
| dwOutputFlags | Ignorado para consultas. |
| Lpszserviceinstancename | (Opcional) A cadeia de caracteres referenciada contém o nome do serviço. A semântica para curinga dentro da cadeia de caracteres não é definida, mas pode ser compatível com determinados provedores de namespace. |
| lpServiceClassId | (Obrigatório) O GUID correspondente à classe de serviço. |
| lpVersion | (Opcional) Faz referência ao número de versão desejado e fornece semântica de comparação de versão (ou seja, a versão deve corresponder exatamente ou a versão não deve ser menor que o valor especificado). |
| lpszComment | Ignorado para consultas. |
|
Dwnamespace
Consulte a observação Importante a seguir. |
Identificador de um único namespace no qual restringir a pesquisa ou NS_ALL incluir todos os namespaces. |
| lpNSProviderId | (Opcional) Faz referência ao GUID de um provedor de namespace específico e limita a consulta somente a esse provedor. |
| lpszContext | (Opcional) Especifica o ponto de partida da consulta em um namespace hierárquico. |
| dwNumberOfProtocols | O tamanho da matriz de restrição de protocolo pode ser zero. |
| lpafpProtocols | (Opcional) Faz referência a uma matriz de estrutura AFPROTOCOLS . Somente os serviços que utilizam esses protocolos serão retornados. |
| lpszQueryString | (Opcional) Alguns namespaces (como whois++) dão suporte a consultas enriquecidas semelhantes a SQL contidas em uma cadeia de caracteres de texto simples. Esse parâmetro é usado para especificar essa cadeia de caracteres. |
| dwNumberOfCsAddrs | Ignorado para consultas. |
| Lpcsabuffer | Ignorado para consultas. |
| Lpblob | (Opcional) Esse é um ponteiro para uma entidade específica do provedor. |
Windows 8.1 e Windows Server 2012 R2: a função WSALookupServiceBeginW 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 WSALookupServiceBegin 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
| Requisito | Valor |
|---|---|
| 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 |