LDAPVLVInfo-Struktur (winldap.h)

Die LDAPVLVInfo-Struktur wird verwendet, um die Suchparameter für ein VLV-Anforderungssteuerelement (Virtual List View) (LDAP_CONTROL_VLVREQUEST) einzurichten.

Die LDAPVLVInfo-Struktur kann auch von Anwendungen verwendet werden, um die Zustandsdaten zu verwalten, die einer Reihe von VLV-Client/Server-Interaktionen zugeordnet sind.

Syntax

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;

Member

ldvlv_version

Gibt die Version der LDAPVLVInfo-Struktur an. Dies sollte immer auf den Wert LDAP_VLVINFO_VERSION (1) festgelegt werden.

ldvlv_before_count

Gibt die Anzahl der Einträge vor dem Zieleintrag an, die der Client in den Listenergebnissen vom Server zurücksenden soll. Dieses Feld entspricht dem beforeCount-Element des BER-codierten LDAP_CONTROL_VLVREQUEST-Steuerelements .

ldvlv_after_count

Gibt die Anzahl der Einträge nach dem Zieleintrag an, den der Client den Server anweist, die Listenergebnisse zurückzusenden. Dieses Feld entspricht dem afterCount-Element des BER-codierten LDAP_CONTROL_VLVREQUEST-Steuerelements .

ldvlv_offset

Gibt ein Verhältnis zwischen dem Offsetwert und der Inhaltsanzahl an. Überlegen Sie beispielsweise, ob ein Benutzer die Bildlaufleiste zieht, um Einträge in der Mitte der Liste anzuzeigen. Wenn der Client schätzt, dass die gesamte Liste 100 Einträge enthält, berechnet er zum Anzeigen der mittleren Liste den Offset auf 50, sodass der Client diesen Offsetwert mit 100 als Inhaltsanzahl an den Server sendet, der im ldvlv_count-Member gesendet wird. Wenn der Server diese Daten empfängt, hat er möglicherweise tatsächlich die Inhaltsanzahl auf 500 berechnet, sodass er den Offset berechnet, um das vom Client angeforderte Ziel zu finden, wobei die folgende Formel verwendet wird:

Si = Sc * (Ci / Cc)

where

Si ist der tatsächliche Listenoffset, der vom Server verwendet wird

Sc ist die Serverschätzung für die Inhaltsanzahl

Ci ist der vom Client übermittelte Offset

Cc ist die anzahl der vom Client übermittelten Inhalte

Wenn der Client einen Offsetwert von 1 (1) verwendet, gibt dies an, dass das Ziel der erste Eintrag in der Liste ist. Wenn der Client einen Offsetwert verwendet, der ldvlv_count entspricht, ist das Element der letzte Eintrag in der Liste. Der Offset entspricht null (0), wenn ldvlv_count gleich 0 ist. Dies wäre der letzte Eintrag in der Liste.

Offsets werden nur verwendet, wenn die Suche nicht auf einem Attributwert basiert, daher muss ldvlv_attrvalueNULL sein. Dieses Feld entspricht dem Offsetelement innerhalb des BER-codierten LDAP_CONTROL_VLVREQUEST-Steuerelements .

ldvlv_count

Gibt die Inhaltsanzahl der Liste an. Eine Schätzung der Inhaltsanzahl wird vom Client an den Server gesendet, wenn eine Suchanforderung gesendet wird, damit der Server einen Offsetwert berechnen kann. Der Server gibt eine eigene Berechnung der Inhaltsanzahl an den Client in seiner Antwort zurück. Wenn der Client keine Schätzung für die Inhaltsanzahl hat, sendet er null (0), was angibt, dass der Server eine eigene Schätzung für die Inhaltsanzahl verwenden soll. Dieses Element wird mit ldvlv_offset verwendet. Da die Inhaltsanzahl nur erforderlich ist, wenn die Suche nicht auf einem Attributwert basiert, muss der ldvlv_attrvalue Member NULL sein. Dieses Feld entspricht dem contentCount-Element innerhalb des BER-codierten LDAP_CONTROL_VLVREQUEST-Steuerelements und dem contentCount-Element innerhalb des BER-codierten LDAP_CONTROL_VLVRESPONSE-Steuerelements .

ldvlv_attrvalue

Stellt einen Attributwert als Zieleintrag für die Suche bereit. Der Server vergleicht diesen Member mit Werten, die denselben Attributtyp aufweisen, wie im sk_attrtype Member der LDAPSortKey-Struktur angegeben. Wenn ein Offset verwendet wird, muss dieser Member NULL sein. Dieses Element entspricht dem assertionValue-Element des BER-codierten LDAP_CONTROL_VLVREQUEST-Steuerelements .

ldvlv_context

Stellt die Kontext-ID bereit, die vom Server zugewiesen wird, um diesen Suchvorgang zu identifizieren. Dies ist ein undurchsichtiges "Cookie", das vom Server verwendet wird, um den aktuellen VLV-Vorgang intern nachzuverfolgen. Beim ersten Aufruf des Suchvorgangs mithilfe des VLV-Steuerelements sollte dieser Parameter auf NULL festgelegt werden. Der Server gibt möglicherweise einen Wert in der LDAP_CONTROL_VLVRESPONSE-Nachricht zurück. Dieser "Cookie"-Wert sollte beim nächsten Aufruf einer Suchfunktion, die für eine bestimmte VLV-Liste ausgeführt wird, an den Server zurückgegeben werden.

