Cómo buscar mediante VLV

Active Directory admite búsquedas de vista de lista virtual (VLV). Este estilo de búsqueda está diseñado específicamente para grandes conjuntos de resultados y permite a una aplicación mostrar un subconjunto de miles de entradas sin tener que recuperar realmente cada entrada.

Hay dos maneras distintas de usar una búsqueda de VLV. La primera consiste en recuperar los atributos de determinadas entradas en función de un desplazamiento numérico. Este método es útil al recuperar los resultados de búsqueda en respuesta a una operación de desplazamiento.

La segunda manera de usar las búsquedas de VLV es buscar parte o todo un atributo textual y mostrar solo los resultados de la búsqueda. Un ejemplo de uso de esta es una libreta de direcciones. Si el usuario escribe "s", la aplicación puede usar una búsqueda de VLV para buscar entradas que tengan un nombre común que comience por "s". Si el usuario agrega una "m" a "s", la aplicación puede usar otra búsqueda de VLV para buscar entradas que tengan un nombre común que comience por "sm".

Para realizar una búsqueda de VLV, indique a ADSI que use el control VLV. Para ello, llame al método IDirectorySearch::SetSearchPreference con una opción de búsqueda ADS_SEARCHPREF_VLV con un valor de ADSTYPE_PROV_SPECIFIC . El valor ADSTYPE_PROV_SPECIFIC es un puntero a una estructura de ADS_VLV que contiene datos sobre la búsqueda. La función de ejemplo GetVLVItemCount muestra cómo establecer ambas preferencias de búsqueda.

Todas las búsquedas de VLV deben usar la ordenación de resultados del lado servidor, que se realiza estableciendo la preferencia de búsqueda ADS_SEARCHPREF_SORT_ON . Para obtener más información sobre el ADS_SEARCHPREF_SORT_ON preferencia de búsqueda, vea Ordenar los resultados de búsqueda con IDirectorySearch.

Cuando se realiza una búsqueda VLV, se devuelve una determinada cantidad de metadatos sobre la búsqueda en una columna que se recupera mediante una llamada a IDirectorySearch::GetColumn con el identificador ADS_VLV_RESPONSE . Estos datos se encuentran en una estructura ADS_VLV . De especial importancia son los miembros dwContentCount y lpContextID . El miembro dwContentCount contendrá el número de resultados que cumplen los criterios de búsqueda de VLV. Este valor se puede usar como una estimación del número total de elementos que se devolverían para una búsqueda de ese tipo. El miembro lpContextID contiene un valor definido por el servidor que se puede pasar a la siguiente búsqueda para identificar la búsqueda. El uso de lpContextID puede mejorar el rendimiento de la búsqueda. Tenga en cuenta que lpContextID es un valor definido por el servidor y su longitud se encuentra en el miembro dwContextIDLength . Este búfer se libera cuando se llama al método IDirectorySearch::FreeColumn , por lo que el autor de la llamada debe asignar un búfer del tamaño adecuado y copiar y guardar el contenido del búfer entre búsquedas.

Para obtener más información sobre el control VLV ldap, vea Buscar con el control VLV ldap.

Para más información, consulte:

Obtener el número de elementos

