Compartilhar via


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
LUP_DEEP
0x0001
Consulta a hierarquia de um provedor em vez de apenas o primeiro nível.
LUP_CONTAINERS
0x0002
Retorna apenas contêineres.
LUP_NOCONTAINERS
0x0004
Não retorna nenhum contêiner.
LUP_NEAREST
0x0008
Se possível, retorna os resultados na ordem de distância. A medida de distância é específica do provedor.
LUP_RETURN_NAME
0x0010
Recupera o nome como **lpszServiceInstanceName**.
LUP_RETURN_TYPE
0x0020
Recupera o tipo como **lpServiceClassId**.
LUP_RETURN_VERSION
0x0040
Recupera a versão como **lpVersion**.
LUP_RETURN_COMMENT
0x0080
Recupera o comentário como **lpszComment**.
LUP_RETURN_ADDR
0x0100
Recupera os endereços como **lpcsaBuffer**.
LUP_RETURN_BLOB
0x0200
Recupera os dados privados como **lpBlob**.
LUP_RETURN_ALIASES
0x0400
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.
LUP_RETURN_QUERY_STRING
0x0800
Recupera a cadeia de caracteres de consulta como **lpszQueryString**.
LUP_RETURN_ALL
0x0ff0
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.
LUP_FLUSHCACHE
0x1000
Se o provedor tiver informações armazenadas em cache, ignore o cache e consulte o próprio namespace.
LUP_FLUSHPREVIOUS
0x2000
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.
LUP_NON_AUTHORITATIVE
0x4000
Indica que o provedor de namespace deve incluir resultados não autoritativos para nomes.
LUP_RES_RESERVICE
0x8000
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.
LUP_SECURE
0x8000
Indica que o provedor de namespace deve usar uma consulta segura. Essa opção só se aplica a solicitações de consulta de nome.
LUP_RETURN_PREFERRED_NAMES
0x10000
Indica que o provedor de namespace deve retornar apenas nomes preferenciais.
LUP_ADDRCONFIG
0x100000
Indica que o provedor de namespace deve retornar a configuração de endereço.
LUP_DUAL_ADDR
0x200000
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).
LUP_DISABLE_IDN_ENCODING
0x800000
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
WSAEINVAL
Um ou mais parâmetros eram inválidos ou ausentes para esse provedor.
WSANO_DATA
O nome foi encontrado no banco de dados, mas não tem os dados associados corretos para os quais foi resolvido.
WSASERVICE_NOT_FOUND
O serviço é desconhecido. O serviço não pode ser encontrado no namespace especificado.
WSA_NOT_ENOUGH_MEMORY
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

Confira também

AFPROTOCOLS

NSPV2_ROUTINE

NSPv2Cleanup

NSPv2ClientSessionRundown

NSPv2LookupServiceEnd

NSPv2LookupServiceNextEx

NSPv2SetServiceEx

NSPv2Startup

WSAQUERYSET2

WSASERVICECLASSINFO

WSASetLastError