Comment effectuer une recherche à l’aide de VLV

  • Article

Active Directory prend en charge les recherches en mode liste virtuelle (VLV). Ce style de recherche est spécifiquement conçu pour les grands jeux de résultats et permet à une application d’afficher un sous-ensemble de milliers d’entrées sans avoir à récupérer chaque entrée.

Il existe deux façons distinctes d’utiliser une recherche VLV. La première consiste à récupérer les attributs d’entrées particulières en fonction d’un décalage numérique. Cette méthode est utile lors de la récupération des résultats de recherche en réponse à une opération de défilement.

La deuxième façon d’utiliser les recherches VLV consiste à rechercher une partie ou la totalité d’un attribut textuel et à afficher uniquement les résultats de la recherche. Un carnet d’adresses est un exemple d’utilisation de ce carnet d’adresses. Si l’utilisateur tape un « s », l’application peut utiliser une recherche VLV pour rechercher des entrées dont le nom commun commence par « s ». Si l’utilisateur ajoute ensuite un « m » au « s », l’application peut utiliser une autre recherche VLV pour rechercher des entrées dont le nom commun commence par « sm ».

Pour effectuer une recherche VLV, demandez à ADSI d’utiliser le contrôle VLV. Pour ce faire, appelez la méthode IDirectorySearch::SetSearchPreference avec une option de recherche ADS_SEARCHPREF_VLV avec une valeur ADSTYPE_PROV_SPECIFIC . La valeur ADSTYPE_PROV_SPECIFIC est un pointeur vers une structure de ADS_VLV qui contient des données sur la recherche. L’exemple de fonction GetVLVItemCount montre comment définir ces deux préférences de recherche.

Toutes les recherches VLV doivent utiliser le tri des résultats côté serveur, qui est effectué en définissant la préférence de recherche ADS_SEARCHPREF_SORT_ON . Pour plus d’informations sur la préférence de recherche ADS_SEARCHPREF_SORT_ON , consultez Tri des résultats de la recherche avec IDirectorySearch.

Lorsqu’une recherche VLV est effectuée, une certaine quantité de métadonnées relatives à la recherche est retournée dans une colonne qui est récupérée en appelant IDirectorySearch::GetColumn avec l’identificateur ADS_VLV_RESPONSE . Ces données sont contenues dans une structure ADS_VLV . Les membres dwContentCount et lpContextID sont particulièrement importants. Le membre dwContentCount contient le nombre de résultats qui répondent aux critères de recherche VLV. Cette valeur peut être utilisée comme une estimation du nombre total d’éléments qui seraient retournés pour une recherche de ce type. Le membre lpContextID contient une valeur définie par le serveur qui peut être passée à la recherche suivante pour identifier la recherche. L’utilisation de lpContextID peut améliorer les performances de recherche. N’oubliez pas que le lpContextID est une valeur définie par le serveur et que sa longueur est contenue dans le membre dwContextIDLength . Cette mémoire tampon est libérée lorsque la méthode IDirectorySearch::FreeColumn est appelée, de sorte que l’appelant doit allouer une mémoire tampon de la taille appropriée et copier et enregistrer le contenu de la mémoire tampon entre les recherches.

Pour plus d’informations sur le contrôle VLV LDAP, consultez Recherche avec le contrôle VLV LDAP.

Pour plus d'informations, consultez les pages suivantes :

Obtention du nombre d’éléments

