Função WSALookupServiceBeginW (winsock2.h)
A função
Sintaxe
INT WSAAPI WSALookupServiceBeginW(
[in] LPWSAQUERYSETW 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 detalhes.
[in] dwControlFlags
Um conjunto de sinalizadores que controla a profundidade da pesquisa.
Os valores com suporte para o parâmetro
| Bandeira | Significado |
|---|---|
|
Consultas profundas 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 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 tiver armazenado em cache informações, ignorará o cache e consultará o namespace em si. |
|
Isso indica se a resposta principal está na parte remota ou local de CSADDR_INFO estrutura. 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.
Valor de retorno
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.
Observações
O parâmetro
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 o
Informações sobre protocolos de transporte de rede com suporte podem ser retraídas usando o EnumProtocols, WSAEnumProtocols, WSCEnumProtocolsou função de WSCEnumProtocols32.
Também é possível restringir a consulta a um único namespace. Por exemplo, uma consulta que deseja apenas resultados de DNS (não resultados do arquivo de hosts locais e outros serviços de nomenclatura) definiria o membro
Os aplicativos também podem restringir a consulta a um provedor de namespace específico especificando um ponteiro para o GUID para o provedor no membro lpNSProviderId.
Informações sobre provedores de namespace no computador local podem ser recuperadas usando o WSAEnumNameSpaceProviders, WSAEnumNameSpaceProvidersEx, WSCEnumNameSpaceProviders32ou função 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 de obter os contêineres em 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 usar os contêineres retornados de uma chamada anterior.
Conforme mencionado acima, uma estrutura de WSAQUERYSET
| 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 suportada por determinados provedores de namespace. |
| lpServiceClassId | (Obrigatório) O GUID correspondente à classe de serviço. |
| lpVersion | (Opcional) Referencia o 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 do 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 inicial 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 de 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 que estão 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 no Windows 8.1, Windows Server 2012 R2 e posterior.
Nota
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 do pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.
Requisitos
| Requisito | Valor |
|---|---|
| de cliente com suporte mínimo | Windows 8.1, Windows Vista [aplicativos da área de trabalho | Aplicativos UWP] |
| servidor com suporte mínimo | Windows Server 2003 [aplicativos da área de trabalho | Aplicativos UWP] |
| da Plataforma de Destino |
Windows |
| cabeçalho | winsock2.h |
| biblioteca | Ws2_32.lib |
| de DLL |
Ws2_32.dll |
Consulte também
Bluetooth e WSALookupServiceBegin
EnumProtocols
WSCEnumProtocols