Suchen mithilfe von VLV

Active Directory unterstützt VLV-Suchen (Virtual List View). Diese Art der Suche ist speziell für große Resultsets konzipiert und ermöglicht es einer Anwendung, eine Teilmenge von Tausenden von Einträgen anzuzeigen, ohne tatsächlich jeden Eintrag abrufen zu müssen.

Es gibt zwei unterschiedliche Möglichkeiten, eine VLV-Suche zu verwenden. Die erste besteht darin, die Attribute für bestimmte Einträge basierend auf einem numerischen Offset abzurufen. Diese Methode ist nützlich beim Abrufen von Suchergebnissen als Reaktion auf einen Bildlaufvorgang.

Die zweite Möglichkeit zur Verwendung von VLV-Suchvorgängen besteht darin, nach einem Teil oder ganz eines Textattributes zu suchen und nur die Ergebnisse der Suche anzuzeigen. Ein Beispiel hierfür ist ein Adressbuch. Wenn der Benutzer ein "s" eingibt, kann die Anwendung eine VLV-Suche verwenden, um nach Einträgen zu suchen, die einen allgemeinen Namen haben, der mit "s" beginnt. Wenn der Benutzer dann ein "m" zu "s" hinzufügt, kann die Anwendung eine andere VLV-Suche verwenden, um nach Einträgen zu suchen, die einen allgemeinen Namen haben, der mit "sm" beginnt.

Weisen Sie ADSI an, das VLV-Steuerelement zu verwenden, um eine VLV-Suche durchzuführen. Rufen Sie hierzu die IDirectorySearch::SetSearchPreference-Methode mit einer ADS_SEARCHPREF_VLV Suchoption mit einem ADSTYPE_PROV_SPECIFIC-Wert auf. Der ADSTYPE_PROV_SPECIFIC-Wert ist ein Zeiger auf eine ADS_VLV-Struktur , die Daten zur Suche enthält. Die GetVLVItemCount-Beispielfunktion zeigt, wie sie beide Sucheinstellungen festlegen.

Alle VLV-Suchvorgänge müssen die serverseitige Ergebnissortierung verwenden, die durch Festlegen der ADS_SEARCHPREF_SORT_ON Sucheinstellung durchgeführt wird. Weitere Informationen zur ADS_SEARCHPREF_SORT_ON Sucheinstellung finden Sie unter Sortieren der Suchergebnisse mit IDirectorySearch.

Wenn eine VLV-Suche ausgeführt wird, wird eine bestimmte Menge von Metadaten zur Suche in einer Spalte zurückgegeben, die durch Aufrufen von IDirectorySearch::GetColumn mit dem ADS_VLV_RESPONSE-Bezeichner abgerufen wird. Diese Daten sind in einer ADS_VLV-Struktur enthalten. Besonders wichtig sind die Elemente dwContentCount und lpContextID . Das dwContentCount-Element enthält die Anzahl der Ergebnisse, die die VLV-Suchkriterien erfüllen. Dieser Wert kann als Schätzung der Gesamtzahl der Elemente verwendet werden, die für eine Suche dieses Typs zurückgegeben würden. Das lpContextID-Element enthält einen serverdefinierten Wert, der an die nächste Suche übergeben werden kann, um die Suche zu identifizieren. Die Verwendung der lpContextID kann die Suchleistung verbessern. Beachten Sie, dass die lpContextID ein serverdefinierter Wert ist und seine Länge im dwContextIDLength-Element enthalten ist. Dieser Puffer wird freigegeben, wenn die IDirectorySearch::FreeColumn-Methode aufgerufen wird. Daher muss der Aufrufer einen Puffer der entsprechenden Größe zuordnen und den Inhalt des Puffers zwischen Suchvorgängen kopieren und speichern.

Weitere Informationen zum LDAP-VLV-Steuerelement finden Sie unter Suchen mit dem LDAP-VLV-Steuerelement.

Weitere Informationen finden Sie unter

• Abrufen der Anzahl von Elementen
• Suchen nach Offset
• Suchen nach Zeichenfolge
• Beispielcode für die Verwendung einer VLV-Suche

