Structure LDAPVLVInfo (winldap.h)

Article
08/27/2023

La structure LDAPVLVInfo permet de configurer les paramètres de recherche d’un contrôle de requête VLV (LDAP_CONTROL_VLVREQUEST).

La structure LDAPVLVInfo peut également être utilisée par les applications pour gérer les données d’état associées à une série d’interactions client/serveur VLV.

Syntaxe

typedef struct ldapvlvinfo {
  int     ldvlv_version;
  ULONG   ldvlv_before_count;
  ULONG   ldvlv_after_count;
  ULONG   ldvlv_offset;
  ULONG   ldvlv_count;
  PBERVAL ldvlv_attrvalue;
  PBERVAL ldvlv_context;
  VOID    *ldvlv_extradata;
} LDAPVLVInfo, *PLDAPVLVInfo;

Membres

ldvlv_version

Identifie la version de la structure LDAPVLVInfo . Cette valeur doit toujours être définie sur la valeur LDAP_VLVINFO_VERSION (1).

ldvlv_before_count

Identifie le nombre d’entrées avant l’entrée cible que le client souhaite que le serveur renvoie dans les résultats de la liste. Ce champ correspond à l’élément beforeCount du contrôle LDAP_CONTROL_VLVREQUEST encodé en BER.

ldvlv_after_count

Indique le nombre d’entrées après l’entrée cible que le client a demandé au serveur de renvoyer dans les résultats de la liste. Ce champ correspond à l’élément afterCount du contrôle LDAP_CONTROL_VLVREQUEST encodé en BER.

ldvlv_offset

Indique un rapport entre la valeur de décalage et le nombre de contenu. Par exemple, considérez si un utilisateur fait glisser la barre de défilement pour afficher les entrées au milieu de la liste. Si le client estime que l’ensemble de la liste contient 100 entrées, il calcule le décalage à 50 pour afficher la liste centrale, de sorte que le client envoie cette valeur de décalage, avec 100 comme nombre de contenu, envoyée dans le membre ldvlv_count , au serveur. Lorsque le serveur reçoit ces données, il a peut-être calculé le nombre de contenu à 500, de sorte qu’il calcule le décalage pour rechercher la cible demandée par le client, à l’aide de la formule suivante :

Si = Sc * (Ci / Cc)

où

Si est le décalage de liste réel utilisé par le serveur

Sc est l’estimation du serveur pour le nombre de contenu

Ci est le décalage soumis par le client

Cc est le nombre de contenu soumis par le client

Si le client utilise une valeur de décalage d’une (1), cela indique que la cible est la première entrée de la liste. Si le client utilise une valeur de décalage égale à ldvlv_count, l’élément est la dernière entrée de la liste. Le décalage est égal à zéro (0) quand ldvlv_count est égal à zéro, ce qui est la dernière entrée de la liste.

Les décalages étant utilisés uniquement si la recherche n’est pas basée sur une valeur d’attribut, ldvlv_attrvalue doit avoir la valeur NULL. Ce champ correspond à l’élément offset dans le contrôle LDAP_CONTROL_VLVREQUEST encodé en BER.

ldvlv_count

Indique le nombre de contenu de la liste. Une estimation du nombre de contenu est envoyée par le client au serveur lors de l’envoi d’une demande de recherche, afin de permettre au serveur de calculer une valeur de décalage. Le serveur retourne son propre calcul du nombre de contenu au client dans sa réponse. Si le client n’a pas d’estimation pour le nombre de contenu, il envoie zéro (0), ce qui indique que le serveur doit utiliser sa propre estimation pour le nombre de contenu. Ce membre est utilisé avec ldvlv_offset. Étant donné que le nombre de contenu n’est requis que si la recherche n’est pas basée sur une valeur d’attribut, le membre ldvlv_attrvalue doit avoir la valeur NULL. Ce champ correspond à l’élément contentCount dans le contrôle LDAP_CONTROL_VLVREQUEST encodé en BER et à l’élément contentCount dans le contrôle LDAP_CONTROL_VLVRESPONSE encodé beR.

ldvlv_attrvalue

Fournit une valeur d’attribut en tant qu’entrée cible pour la recherche. Le serveur compare ce membre à des valeurs qui ont le même type d’attribut, comme spécifié dans le sk_attrtype membre de la structure LDAPSortKey . Si un décalage est utilisé, ce membre doit avoir la valeur NULL. Ce membre correspond à l’élément assertionValue du contrôle LDAP_CONTROL_VLVREQUEST encodé en BER.

