Como pesquisar usando VLV

  • Artigo

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

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

A segunda maneira de usar pesquisas VLV é pesquisar parte ou todo um atributo textual 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 procurar entradas que tenham um nome comum que comece com "s". Se o usuário adicionar um "m" ao "s", o aplicativo pode usar outra pesquisa VLV para procurar 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 essas duas 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 certa 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 sã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. O uso do 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 as pesquisas.

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

Para saber mais, veja:

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 seguintes valores.

    • Defina o membro dwSearchPref como ADS_SEARCHPREF_VLV.
    • Defina o membro vValue.dwType como ADSTYPE_PROV_SPECIFIC.
    • Defina o membro vValue.ProviderSpecific.dwLength para 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 ADS_SORTKEY conforme mostrado em Classificando os resultados da pesquisa com IDirectorySearch para classificar no atributo desejado.

  4. Preencha outro ADS_SEARCHPREF_INFO para adicionar a estrutura ADS_SORTKEYàs preferências de pesquisa, conforme mostrado em Classificando os 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. Converta o pADsValues-ProviderSpecific.lpValue> da estrutura ADS_SEARCH_COLUMN em um ponteiro de estrutura ADS_VLV. O membro dwContentCount dessa estrutura de 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 preservá-los para a próxima pesquisa VLV.

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

Pesquisando por Offset

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 possibilitará obter as informações para aproximadamente o item 4072 sem ter que recuperar todos os itens antes do item em questão.

Os deslocamentos são especificados como uma proporção entre o deslocamento e a contagem de conteúdo. As proporções são úteis porque o servidor pode não ter uma estimativa precisa do número de entradas que existem 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 dentro da 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 o tamanho real da lista como 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 garantia de obter o item do meio exato.

Para procurar um item específico por deslocamento, execute as seguintes etapas.

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

    • Defina o membro dwContentCount como o valor máximo da proporção de itens a serem recuperados.
    • Defina o membro dwOffset para a proporção, relativa 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 nenhum ID de contexto tiver sido salvo, 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. Converta o pADsValues-ProviderSpecific.lpValue> da estrutura ADS_SEARCH_COLUMN em um ponteiro de estrutura ADS_VLV.

  8. Faça uma cópia dos dados lpContextID e preservá-los 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 os membros dwBeforeCount e dwAfterCount da estrutura ADS_VLV apropriadamente. 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 depois do 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 habilita o armazenamento em cache dos resultados da pesquisa no lado do cliente.

Pesquisando por String

Também é possível usar uma pesquisa VLV para localizar itens que tenham um atributo string cujo valor corresponda a toda ou parte de uma string 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 procurar um item específico por cadeia de caracteres, execute as seguintes etapas.

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

    • Defina o membro pszTarget como um ponteiro para uma cadeia de caracteres terminada em 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 nenhum ID de contexto tiver sido salvo, 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. Converta o pADsValues-ProviderSpecific.lpValue> da estrutura ADS_SEARCH_COLUMN em um ponteiro de estrutura ADS_VLV.

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

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

Da mesma forma que a pesquisa 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 os membros dwBeforeCount e dwAfterCount da estrutura ADS_VLV apropriadamente.