Compartir a través de

Cómo buscar mediante VLV

  • Artículo

Active Directory admite búsquedas de vistas 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 entradas concretas en función de un desplazamiento numérico. Este método es útil cuando se recuperan resultados de búsqueda en respuesta a una operación de desplazamiento.

La segunda forma 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 de 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 la preferencia de búsqueda de ADS_SEARCHPREF_SORT_ON , vea Ordenar los resultados de la búsqueda con IDirectorySearch.

Cuando se realiza una búsqueda de VLV, se devuelve una determinada cantidad de metadatos sobre la búsqueda en una columna que se recupera llamando a IDirectorySearch::GetColumn con el identificador de ADS_VLV_RESPONSE . Estos datos se encuentran en una estructura de ADS_VLV . De particular 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 está contenida 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 las 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 cero o NULL .

  2. Rellene un ADS_SEARCHPREF_INFO con los valores siguientes.

    • Establezca el miembro dwSearchPref en ADS_SEARCHPREF_VLV.
    • Establezca el miembro vValue.dwType en ADSTYPE_PROV_SPECIFIC.
    • Establezca el miembro vValue.ProviderSpecific.dwLength en el tamaño de la estructura 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 de ADS_SEARCH_COLUMN en un puntero de estructura de ADS_VLV. El miembro dwContentCount de esta estructura de ADS_VLV contiene el número aproximado de elementos devueltos por 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 de 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 momento 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 lista en 3000 y desea que el desplazamiento sea la entrada de lista 1500, establecería dwContentCount en 3000 y dwOffset en 1500. Si el servidor calcula el tamaño real de la lista en 4500, volverá a calcular 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 artículo 50 en una ración de 100, no se garantiza que obtenga el elemento intermedio 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 para 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 de ADS_SEARCH_COLUMN en un puntero de estructura de ADS_VLV.

  8. Realice una copia de los datos lpContextID y guídelo 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 elemento en sí, 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 de VLV para buscar elementos que tengan un atributo de cadena cuyo valor coincida 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 de 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 para 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 de ADS_SEARCH_COLUMN en un puntero de estructura de 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.