ldvlv_context

Fournit l’ID de contexte attribué par le serveur pour identifier cette opération de recherche. Il s’agit d’un « cookie » opaque utilisé par le serveur pour assurer le suivi interne de l’opération VLV actuelle. Lors du premier appel à l’opération de recherche à l’aide du contrôle VLV, ce paramètre doit avoir la valeur NULL. Le serveur peut retourner une valeur dans le message LDAP_CONTROL_VLVRESPONSE . Cette valeur « cookie » doit être retournée au serveur lors de l’appel suivant à une fonction de recherche effectuée sur une liste VLV particulière.

ldvlv_extradata

Ce champ est réservé à une utilisation spécifique à l’application et n’est pas utilisé par la fonction ldap_create_vlv_control ; elle n’a aucun effet sur le contrôle créé.

Remarques

Il existe deux méthodes pour calculer la cible d’une recherche VLV : à l’aide d’une valeur d’attribut ou d’un décalage. Différents éléments de cette structure seront utilisés en fonction du type de recherche que vous choisissez. Les deux méthodes nécessitent que des valeurs soient entrées pour les membres ldvlv_before_count et ldvlv_after_count . Spécifiez un nombre de contenu de liste dans ldvlv_count, ou si vous ne connaissez pas cette valeur, utilisez zéro (0), afin que le serveur le calcule.

Recherche avec des valeurs d’attribut
Pour effectuer une recherche basée sur des valeurs, par exemple, si vous souhaitez rechercher Jeff Smith et que vous connaissez le type d’attribut de cette valeur, définissez le type d’attribut dans le sk_attrtype membre de la structure LDAPSortKey et la valeur d’attribut dans ldvlv_attrvalue. Le membre ldvlv_offset est ignoré pour ce type de recherche. Il n’est donc pas nécessaire de le définir.

Par exemple, pour effectuer une recherche à l’aide de la lettre J. Pour récupérer 20 résultats, définissez ldvlv_before_count sur 9, ldvlv_after_count sur 10 et ldvlv_attrvalue sur J. Le serveur recherche la première entrée de la liste qui n’est pas inférieure à J, telle que Jeff Smith, et retourne les neuf entrées précédentes, l’entrée cible et les 10 entrées suivantes. Le serveur retourne une ldvlv_count de 30000 et une ldvlv_offset de 4053 dans le contrôle LDAP_CONTROL_VLVRESPONSE ; c’est en supposant que Jeff Smith est le numéro d’entrée 4053 sur la liste. Le serveur peut retourner quelques entrées que celles demandées avant et/ou après l’entrée cible s’il n’y a pas suffisamment d’entrées dans la liste pour répondre à la demande. Par exemple, s’il n’y avait que deux entrées au total avant la première entrée « J », le serveur ne pouvait pas retourner neuf entrées précédentes.
Recherche avec décalages
Pour utiliser des décalages pour votre recherche, définissez un décalage dans ldvlv_offset et définissez ldvlv_attrvalue sur NULL. Définissez également le type d’attribut dans le membre sk_attrtype de LDAPSortKey, mais cette fois, la cible sera un décalage dans la liste des entrées pour ce type d’attribut, plutôt qu’une valeur d’attribut spécifique.

Par exemple, pour cibler la recherche 68 % de la liste des résultats de recherche. Si le ldvlv_count est 30 000, le 68 % de 30000 est 20400. Pour récupérer 20 résultats, définissez ldvlv_before_count sur 9, ldvlv_after_count sur 10, ldvlv_count sur 30000, ldvlv_offset sur 20400 et envoyez la demande au serveur. Le serveur retourne les 20 entrées précédentes dans la liste, plus la ldvlv_count de 30000 et une ldvlv_offset de 20400. Sachez qu’il est possible que le nombre d’entrées de la liste change entre l’estimation du client du nombre d’entrées et le serveur qui traite la recherche, ce qui affecte à son tour les décalages. Dans ce cas, l’entrée cible retournée peut ne pas être exactement l’entrée cible attendue par le client. Les demandes doivent être préparées à gérer cette incertitude.

N’oubliez pas qu’un contrôle de tri doit accompagner une demande de recherche VLV pour spécifier la liste ordonnée des entrées sur lesquelles la recherche VLV est effectuée. Les serveurs peuvent rejeter les recherches VLV effectuées sur des listes pour lesquelles ils n’ont pas d’index.