Como pesquisar usando o VLV

O Active Directory dá suporte a pesquisas de VLV (exibição de lista virtual). Esse estilo de pesquisa foi especificamente projetado para grandes conjuntos de resultados e permite que um aplicativo exiba um subconjunto de milhares de entradas sem realmente precisar recuperar todas as entradas.

Há duas maneiras distintas de usar uma pesquisa VLV. A primeira é recuperar os atributos para entradas específicas com base em um deslocamento numérico. Esse método é útil ao recuperar os resultados da pesquisa em resposta a uma operação de rolagem.

A segunda maneira de usar pesquisas VLV é pesquisar parte ou todos os atributos textuais e exibir apenas os resultados da pesquisa. Um exemplo de uso disso é um catálogo de endereços. Se o usuário digitar um "s", o aplicativo poderá usar uma pesquisa VLV para pesquisar entradas que tenham um nome comum que comece com "s". Se o usuário adicionar um "m" aos "s", o aplicativo poderá usar outra pesquisa VLV para pesquisar entradas que tenham um nome comum que comece com "sm".

Para executar uma pesquisa VLV, instrua ADSI a usar o controle VLV. Para fazer isso, chame o método IDirectorySearch::SetSearchPreference com uma opção de pesquisa ADS_SEARCHPREF_VLV com um valor ADSTYPE_PROV_SPECIFIC . O valor ADSTYPE_PROV_SPECIFIC é um ponteiro para uma estrutura ADS_VLV que contém dados sobre a pesquisa. A função de exemplo GetVLVItemCount mostra como definir ambas as preferências de pesquisa.

Todas as pesquisas VLV devem usar a classificação de resultados do lado do servidor, que é executada definindo a preferência de pesquisa ADS_SEARCHPREF_SORT_ON . Para obter mais informações sobre a preferência de pesquisa ADS_SEARCHPREF_SORT_ON , consulte Classificando os resultados da pesquisa com IDirectorySearch.

Quando uma pesquisa VLV é executada, uma determinada quantidade de metadados sobre a pesquisa é retornada em uma coluna que é recuperada chamando IDirectorySearch::GetColumn com o identificador ADS_VLV_RESPONSE . Esses dados estão contidos em uma estrutura ADS_VLV . De particular importância estão os membros dwContentCount e lpContextID . O membro dwContentCount conterá o número de resultados que atendem aos critérios de pesquisa VLV. Esse valor pode ser usado como uma estimativa do número total de itens que seriam retornados para uma pesquisa desse tipo. O membro lpContextID contém um valor definido pelo servidor que pode ser passado para a próxima pesquisa para identificar a pesquisa. Usar o lpContextID pode melhorar o desempenho da pesquisa. Lembre-se de que lpContextID é um valor definido pelo servidor e seu comprimento está contido no membro dwContextIDLength . Esse buffer é liberado quando o método IDirectorySearch::FreeColumn é chamado, portanto, o chamador deve alocar um buffer do tamanho apropriado e copiar e salvar o conteúdo do buffer entre pesquisas.

Para obter mais informações sobre o controle VLV LDAP, consulte Pesquisar com o controle VLV LDAP.

Para obter mais informações, consulte:

Obtendo o número de itens

