So suchen Sie mithilfe von VLV

Active Directory unterstützt Suchvorgänge in der virtuellen Listenansicht (VLV). Diese Suchart ist speziell für große Resultsets konzipiert und ermöglicht es einer Anwendung, eine Teilmenge von Tausenden von Einträgen anzuzeigen, ohne jeden Eintrag abrufen zu müssen.

Es gibt zwei verschiedene Möglichkeiten, wie eine VLV-Suche verwendet werden kann. Die erste besteht darin, die Attribute für bestimmte Einträge basierend auf einem numerischen Offset abzurufen. Diese Methode ist hilfreich beim Abrufen von Suchergebnissen als Reaktion auf einen Bildlaufvorgang.

Die zweite Möglichkeit zum Verwenden von VLV-Suchvorgängen besteht darin, nach einem Teil oder allen Textattributen zu suchen und nur die Ergebnisse der Suche anzuzeigen. Eine Beispielverwendung hierfür ist ein Adressbuch. Wenn der Benutzer einen "s" eingibt, kann die Anwendung eine VLV-Suche verwenden, um nach Einträgen zu suchen, die mit "s" beginnen. Wenn der Benutzer dann dem "s" ein "m" hinzufügt, kann die Anwendung eine weitere VLV-Suche verwenden, um nach Einträgen zu suchen, die mit "sm" beginnen.

Um eine VLV-Suche auszuführen, weisen Sie ADSI an, das VLV-Steuerelement zu verwenden. 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 Beispielfunktion GetVLVItemCount zeigt, wie beide Sucheinstellungen festgelegt werden.

Alle VLV-Suchvorgänge müssen die serverseitige Ergebnissortierung verwenden, die durch Festlegen der ADS_SEARCHPREF_SORT_ON Sucheinstellung ausgefü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. Von besonderer Bedeutung sind die dwContentCount - und lpContextID-Member . Das dwContentCount-Element enthält die Anzahl der Ergebnisse, die den VLV-Suchkriterien entsprechen. Dieser Wert kann als Schätzung der Gesamtzahl der Elemente verwendet werden, die für eine Suche dieses Typs zurückgegeben werden. 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 zuweisen 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 der Elemente

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

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

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

    • Legen Sie das dwSearchPref-Element auf ADS_SEARCHPREF_VLV fest.
    • Legen Sie das vValue.dwType-Element auf ADSTYPE_PROV_SPECIFIC fest.
    • Legen Sie das vValue.ProviderSpecific.dwLength-Element auf die Größe der ADS_VLV Struktur fest.
    • Legen Sie das vValue.ProviderSpecific.lpValue-Element auf die Adresse der ADS_VLV Struktur aus Schritt 1 fest.
  3. Füllen Sie eine ADS_SORTKEY Struktur aus, wie in der Sortierung der Suchergebnisse mit IDirectorySearch dargestellt, um nach dem gewünschten Attribut zu sortieren.

  4. Füllen Sie eine weitere ADS_SEARCHPREF_INFO aus, um die ADS_SORTKEY Struktur den Sucheinstellungen hinzuzufügen, wie in der Sortierung 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. Cast the pADsValues-ProviderSpecific.lpValue> of the ADS_SEARCH_COLUMN structure to an ADS_VLV structure pointer. Das dwContentCount-Element dieser ADS_VLV Struktur enthält die ungefähre Anzahl von Elementen, die von einer Suche dieses Typs zurückgegeben werden.

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

Die Beispielfunktion GetVLVItemCount zeigt, wie dies geschieht.

Suchen nach Offset

Eine Sache, die VLV-Suchvorgänge so schnell macht, dass es möglich ist, durch einen numerischen Offset nach einem bestimmten Ergebnis zu suchen. Wenn z. B. eine Suche zu 10.000 zurückgegebenen Elementen führen würde, ermöglicht eine VLV-Suche das Abrufen der Informationen für ungefähr das 4072. Element, ohne alle Elemente vor dem betreffenden Element abrufen zu müssen.

