Comment effectuer une recherche à l’aide de VLV

Active Directory prend en charge les recherches en mode liste virtuelle (VLV). Ce style de recherche est spécifiquement conçu pour les jeux de résultats volumineux et permet à une application d’afficher un sous-ensemble de milliers d’entrées sans avoir réellement à 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 pour des 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 l’ensemble d’un attribut textuel et à afficher uniquement les résultats de la recherche. Par exemple, il s’agit d’un 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 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 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 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 d’une importance particulière. 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 estimation du nombre total d’éléments 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 LDAP VLV, consultez Recherche avec le contrôle LDAP VLV.

Pour plus d'informations, consultez les pages suivantes :

Obtention du nombre d’éléments

Pour obtenir une estimation du nombre d’éléments retournés pour une recherche particulière, procédez comme suit.

  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 Tri des résultats de 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 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. Cast de la structure 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 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 rapide est qu’il est possible de rechercher un résultat spécifique par un décalage numérique. Par exemple, si une recherche entraînerait un renvoi de 10 000 éléments, une recherche VLV permet d’obtenir les informations pour 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 la forme d’un 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 liste peut changer pendant la navigation de l’utilisateur. É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 requête 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é 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 devez définir dwContentCount sur 3 000 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 émettez une recherche VLV pour le 50e élément dans une ration de 100, vous n’êtes pas garanti d’obtenir l’élément central exact.

Pour rechercher un élément particulier par décalage, procédez comme suit.

  1. Remplissez une structure ADS_VLV avec les valeurs suivantes. Les membres supplémentaires de la structure doivent avoir la valeur zéro ou NULL.

    • Définissez le membre dwContentCount sur la valeur maximale du rapport d’éléments à récupérer.
    • Définissez le membre dwOffset sur le ratio, relatif à 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é, les deux membres doivent être nuls ou NULL.
  2. Définissez les préférences de recherche comme indiqué dans les é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. Cast de la structure 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 les membres dwBeforeCount et dwAfterCount de la structure ADS_VLV de manière appropriée. Le membre dwBeforeCount contient le nombre d’éléments qui apparaissent dans la liste avant 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. La définition de dwBeforeCount sur 10 et dwAfterCount sur 10 entraîne un total de 21 éléments retournés. Cette option active la mise en cache des résultats de recherche côté client.

Recherche par chaîne

Il est également possible d’utiliser une recherche VLV pour rechercher des éléments ayant un attribut de chaîne dont la valeur correspond à la totalité ou à la partie d’une chaîne sans avoir à récupérer tous les éléments. La correspondance de chaîne est effectuée sur 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, procédez comme suit.

  1. Remplissez une structure ADS_VLV avec les valeurs suivantes. Les membres supplémentaires de la structure doivent avoir la valeur 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é, les deux membres doivent être nuls ou NULL.
  2. Définissez les préférences de recherche comme indiqué dans les é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. Cast de la structure 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 un 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.

De même que 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 .