Para obter uma estimativa do número de itens que serão retornados para uma pesquisa específica, execute as etapas a seguir.

  1. Preencha uma estrutura ADS_VLV com todos os valores zero ou NULL .

  2. Preencha um ADS_SEARCHPREF_INFO com os valores a seguir.

    • Defina o membro dwSearchPref como ADS_SEARCHPREF_VLV.
    • Defina o membro vValue.dwType como ADSTYPE_PROV_SPECIFIC.
    • Defina o membro vValue.ProviderSpecific.dwLength com o tamanho da estrutura ADS_VLV .
    • Defina o membro vValue.ProviderSpecific.lpValue como o endereço da estrutura ADS_VLV da Etapa 1.
  3. Preencha uma estrutura de ADS_SORTKEY conforme mostrado na classificação dos resultados da pesquisa com IDirectorySearch para classificar o atributo desejado.

  4. Preencha outra ADS_SEARCHPREF_INFO para adicionar a estrutura ADS_SORTKEY às preferências de pesquisa, conforme mostrado na Classificação dos Resultados da Pesquisa com IDirectorySearch.

  5. Adicione quaisquer outras preferências de pesquisa desejadas e chame IDirectorySearch::SetSearchPreference para definir as preferências de pesquisa.

  6. Execute a pesquisa com IDirectorySearch::ExecuteSearch.

  7. Obtenha a primeira linha de resultados chamando IDirectorySearch::GetFirstRow.

  8. Chame IDirectorySearch::GetColumn com ADS_VLV_RESPONSE para obter os metadados de pesquisa VLV.

  9. Cast the pADsValues-ProviderSpecific.lpValue> of the ADS_SEARCH_COLUMN structure to an ADS_VLV structure pointer. O membro dwContentCount dessa estrutura ADS_VLV contém o número aproximado de itens que seriam retornados por uma pesquisa desse tipo.

  10. Se outras pesquisas VLV do mesmo tipo forem executadas, faça uma cópia dos dados lpContextID e preserve-os para a próxima pesquisa VLV.

A função de exemplo GetVLVItemCount mostra como fazer isso.

Pesquisando por deslocamento

Uma coisa que torna as pesquisas VLV tão rápidas é que é possível pesquisar um resultado específico por um deslocamento numérico. Por exemplo, se uma pesquisa resultar em 10.000 itens sendo retornados, uma pesquisa VLV possibilita obter as informações para aproximadamente o 4072º item sem precisar recuperar todos os itens antes do item em questão.

Os deslocamentos são especificados como uma taxa entre o deslocamento e a contagem de conteúdo. As taxas são úteis porque o servidor pode não ter uma estimativa precisa do número de entradas existentes na lista ou o tamanho da lista pode estar mudando durante o tempo em que o usuário está navegando. Como você deve indicar o início e o fim da lista, você pode usar um valor estimado para a contagem de conteúdo na primeira solicitação de pesquisa, juntamente com um valor de deslocamento. O servidor usa esses dados para calcular os deslocamentos correspondentes na lista, com base em sua ideia de contagem de conteúdo, que é enviada em sua resposta ao cliente por meio do membro dwContentCount da estrutura ADS_VLV . Por exemplo, se você estimar o tamanho da lista como 3000 e quiser que o deslocamento seja a entrada de lista 1500, defina dwContentCount como 3000 e dwOffset como 1500. Se o servidor estimar que o tamanho real da lista seja 4500, ele recalculará o deslocamento para 2250 e retornará as novas estimativas em dwContentCount e dwOffset.

Observação

Todos os valores numéricos em uma pesquisa VLV são aproximações e não devem ser usados para valores absolutos. Por exemplo, se você emitir uma pesquisa VLV para o 50º item em uma ração de 100, você não tem a garantia de obter o item do meio exato.