ldvlv_extradata

Dieses Feld ist für die anwendungsspezifische Verwendung reserviert und wird nicht von der ldap_create_vlv_control-Funktion verwendet. Es hat keine Auswirkungen auf das steuerelement, das erstellt wird.

Hinweise

Es gibt zwei Methoden zum Berechnen des Ziels einer VLV-Suche: mithilfe eines Attributwerts oder eines Offsets. Je nachdem, welchen Suchtyp Sie auswählen, werden verschiedene Elemente dieser Struktur verwendet. Beide Methoden erfordern die Eingabe von Werten für die ldvlv_before_count - und ldvlv_after_count-Member . Geben Sie eine Listeninhaltsanzahl in ldvlv_count an. Wenn Sie diesen Wert nicht kennen, verwenden Sie null (0), damit der Server sie berechnet.

  • Suchen mit Attributwerten

    Wenn Sie beispielsweise nach Jeff Smith suchen möchten, und Sie den Attributtyp für diesen Wert kennen, legen Sie den Attributtyp im sk_attrtype Element der LDAPSortKey-Struktur und den Attributwert in ldvlv_attrvalue fest, um eine wertbasierte Suche durchzuführen. Das ldvlv_offset-Members wird für diese Art der Suche ignoriert, sodass es nicht erforderlich ist, ihn festzulegen.

    Beispielsweise, um eine Suche mit dem Buchstaben J durchzuführen. Um 20 Ergebnisse abzurufen, legen Sie ldvlv_before_count auf 9, ldvlv_after_count auf 10 und ldvlv_attrvalue auf J fest. Der Server findet den ersten Eintrag in der Liste, der nicht kleiner als J ist, z. B. Jeff Smith, und gibt die neun vorherigen Einträge, den Zieleintrag und die vorangehenden 10 Einträge zurück. Der Server gibt eine ldvlv_count von 30000 und einen ldvlv_offset von 4053 im LDAP_CONTROL_VLVRESPONSE-Steuerelement zurück. dies setzt voraus, dass Jeff Smith die Nummer 4053 in der Liste hat. Der Server gibt möglicherweise nur wenige Einträge zurück, die vor und/oder nach dem Zieleintrag angefordert wurden, wenn nicht genügend Einträge in der Liste vorhanden sind, um die Anforderung zu erfüllen. Wenn beispielsweise vor dem ersten "J"-Eintrag nur zwei Einträge insgesamt vorhanden waren, konnte der Server neun vorangehende Einträge nicht zurückgeben.

  • Suchen mit Offsets

    Um Offsets für Ihre Suche zu verwenden, legen Sie einen Offset in ldvlv_offset fest, und legen Sie ldvlv_attrvalue auf NULL fest. Legen Sie auch den Attributtyp im sk_attrtype Member des LDAPSortKey fest, aber dieses Mal ist das Ziel ein Offset innerhalb der Liste der Einträge für diesen Attributtyp und nicht ein bestimmter Attributwert.

    Beispielsweise, um 68 Prozent der Suchergebnisse als Ziel für die Suche zu verwenden. Wenn die ldvlv_count 30000 ist, sind die 68 Prozent von 30000 20400. Um 20 Ergebnisse abzurufen, legen Sie ldvlv_before_count auf 9, ldvlv_after_count auf 10, ldvlv_count auf 30000, ldvlv_offset auf 20400 fest, und senden Sie die Anforderung an den Server. Der Server gibt die vorherigen 20 Einträge in der Liste sowie die ldvlv_count 30000 und einen ldvlv_offset 20400 zurück. Beachten Sie, dass sich die Anzahl der Einträge in der Liste zwischen der Clientschätzung der Anzahl der Einträge und dem Server, der die Suche verarbeitet, ändern kann, was sich wiederum auf die Offsets auswirkt. In diesem Fall ist der zurückgegebene Zieleintrag möglicherweise nicht genau der Zieleintrag, den der Client erwartet hat. Anwendungen müssen darauf vorbereitet sein, mit dieser Unsicherheit umzugehen.

Beachten Sie, dass ein Sortiersteuerelement eine VLV-Suchanforderung begleiten muss, um die sortierte Liste der Einträge anzugeben, für die die VLV-Suche ausgeführt wird. Server können VLV-Suchvorgänge für Listen ablehnen, für die sie keine Indizes aufweisen.

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client) Windows Vista
Unterstützte Mindestversion (Server) Windows Server 2008
Kopfzeile winldap.h

Weitere Informationen

LDAPControl

LDAP_CONTROL_VLVREQUEST

LDAP_CONTROL_VLVRESPONSE

Suchen mit dem LDAP-VLV-Steuerelement

ldap_create_sort_control

ldap_create_vlv_control

ldap_parse_vlv_control

ldap_search_ext

ldap_search_ext_s