Para obtener una estimación del número de elementos que se devolverán para una búsqueda determinada, realice los pasos siguientes.

  1. Rellene una estructura de ADS_VLV con todos los valores NULL o cero.

  2. Rellene un ADS_SEARCHPREF_INFO con los valores siguientes.

    • Establezca el miembro dwSearchPref en ADS_SEARCHPREF_VLV.
    • Establezca el miembro vValue.dwTypeen ADSTYPE_PROV_SPECIFIC.
    • Establezca el miembro vValue.ProviderSpecific.dwLength en el tamaño de la estructura de ADS_VLV .
    • Establezca el miembro vValue.ProviderSpecific.lpValue en la dirección de la estructura de ADS_VLV del paso 1.
  3. Rellene una estructura de ADS_SORTKEY como se muestra en Ordenar los resultados de búsqueda con IDirectorySearch para ordenar en el atributo deseado.

  4. Rellene otro ADS_SEARCHPREF_INFO para agregar la estructura de ADS_SORTKEY a las preferencias de búsqueda, como se muestra en Ordenar los resultados de la búsqueda con IDirectorySearch.

  5. Agregue cualquier otra preferencia de búsqueda deseada y llame a IDirectorySearch::SetSearchPreference para establecer las preferencias de búsqueda.

  6. Realice la búsqueda con IDirectorySearch::ExecuteSearch.

  7. Obtenga la primera fila de resultados llamando a IDirectorySearch::GetFirstRow.

  8. Llame a IDirectorySearch::GetColumn con ADS_VLV_RESPONSE para obtener los metadatos de búsqueda de VLV.

  9. Convierta pADsValues-ProviderSpecific.lpValue> de la estructura ADS_SEARCH_COLUMN en un puntero de estructura ADS_VLV. El miembro dwContentCount de esta estructura de ADS_VLV contiene el número aproximado de elementos que devolvería una búsqueda de ese tipo.

  10. Si se realizarán otras búsquedas de VLV del mismo tipo, realice una copia de los datos lpContextID y créela para la siguiente búsqueda de VLV.

La función de ejemplo GetVLVItemCount muestra cómo hacerlo.

Buscar por desplazamiento

Una cosa que hace que las búsquedas de VLV sea tan rápida es que es posible buscar un resultado específico mediante un desplazamiento numérico. Por ejemplo, si una búsqueda daría lugar a que se devuelvan 10 000 elementos, una búsqueda VLV permite obtener la información de aproximadamente el elemento 4072nd sin tener que recuperar todos los elementos antes del elemento en cuestión.

Los desplazamientos se especifican como una relación entre el desplazamiento y el recuento de contenido. Las relaciones son útiles porque es posible que el servidor no tenga una estimación precisa del número de entradas que existen en la lista o el tamaño de la lista puede cambiar durante el tiempo en que el usuario lo está explorando. Dado que debe indicar el principio y el final de la lista, puede usar un valor estimado para el recuento de contenido en la primera solicitud de búsqueda, junto con un valor de desplazamiento. El servidor usa estos datos para calcular los desplazamientos correspondientes dentro de la lista, en función de su idea de recuento de contenido, que se envía en su respuesta al cliente a través del miembro dwContentCount de la estructura ADS_VLV . Por ejemplo, si calcula el tamaño de la lista en 3000 y desea que el desplazamiento sea la entrada de lista 1500, debe establecer dwContentCount en 3000 y dwOffset en 1500. Si el servidor calcula el tamaño real de la lista en 4500, recalculará el desplazamiento a 2250 y devolverá las nuevas estimaciones en dwContentCount y dwOffset.

Nota

Todos los valores numéricos de una búsqueda de VLV son aproximaciones y no deben usarse para valores absolutos. Por ejemplo, si emite una búsqueda de VLV para el 50º elemento en una ración de 100, no se garantiza que obtenga el elemento central exacto.