Offsets werden als Verhältnis zwischen dem Offset und der Inhaltsanzahl angegeben. Die Verhältnisverhältnisse sind nützlich, da der Server möglicherweise keine genaue Schätzung der Anzahl der Einträge hat, die in der Liste vorhanden sind, oder die Listengröße kann während des Durchsuchens des Benutzers geändert werden. 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 der Idee der Inhaltsanzahl zu berechnen, die in seiner Antwort auf den Client über den dwContentCount-Member der ADS_VLV-Struktur gesendet wird. Wenn Sie beispielsweise die Listengröße auf 3000 schätzen und möchten, dass der Offset listeneintrag 1500 sein soll, legen Sie dwContentCount auf 3000 und dwOffset auf 1500 fest. Wenn der Server die tatsächliche Listengröße auf 4500 geschätzt, berechnet er den Offset auf 2250 neu und gibt die neuen Schätzungen in dwContentCount und dwOffset zurück.

Hinweis

Alle numerischen Werte in einer VLV-Suche sind Annäherungen und sollten nicht für absolute Werte verwendet werden. Wenn Sie z. B. eine VLV-Suche nach dem 50. Element in einer Ration von 100 ausgeben, sind Sie nicht garantiert, das genaue mittlere Element zu erhalten.

Führen Sie die folgenden Schritte aus, um nach einem bestimmten Element nach einem Offset 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 dwContentCount-Element auf den maximalen Wert des zu abrufenden Elements fest.
    • Legen Sie das dwOffset-Element auf das Verhältnis relativ zu dwContentCount des abzurufenden Elements oder Elements fest.
    • Legen Sie das lpContextID-Element auf die Adresse der Kopie des Kontext-ID-Puffers und der dwContextIDLength auf die Länge des Kontext-ID-Puffers fest. Wenn keine Kontext-ID gespeichert wurde, sollten beide Elemente null oder NULL sein.
  2. Legen Sie die Sucheinstellungen fest, wie in den Schritten 2 bis 5 des Abrufens der Anzahl der Elemente dargestellt.

  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 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. Cast the pADsValues-ProviderSpecific.lpValue> of the ADS_SEARCH_COLUMN structure to an ADS_VLV structure pointer.

  8. Erstellen Sie eine Kopie der lpContextID-Daten , und bewahren Sie sie für die nächste VLV-Suche auf.

 

Die Beispielfunktion "GetVLVItemText " zeigt, wie Dies geschieht.

Es ist auch möglich, mehrere Datenzeilen mit einem einzelnen Suchaufruf abzurufen. Dies erfolgt in Schritt 1, indem sie die dwBeforeCount - und dwAfterCount-Member 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 nach dem betreffenden Element in der Liste angezeigt werden. Beide Anzahlen schließen das Element selbst aus, sodass das Festlegen von dwBeforeCount auf 10 und dwAfterCount auf 10 insgesamt 21 Elemente führt. 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 Zeichenfolgenattribute verfügen, dessen Wert allen oder teil einer Zeichenfolge entspricht, ohne alle Elemente abrufen zu müssen. Der Zeichenfolgenabgleich wird mit dem attribut ausgeführt, das in der ADS_SORTKEY Struktur der sucheinstellung ADS_SEARCHPREF_SORT_ON 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 pszTarget-Element auf einen Zeiger auf eine NULL-beendete Zeichenfolge fest, die die zu suchende Zeichenfolge enthält.
    • Legen Sie das lpContextID-Element auf die Adresse der Kopie des Kontext-ID-Puffers und der dwContextIDLength auf die Länge des Kontext-ID-Puffers fest. Wenn keine Kontext-ID gespeichert wurde, sollten beide Elemente null oder NULL sein.
  2. Legen Sie die Sucheinstellungen fest, wie in den Schritten 2 bis 5 des Abrufens der Anzahl der Elemente dargestellt.

  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 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. Cast the pADsValues-ProviderSpecific.lpValue> of the ADS_SEARCH_COLUMN structure to an ADS_VLV structure pointer.

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

Die Beispielfunktion "GetVLVItemsByString" zeigt, wie dies ausgeführt wird.

Ähnlich wie bei der Suche nach Index ist es auch möglich, mehrere Datenzeilen mit einem einzigen Suchaufruf abzurufen. Dies erfolgt auf dieselbe Weise, indem Sie die Elemente "dwBeforeCount " und "dwAfterCount " der ADS_VLV struktur entsprechend festlegen.