LPNSPV2LOOKUPSERVICEBEGIN função de retorno de chamada (ws2spi.h)
A função NSPv2LookupServiceBegin inicia uma consulta de cliente de um provedor de serviços de namespace versão 2 que é restrita pelas informações contidas em uma estrutura de WSAQUERYSET2 .
Sintaxe
LPNSPV2LOOKUPSERVICEBEGIN Lpnspv2lookupservicebegin;
INT Lpnspv2lookupservicebegin(
[in] LPGUID lpProviderId,
[in] LPWSAQUERYSET2W lpqsRestrictions,
[in] DWORD dwControlFlags,
[out] LPVOID lpvClientSessionArg,
[out] LPHANDLE lphLookup
)
{...}
Parâmetros
[in] lpProviderId
Um ponteiro para o identificador do provedor de serviços de namespace a ser consultado.
[in] lpqsRestrictions
Um ponteiro para os critérios de pesquisa. Consulte Observações.
[in] dwControlFlags
Um conjunto de sinalizadores que afetam a pesquisa. Esse parâmetro pode ser uma combinação dos seguintes valores definidos no arquivo de cabeçalho Winsock2.h .
| Valor | Significado |
|---|---|
|
Consulta a hierarquia de um provedor em vez de apenas o primeiro nível. |
|
Retorna apenas contêineres. |
|
Não retorna nenhum contêiner. |
|
Se possível, retorna os 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 NSPv2LookupServiceNextEx e cada alias retornado terá o sinalizador **RESULT_IS_ALIAS** definido. |
|
Recupera a cadeia de caracteres de consulta como **lpszQueryString**. |
|
Recupera informações, incluindo o nome, o tipo, a versão, o comentário, o endereço, o blob, os aliases e a cadeia de consulta. |
|
Se o provedor tiver informações armazenadas em cache, ignore o cache e consulte o próprio namespace. |
|
Usado como um valor para o parâmetro dwControlFlags em NSPv2LookupServiceNextEx. Definir esse sinalizador instrui o provedor a descartar o último conjunto de resultados, que era muito grande para o buffer fornecido, e passar para o próximo conjunto de resultados. |
|
Indica que o provedor de namespace deve incluir resultados não autoritativos para nomes. |
|
Indica se a resposta principal está na parte remota ou local de CSADDR_INFO estrutura. A outra parte deve ser utilizável em ambos os casos. Essa opção se aplica somente a solicitações de instância de serviço. |
|
Indica que o provedor de namespace deve usar uma consulta segura. Essa opção só se aplica a solicitações de consulta de nome. |
|
Indica que o provedor de namespace deve retornar apenas nomes preferenciais. |
|
Indica que o provedor de namespace deve retornar a configuração de endereço. |
|
Indica que o provedor de namespace deve retornar os endereços duplos. Essa opção só se aplica a soquetes de modo duplo (endereços mapeados IPv6 e IPv4). |
|
Indica que o provedor de namespace deve desabilitar a codificação automática de Nomes de Domínio Internacionais.
Esse valor é compatível com Windows 8 e Windows Server 2012 |
[out] lpvClientSessionArg
Um ponteiro para a sessão do cliente.
[out] lphLookup
Um ponteiro para o identificador a ser usado em chamadas subsequentes para NSPv2LookupServiceNextEx para recuperar o conjunto de resultados.
Retornar valor
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 |
|---|---|
| Um ou mais parâmetros eram inválidos ou ausentes para esse provedor. | |
| O nome foi encontrado no banco de dados, mas não tem os dados associados corretos para os quais foi resolvido. | |
| 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 NSPv2LookupServiceBegin é 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 NSPv2LookupServiceBegin só pode ser usada para operações em provedores de namespace NS_EMAIL.
A função NSPv2LookupServiceBegin retorna apenas um identificador, que deve ser usado por chamadas subsequentes para NSPv2LookupServiceNextEx para obter os resultados reais. Como essa operação não pode ser cancelada, ela deve ser implementada para ser executada rapidamente. Embora seja aceitável iniciar uma consulta de rede, essa função não deve exigir uma resposta para retornar com êxito.
A função NSPv2Startup é chamada sempre que um novo processo de cliente começa a usar o provedor de namespace. Os provedores podem usar o argumento de sessão do cliente apontado pelo parâmetro ppvClientSessionArg para armazenar informações sobre essa sessão. Se um valor tiver sido especificado para o argumento de sessão do cliente na chamada para a função NSPv2Startup , esse mesmo argumento de sessão do cliente será passado no parâmetro lpvClientSessionArg para a função NSPv2LookupServiceBegin .
Se LUP_CONTAINERS for especificado em uma chamada, evite todos os outros valores de restrição. Se algum for fornecido, o provedor de serviços de nome deverá decidir se pode dar suporte a essa restrição sobre os contêineres. Caso contrário, 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á retornar WSANO_DATA.
O método preferencial para obter os contêineres dentro de outro contêiner é a chamada:
dwStatus = NSPv2LookupServiceBegin(
lpProviderId,
lpqsRestrictions,
LUP_CONTAINERS,
lpClientSession,
lphLookup);
seguido pelo número necessário de chamadas NSPv2LookupServiceNextEx . 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 NSPv2LookupServiceBegin usam os contêineres retornados de uma chamada anterior.
Formando consultas
A estrutura WSAQUERYSET2 é usada como um parâmetro de entrada para NSPv2LookupServiceBegin para qualificar a consulta. A tabela a seguir lista **WSAQUERYSET2** nomes de membro e descreve como o **WSAQUERYSET2** é usado para construir uma consulta. Os membros rotulados como opcionais e dependentes dos requisitos do provedor NSPv2 podem ser fornecidos como um ponteiro **NULL** quando não utilizados como critérios de pesquisa pelo provedor de namespace. Para obter mais informações, consulte Estruturas de dados relacionadas à consulta.| WSAQUERYSET2 nome do membro | Interpretação de consulta |
|---|---|
| **Dwsize** | Será definido como sizeof(WSAQUERYSET2). Esse é um mecanismo de controle de versão. |
| **Lpszserviceinstancename** | Uma cadeia de caracteres que 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. Esse membro é opcional, dependendo dos requisitos do provedor de serviços NSPv2. |
| **lpVersion** | O número de versão desejado que 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 fornecido). Esse membro é opcional, dependendo dos requisitos do provedor de serviços NSPv2. |
| **lpszComment** | Esse membro é ignorado para consultas. |
| **Dwnamespace** | O identificador de um único namespace no qual restringir a pesquisa ou **NS_ALL** para incluir todos os namespaces. |
| **lpNSProviderId** | O GUID de um provedor de namespace específico que limita a consulta somente a esse provedor. Esse membro é opcional, dependendo dos requisitos do provedor de serviços NSPv2. |
| **lpszContext** | O ponto de partida da consulta em um namespace hierárquico. Esse membro é opcional, dependendo dos requisitos do provedor de serviços NSPv2. |
| **dwNumberOfProtocols** | O tamanho, em bytes, do número de entradas na matriz de restrição de protocolo. Esse membro pode ser zero. |
| **lpafpProtocols** | Uma matriz de estruturas AFPROTOCOLS . Somente os serviços que usam esses protocolos serão retornados. É permitido que o valor **AF_UNSPEC** apareça como um valor de família de protocolo, significando um curinga. Os provedores de namespace podem fornecer informações sobre qualquer serviço que use o protocolo correspondente, independentemente da família de endereços. Esse membro é opcional, dependendo dos requisitos do provedor de serviços NSPv2. |
| **lpszQueryString** | Alguns namespaces (como whois++) dão suporte a consultas avançadas semelhantes a SQL contidas em uma cadeia de caracteres de texto simples. Esse parâmetro é usado para especificar essa cadeia de caracteres. Esse membro é opcional, dependendo dos requisitos do provedor de serviços NSPv2. |
| **dwNumberOfCsAddrs** | Esse membro é ignorado para consultas. |
| **Lpcsabuffer** | Esse membro é ignorado para consultas. |
| **dwOutputFlags** | Esse membro é ignorado para consultas. |
| **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 |
|---|---|
| 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 |