Para pesquisar um item específico por deslocamento, execute as etapas a seguir.

  1. Preencha uma estrutura ADS_VLV com os valores a seguir. Membros adicionais da estrutura devem ser definidos como zero ou NULL.

    • Defina o membro dwContentCount como o valor máximo da taxa de itens a serem recuperados.
    • Defina o membro dwOffset como a taxa, em relação a dwContentCount, do item ou itens a serem recuperados.
    • Defina o membro lpContextID como o endereço da cópia do buffer de ID de contexto e o dwContextIDLength para o comprimento, em bytes, do buffer de ID de contexto. Se nenhuma ID de contexto tiver sido salva, ambos os membros deverão ser zero ou NULL.
  2. Defina as preferências de pesquisa, conforme mostrado nas Etapas 2 a 5 do procedimento Obtendo o número de itens.

  3. Execute a pesquisa com IDirectorySearch::ExecuteSearch.

  4. Obtenha a primeira linha de resultados chamando IDirectorySearch::GetFirstRow.

  5. Chame IDirectorySearch::GetColumn com o nome do atributo a ser recuperado para obter os dados reais do item solicitado.

  6. Chame IDirectorySearch::GetColumn com ADS_VLV_RESPONSE para obter os metadados de pesquisa VLV.

  7. Cast the pADsValues-ProviderSpecific.lpValue> of the ADS_SEARCH_COLUMN structure to an ADS_VLV structure pointer.

  8. Faça uma cópia dos dados lpContextID e preserve-os para a próxima pesquisa VLV.

 

A função de exemplo GetVLVItemText mostra como fazer isso.

Também é possível recuperar mais de uma linha de dados com uma única chamada de pesquisa. Isso é feito na Etapa 1 definindo adequadamente os membros dwBeforeCount e dwAfterCount da estrutura ADS_VLV . O membro dwBeforeCount contém o número de itens que aparecem na lista antes do item em questão e o membro dwAfterCount contém o número de itens que aparecem na lista após o item em questão. Ambas as contagens excluem o item em si, portanto, definir dwBeforeCount como 10 e dwAfterCount como 10 resultará em um total de 21 itens retornados. Essa opção permite armazenar em cache os resultados da pesquisa no lado do cliente.

Pesquisando por cadeia de caracteres

Também é possível usar uma pesquisa VLV para localizar itens que têm um atributo de cadeia de caracteres cujo valor corresponde a toda ou parte de uma cadeia de caracteres sem precisar recuperar todos os itens. A correspondência de cadeia de caracteres é executada em relação ao atributo especificado na estrutura ADS_SORTKEY da preferência de pesquisa ADS_SEARCHPREF_SORT_ON .

Para pesquisar um item específico por cadeia de caracteres, execute as etapas a seguir.

  1. Preencha uma estrutura ADS_VLV com os valores a seguir. Membros adicionais da estrutura devem ser definidos como zero ou NULL.

    • Defina o membro pszTarget como um ponteiro para uma cadeia de caracteres terminada por NULL que contém a cadeia de caracteres a ser pesquisada.
    • Defina o membro lpContextID como o endereço da cópia do buffer de ID de contexto e o dwContextIDLength para o comprimento, em bytes, do buffer de ID de contexto. Se nenhuma ID de contexto tiver sido salva, ambos os membros deverão ser zero ou NULL.
  2. Defina as preferências de pesquisa, conforme mostrado nas Etapas 2 a 5 do procedimento Obtendo o número de itens.

  3. Execute a pesquisa com IDirectorySearch::ExecuteSearch.

  4. Obtenha a primeira linha de resultados chamando IDirectorySearch::GetFirstRow.

  5. Chame IDirectorySearch::GetColumn com o nome do atributo a ser recuperado para obter os dados reais do item solicitado.

  6. Chame IDirectorySearch::GetColumn com ADS_VLV_RESPONSE para obter os metadados de pesquisa VLV.

  7. Cast the pADsValues-ProviderSpecific.lpValue> of the ADS_SEARCH_COLUMN structure to an ADS_VLV structure pointer.

  8. Faça uma cópia dos dados lpContextID e preserve-os para a próxima pesquisa VLV. Se necessário, o membro dwOffset contém o índice baseado em um do primeiro item cujo atributo de cadeia de caracteres começa com o valor especificado em pszTarget.

A função de exemplo GetVLVItemsByString mostra como fazer isso.

Da mesma forma que pesquisar por índice, também é possível recuperar mais de uma linha de dados com uma única chamada de pesquisa. Isso é feito da mesma maneira definindo adequadamente os membros dwBeforeCount e dwAfterCount da estrutura ADS_VLV .