Pour obtenir une estimation du nombre d’éléments qui seront retournés pour une recherche particulière, effectuez les étapes suivantes.

  1. Remplissez une structure ADS_VLV avec toutes les valeurs zéro ou NULL .

  2. Remplissez un ADS_SEARCHPREF_INFO avec les valeurs suivantes.

    • Définissez le membre dwSearchPref sur ADS_SEARCHPREF_VLV.
    • Définissez le membre vValue.dwType sur ADSTYPE_PROV_SPECIFIC.
    • Définissez le membre vValue.ProviderSpecific.dwLength sur la taille de la structure ADS_VLV .
    • Définissez le membre vValue.ProviderSpecific.lpValue sur l’adresse de la structure ADS_VLV de l’étape 1.

  3. Remplissez une structure ADS_SORTKEY comme indiqué dans Trier les résultats de la recherche avec IDirectorySearch pour trier sur l’attribut souhaité.

  4. Remplissez une autre ADS_SEARCHPREF_INFO pour ajouter la structure ADS_SORTKEY aux préférences de recherche, comme indiqué dans Tri des résultats de la recherche avec IDirectorySearch.

  5. Ajoutez toutes les autres préférences de recherche souhaitées et appelez IDirectorySearch::SetSearchPreference pour définir les préférences de recherche.

  6. Effectuez la recherche avec IDirectorySearch::ExecuteSearch.

  7. Obtenez la première ligne de résultats en appelant IDirectorySearch::GetFirstRow.

  8. Appelez IDirectorySearch::GetColumn avec ADS_VLV_RESPONSE pour obtenir les métadonnées de recherche VLV.

  9. Castez le pADsValues-ProviderSpecific.lpValue> de la structure ADS_SEARCH_COLUMN en pointeur de structure ADS_VLV. Le membre dwContentCount de cette structure ADS_VLV contient le nombre approximatif d’éléments qui seraient retournés par une recherche de ce type.

  10. Si d’autres recherches VLV du même type sont effectuées, effectuez une copie des données lpContextID et conservez-les pour la recherche VLV suivante.

L’exemple de fonction GetVLVItemCount montre comment procéder.

Recherche par décalage

Une chose qui rend les recherches VLV si rapides est qu’il est possible de rechercher un résultat spécifique par un décalage numérique. Par exemple, si une recherche entraîne le retour de 10 000 éléments, une recherche VLV permet d’obtenir les informations relatives à environ le 4072e élément sans avoir à récupérer tous les éléments avant l’élément en question.

Les décalages sont spécifiés sous forme de rapport entre le décalage et le nombre de contenu. Les ratios sont utiles, car le serveur n’a peut-être pas une estimation précise du nombre d’entrées qui existent dans la liste ou la taille de la liste peut changer pendant le temps où l’utilisateur la navigue. Étant donné que vous devez indiquer le début et la fin de la liste, vous pouvez utiliser une valeur estimée pour le nombre de contenu dans la première demande de recherche, ainsi qu’une valeur de décalage. Le serveur utilise ces données pour calculer les décalages correspondants dans la liste, en fonction de son idée du nombre de contenu, qui est envoyée dans sa réponse au client via le membre dwContentCount de la structure ADS_VLV . Par exemple, si vous estimez la taille de la liste à 3 000 et que vous souhaitez que le décalage soit l’entrée de liste 1500, vous définissez dwContentCount sur 3000 et dwOffset sur 1500. Si le serveur estime la taille réelle de la liste à 4500, il recalcule le décalage sur 2250 et retourne les nouvelles estimations dans dwContentCount et dwOffset.

Notes

Toutes les valeurs numériques d’une recherche VLV sont des approximations et ne doivent pas être utilisées pour les valeurs absolues. Par exemple, si vous effectuez une recherche VLV pour le 50e élément dans une ration de 100, vous n’êtes pas assuré d’obtenir l’élément central exact.

