Função de retorno de chamada LPNSPLOOKUPSERVICEBEGIN (ws2spi.h)

  • Artigo

A função NSPLookupServiceBegin inicia uma consulta de cliente de um provedor de serviços de nome que é restrito pelas informações contidas em uma estrutura WSAQUERYSET .

NSPLookupServiceBegin retorna apenas um identificador, que deve ser usado por chamadas subsequentes para NSPLookupServiceNext 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.

Sintaxe

LPNSPLOOKUPSERVICEBEGIN Lpnsplookupservicebegin;

INT Lpnsplookupservicebegin(
  [in]  LPGUID lpProviderId,
  [in]  LPWSAQUERYSETW lpqsRestrictions,
  [in]  LPWSASERVICECLASSINFOW lpServiceClassInfo,
  [in]  DWORD dwControlFlags,
  [out] LPHANDLE lphLookup
)
{...}

Parâmetros

[in] lpProviderId

Um ponteiro para o identificador do provedor de serviços de nome a ser consultado.

[in] lpqsRestrictions

Um ponteiro para os critérios de pesquisa. Consulte Observações.

[in] lpServiceClassInfo

Um ponteiro para a estrutura WSASERVICECLASSINFO que contém informações de esquema para o serviço.

[in] dwControlFlags

Um valor que controla a profundidade da pesquisa.

Valor Significado
LUP_DEEP
0x0001
 Consulta a hierarquia de um provedor em vez de apenas o primeiro nível.
LUP_CONTAINERS
0x0002
 Retorna somente contêineres.
LUP_NOCONTAINERS
0x0004
 Não retorna nenhum contêiner.
LUP_NEAREST
0x0008
 Se possível, retorna 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 NSPLookupServiceNext, 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 caracteres 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 NSPLookupServiceNext. 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 da estrutura CSADDR_INFO . 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).

[out] lphLookup

Um ponteiro para o identificador a ser usado em chamadas subsequentes para NSPLookupServiceNext para recuperar o conjunto de resultados.

Valor retornado

A função deverá retornar NO_ERROR (zero) se a rotina for bem-sucedida. Ele deverá retornar SOCKET_ERROR (–1) se a rotina falhar e precisar definir o código de erro apropriado usando WSASetLastError.

Código do erro Significado
WSA_NOT_ENOUGH_MEMORY
 Não há memória suficiente disponível para executar essa operação.
WSAEINVAL
 Um ou mais parâmetros eram inválidos ou ausentes para esse provedor.
WSAEOPNOTSUPP
 A operação não tem suporte. Esse erro será retornado se o provedor de namespace não implementar essa função.
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.

Comentários

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 deve 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 de obtenção dos contêineres em outro contêiner é a chamada:

dwStatus = NSPLookupServiceBegin(
    lpqsRestrictions,
    LUP_CONTAINERS,
    lphLookup);

seguido pelo número necessário de chamadas NSPLookupServiceNext . 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 NSPLookupServiceBegin usam os contêineres retornados de uma chamada anterior.

Formando consultas

Conforme mencionado, uma estrutura WSAQUERYSET é usada como um parâmetro de entrada para NSPLookupServiceBegin para qualificar a consulta. A tabela a seguir lista os nomes de membro WSAQUERYSET e descreve como o WSAQUERYSET é usado para construir uma consulta. Quando um membro é marcado como (Opcional) um ponteiro nulo pode ser fornecido, indicando que o parâmetro não será usado como critério de pesquisa. Para obter mais informações, consulte Estruturas de dados relacionadas à consulta.

Nome do membro WSAQUERYSET Interpretação da consulta
**Dwsize** 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 caracteres curinga dentro da cadeia de caracteres não é definida, mas pode ser compatível com determinados provedores de namespace.
**lpServiceClassId** Obrigatórios. 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 fornecido).
**lpszComment** Ignorado para consultas.
**Dwnamespace** Identificador de um namespace único no qual restringir a pesquisa ou **NS_ALL** para 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, em bytes, do número de entradas na matriz de restrição de protocolo, pode ser zero.
**lpafpProtocols** Opcional. Uma referência a 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.
**lpszQueryString** Opcional. 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.
**dwNumberOfCsAddrs** Ignorado para consultas.
**Lpcsabuffer** Ignorado para consultas.
**Lpblob** Opcional. Um ponteiro para uma entidade específica do provedor.

Requisitos

   
Cliente mínimo com suporte Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino Windows
Cabeçalho ws2spi.h

Confira também

AFPROTOCOLS

Nsplookupserviceend

Nsplookupservicenext

NSP_ROUTINE

WSAQUERYSET

WSASERVICECLASSINFO

WSASetLastError