Para buscar un elemento determinado por desplazamiento, realice los pasos siguientes.

  1. Rellene una estructura de ADS_VLV con los valores siguientes. Los miembros adicionales de la estructura deben establecerse en cero o NULL.

    • Establezca el miembro dwContentCount en el valor máximo de la proporción de elementos que se van a recuperar.
    • Establezca el miembro dwOffset en la relación, relativa a dwContentCount, del elemento o los elementos que se van a recuperar.
    • Establezca el miembro lpContextID en la dirección de la copia del búfer de identificador de contexto y dwContextIDLength en la longitud, en bytes, del búfer de identificador de contexto. Si no se ha guardado ningún identificador de contexto, ambos miembros deben ser cero o NULL.
  2. Establezca las preferencias de búsqueda como se muestra en los pasos 2 a 5 del procedimiento Obtener el número de elementos.

  3. Realice la búsqueda con IDirectorySearch::ExecuteSearch.

  4. Obtenga la primera fila de resultados llamando a IDirectorySearch::GetFirstRow.

  5. Llame a IDirectorySearch::GetColumn con el nombre del atributo que se va a recuperar para obtener los datos reales del elemento solicitado.

  6. Llame a IDirectorySearch::GetColumn con ADS_VLV_RESPONSE para obtener los metadatos de búsqueda de VLV.

  7. Convierta pADsValues-ProviderSpecific.lpValue> de la estructura ADS_SEARCH_COLUMN en un puntero de estructura ADS_VLV.

  8. Realice una copia de los datos lpContextID y conserve para la siguiente búsqueda de VLV.

 

La función de ejemplo GetVLVItemText muestra cómo hacerlo.

También es posible recuperar más de una fila de datos con una sola llamada de búsqueda. Esto se hace en el paso 1 estableciendo los miembros dwBeforeCount y dwAfterCount de la estructura ADS_VLV correctamente. El miembro dwBeforeCount contiene el número de elementos que aparecen en la lista antes del elemento en cuestión y el miembro dwAfterCount contiene el número de elementos que aparecen en la lista después del elemento en cuestión. Ambos recuentos excluyen el propio elemento, por lo que establecer dwBeforeCount en 10 y dwAfterCount en 10 dará como resultado un total de 21 elementos devueltos. Esta opción habilita el almacenamiento en caché de los resultados de búsqueda en el lado cliente.

Buscar por cadena

También es posible usar una búsqueda VLV para buscar elementos que tienen un atributo de cadena cuyo valor coincide con todo o parte de una cadena sin tener que recuperar todos los elementos. La coincidencia de cadenas se realiza con el atributo especificado en la estructura ADS_SORTKEY de la preferencia de búsqueda ADS_SEARCHPREF_SORT_ON .

Para buscar un elemento determinado por cadena, realice los pasos siguientes.

  1. Rellene una estructura de ADS_VLV con los valores siguientes. Los miembros adicionales de la estructura deben establecerse en cero o NULL.

    • Establezca el miembro pszTarget en un puntero a una cadena terminada en NULL que contiene la cadena que se va a buscar.
    • Establezca el miembro lpContextID en la dirección de la copia del búfer de identificador de contexto y dwContextIDLength en la longitud, en bytes, del búfer de identificador de contexto. Si no se ha guardado ningún identificador de contexto, ambos miembros deben ser cero o NULL.
  2. Establezca las preferencias de búsqueda como se muestra en los pasos 2 a 5 del procedimiento Obtener el número de elementos.

  3. Realice la búsqueda con IDirectorySearch::ExecuteSearch.

  4. Obtenga la primera fila de resultados llamando a IDirectorySearch::GetFirstRow.

  5. Llame a IDirectorySearch::GetColumn con el nombre del atributo que se va a recuperar para obtener los datos reales del elemento solicitado.

  6. Llame a IDirectorySearch::GetColumn con ADS_VLV_RESPONSE para obtener los metadatos de búsqueda de VLV.

  7. Convierta pADsValues-ProviderSpecific.lpValue> de la estructura ADS_SEARCH_COLUMN en un puntero de estructura ADS_VLV.

  8. Realice una copia de los datos lpContextID y guídelo para la siguiente búsqueda de VLV. Si es necesario, el miembro dwOffset contiene el índice basado en uno del primer elemento cuyo atributo de cadena comienza con el valor especificado en pszTarget.

La función de ejemplo GetVLVItemsByString muestra cómo hacerlo.

De forma similar a la búsqueda por índice, también es posible recuperar más de una fila de datos con una sola llamada de búsqueda. Esto se logra de la misma manera estableciendo los miembros dwBeforeCount y dwAfterCount de la estructura ADS_VLV correctamente.