Pour rechercher un élément particulier par décalage, effectuez les étapes suivantes.

  1. Remplissez une structure ADS_VLV avec les valeurs suivantes. Les membres supplémentaires de la structure doivent être définis sur zéro ou NULL.

    • Définissez le membre dwContentCount sur la valeur maximale du ratio d’éléments à récupérer.
    • Définissez le membre dwOffset sur le ratio, par rapport à dwContentCount, de l’élément ou des éléments à récupérer.
    • Définissez le membre lpContextID sur l’adresse de la copie de la mémoire tampon d’ID de contexte et le dwContextIDLength sur la longueur, en octets, de la mémoire tampon d’ID de contexte. Si aucun ID de contexte n’a été enregistré, ces deux membres doivent avoir la valeur zéro ou NULL.

  2. Définissez les préférences de recherche comme indiqué aux étapes 2 à 5 de la procédure Obtention du nombre d’éléments.

  3. Effectuez la recherche avec IDirectorySearch::ExecuteSearch.

  4. Obtenez la première ligne de résultats en appelant IDirectorySearch::GetFirstRow.

  5. Appelez IDirectorySearch::GetColumn avec le nom de l’attribut à récupérer pour obtenir les données réelles de l’élément demandé.

  6. Appelez IDirectorySearch::GetColumn avec ADS_VLV_RESPONSE pour obtenir les métadonnées de recherche VLV.

  7. Castez le pADsValues-ProviderSpecific.lpValue> de la structure ADS_SEARCH_COLUMN en pointeur de structure ADS_VLV.

  8. Effectuez une copie des données lpContextID et conservez-les pour la recherche VLV suivante.

 

L’exemple de fonction GetVLVItemText montre comment procéder.

Il est également possible de récupérer plusieurs lignes de données avec un seul appel de recherche. Pour ce faire, à l’étape 1, définissez correctement les membres dwBeforeCount et dwAfterCount de la structure ADS_VLV . Le membre dwBeforeCount contient le nombre d’éléments qui apparaissent dans la liste antérieure à l’élément en question et le membre dwAfterCount contient le nombre d’éléments qui apparaissent dans la liste après l’élément en question. Ces deux nombres excluent l’élément lui-même. Par conséquent, si vous définissez dwBeforeCount sur 10 et dwAfterCount sur 10, un total de 21 éléments sera retourné. Cette option permet de mettre en cache les résultats de la recherche côté client.

Recherche par chaîne

Il est également possible d’utiliser une recherche VLV pour rechercher des éléments qui ont un attribut de chaîne dont la valeur correspond à la totalité ou à une partie d’une chaîne sans avoir à récupérer tous les éléments. La correspondance de chaîne est effectuée par rapport à l’attribut spécifié dans la structure ADS_SORTKEY de la préférence de recherche ADS_SEARCHPREF_SORT_ON .

Pour rechercher un élément particulier par chaîne, effectuez les étapes suivantes.

  1. Remplissez une structure ADS_VLV avec les valeurs suivantes. Les membres supplémentaires de la structure doivent être définis sur zéro ou NULL.

    • Définissez le membre pszTarget sur un pointeur vers une chaîne terminée par NULL qui contient la chaîne à rechercher.
    • Définissez le membre lpContextID sur l’adresse de la copie de la mémoire tampon d’ID de contexte et le dwContextIDLength sur la longueur, en octets, de la mémoire tampon d’ID de contexte. Si aucun ID de contexte n’a été enregistré, ces deux membres doivent avoir la valeur zéro ou NULL.

  2. Définissez les préférences de recherche comme indiqué aux étapes 2 à 5 de la procédure Obtention du nombre d’éléments.

  3. Effectuez la recherche avec IDirectorySearch::ExecuteSearch.

  4. Obtenez la première ligne de résultats en appelant IDirectorySearch::GetFirstRow.

  5. Appelez IDirectorySearch::GetColumn avec le nom de l’attribut à récupérer pour obtenir les données réelles de l’élément demandé.

  6. Appelez IDirectorySearch::GetColumn avec ADS_VLV_RESPONSE pour obtenir les métadonnées de recherche VLV.

  7. Castez le pADsValues-ProviderSpecific.lpValue> de la structure ADS_SEARCH_COLUMN en pointeur de structure ADS_VLV.

  8. Effectuez une copie des données lpContextID et conservez-les pour la recherche VLV suivante. Si nécessaire, le membre dwOffset contient l’index de base unique du premier élément dont l’attribut de chaîne commence par la valeur spécifiée dans pszTarget.

L’exemple de fonction GetVLVItemsByString montre comment procéder.

Comme pour la recherche par index, il est également possible de récupérer plusieurs lignes de données avec un seul appel de recherche. Pour ce faire, définissez correctement les membres dwBeforeCount et dwAfterCount de la structure ADS_VLV .