Abrufen der Anzahl von Elementen

Führen Sie die folgenden Schritte aus, um eine Schätzung der Anzahl der Elemente zu erhalten, die für eine bestimmte Suche zurückgegeben werden.

1. Füllen Sie eine ADS_VLV-Struktur mit allen Null- oder NULL-Werten .

2. Füllen Sie eine ADS_SEARCHPREF_INFO mit den folgenden Werten aus.

   • Legen Sie den dwSearchPref-Member auf ADS_SEARCHPREF_VLV fest.
   • Legen Sie das vValue.dwType-Element auf ADSTYPE_PROV_SPECIFIC fest.
   • Legen Sie den vValue.ProviderSpecific.dwLength-Member auf die Größe der ADS_VLV-Struktur fest.
   • Legen Sie den vValue.ProviderSpecific.lpValue-Member auf die Adresse der ADS_VLV-Struktur aus Schritt 1 fest.

3. Füllen Sie eine ADS_SORTKEY Struktur aus, wie unter Sortieren der Suchergebnisse mit IDirectorySearch gezeigt, um nach dem gewünschten Attribut zu sortieren.

4. Füllen Sie einen weiteren ADS_SEARCHPREF_INFO , um die ADS_SORTKEY-Struktur den Sucheinstellungen hinzuzufügen, wie unter Sortieren der Suchergebnisse mit IDirectorySearch gezeigt.

5. Fügen Sie alle anderen gewünschten Sucheinstellungen hinzu, und rufen Sie IDirectorySearch::SetSearchPreference auf, um die Sucheinstellungen festzulegen.

6. Führen Sie die Suche mit IDirectorySearch::ExecuteSearch aus.

7. Rufen Sie die erste Ergebniszeile ab , indem Sie IDirectorySearch::GetFirstRow aufrufen.

8. Rufen Sie IDirectorySearch::GetColumn mit ADS_VLV_RESPONSE auf, um die VLV-Suchmetadaten abzurufen.

9. Wandeln Sie die pADsValues-ProviderSpecific.lpValue> der ADS_SEARCH_COLUMN-Struktur in einen ADS_VLV Strukturzeiger um. Das dwContentCount-Element dieser ADS_VLV-Struktur enthält die ungefähre Anzahl von Elementen, die von einer Suche dieses Typs zurückgegeben würden.

10. Wenn andere VLV-Suchvorgänge desselben Typs ausgeführt werden, erstellen Sie eine Kopie der lpContextID-Daten , und behalten Sie sie für die nächste VLV-Suche bei.

Die GetVLVItemCount-Beispielfunktion zeigt dies.

Suchen nach Offset

Eine Sache, die VLV-Suchvorgänge so schnell macht, ist, dass es möglich ist, nach einem bestimmten Ergebnis durch einen numerischen Offset zu suchen. Wenn beispielsweise bei einer Suche 10.000 Elemente zurückgegeben werden, ermöglicht eine VLV-Suche, die Informationen für ungefähr das 4072. Element abzurufen, ohne alle Elemente vor dem betreffenden Element abrufen zu müssen.

Offsets werden als Verhältnis zwischen dem Offset und der Inhaltsanzahl angegeben. Verhältnisse sind nützlich, da der Server möglicherweise keine genaue Schätzung der Anzahl von Einträgen in der Liste hat oder sich die Listengröße während der Durchsuchungszeit des Benutzers ändert. Da Sie den Anfang und das Ende der Liste angeben müssen, können Sie einen geschätzten Wert für die Inhaltsanzahl in der ersten Suchanforderung zusammen mit einem Offsetwert verwenden. Der Server verwendet diese Daten, um die entsprechenden Offsets innerhalb der Liste basierend auf seiner Idee der Inhaltsanzahl zu berechnen, die in seiner Antwort an den Client über das dwContentCount-Element der ADS_VLV-Struktur gesendet wird. Wenn Sie beispielsweise die Listengröße auf 3000 schätzen und den Offset als Listeneintrag 1500 verwenden möchten, würden Sie dwContentCount auf 3000 und dwOffset auf 1500 festlegen. Wenn der Server die tatsächliche Listengröße auf 4500 schätzt, berechnet er den Offset neu auf 2250 und gibt die neuen Schätzungen in dwContentCount und dwOffset zurück.

Die Beispielfunktion GetVLVItemText zeigt, wie dies geschieht.

Es ist auch möglich, mehrere Datenzeilen mit einem einzelnen Suchaufruf abzurufen. Dies geschieht in Schritt 1, indem Sie die Elemente dwBeforeCount und dwAfterCount der ADS_VLV Struktur entsprechend festlegen. Das dwBeforeCount-Element enthält die Anzahl der Elemente, die in der Liste vor dem betreffenden Element angezeigt werden, und das dwAfterCount-Element enthält die Anzahl der Elemente, die in der Liste nach dem betreffenden Element angezeigt werden. Beide Anzahlen schließen das Element selbst aus. Wenn Sie dwBeforeCount auf 10 und dwAfterCount auf 10 festlegen, werden insgesamt 21 Elemente zurückgegeben. Diese Option ermöglicht das Zwischenspeichern der Suchergebnisse auf der Clientseite.

Suchen nach Zeichenfolge

Es ist auch möglich, eine VLV-Suche zu verwenden, um Elemente zu finden, die über ein Zeichenfolgen-Attribut verfügen, dessen Wert mit der gesamten oder einem Teil einer Zeichenfolge übereinstimmt, ohne alle Elemente abrufen zu müssen. Der Zeichenfolgenabgleich wird für das Attribut ausgeführt, das in der ADS_SORTKEY-Struktur der ADS_SEARCHPREF_SORT_ON Sucheinstellung angegeben ist.

Führen Sie die folgenden Schritte aus, um nach einem bestimmten Element nach Zeichenfolge zu suchen.

1. Füllen Sie eine ADS_VLV-Struktur mit den folgenden Werten aus. Zusätzliche Elemente der Struktur sollten auf Null oder NULL festgelegt werden.

   • Legen Sie das element pszTarget auf einen Zeiger auf eine NULL-beendete Zeichenfolge fest, die die zu suchende Zeichenfolge enthält.
   • Legen Sie den lpContextID-Member auf die Adresse der Kopie des Kontext-ID-Puffers und die dwContextIDLength auf die Länge (in Bytes) des Kontext-ID-Puffers fest. Wenn keine Kontext-ID gespeichert wurde, sollten beide Member null oder NULL sein.

2. Legen Sie die Sucheinstellungen fest, wie in den Schritten 2 bis 5 der Prozedur Abrufen der Anzahl von Elementen gezeigt.

3. Führen Sie die Suche mit IDirectorySearch::ExecuteSearch aus.

4. Rufen Sie die erste Ergebniszeile ab , indem Sie IDirectorySearch::GetFirstRow aufrufen.

5. Rufen Sie IDirectorySearch::GetColumn mit dem Namen des abzurufenden Attributs auf, um die tatsächlichen Daten für das angeforderte Element abzurufen.

6. Rufen Sie IDirectorySearch::GetColumn mit ADS_VLV_RESPONSE auf, um die VLV-Suchmetadaten abzurufen.

7. Wandeln Sie die pADsValues-ProviderSpecific.lpValue> der ADS_SEARCH_COLUMN-Struktur in einen ADS_VLV Strukturzeiger um.

8. Erstellen Sie eine Kopie der lpContextID-Daten , und bewahren Sie sie für die nächste VLV-Suche auf. Bei Bedarf enthält das dwOffset-Element den einbasierten Index des ersten Elements, dessen Zeichenfolgenattribute mit dem in pszTarget angegebenen Wert beginnt.

Die Beispielfunktion GetVLVItemsByString veranschaulicht dies.

Ähnlich wie bei der Suche nach Index ist es auch möglich, mehrere Datenzeilen mit einem einzelnen Suchaufruf abzurufen. Dies wird auf die gleiche Weise erreicht, indem die DwBeforeCount - und dwAfterCount-Member der ADS_VLV-Struktur entsprechend festgelegt werden.