Come eseguire ricerche con VLV

Active Directory supporta le ricerche VLV (Virtual List View). Questo stile di ricerca è progettato specificamente per set di risultati di grandi dimensioni e consente a un'applicazione di visualizzare un subset di migliaia di voci senza dover effettivamente recuperare ogni voce.

È possibile usare una ricerca VLV in due modi diversi. Il primo consiste nel recuperare gli attributi per voci specifiche in base a un offset numerico. Questo metodo è utile quando si recuperano i risultati della ricerca in risposta a un'operazione di scorrimento.

Il secondo modo per usare le ricerche VLV consiste nel cercare parte o in tutto un attributo testuale e visualizzare solo i risultati della ricerca. Un esempio di utilizzo di questa rubrica è una rubrica. Se l'utente digita "s", l'applicazione può usare una ricerca VLV per cercare voci con un nome comune che inizia con "s". Se l'utente aggiunge quindi "m" a "s", l'applicazione può usare un'altra ricerca VLV per cercare voci con un nome comune che inizia con "sm".

Per eseguire una ricerca VLV, indicare ad ADSI di usare il controllo VLV. A tale scopo, chiamare il metodo IDirectorySearch::SetSearchPreference con un'opzione di ricerca ADS_edizione StandardARCHPREF_VLV con un valore ADSTYPE_PROV_SPECIFIC. Il valore ADSTYPE_PROV_SPECIFIC è un puntatore a una struttura ADS_VLV che contiene dati sulla ricerca. La funzione di esempio GetVLVItemCount mostra come impostare entrambe le preferenze di ricerca.

Tutte le ricerche VLV devono usare l'ordinamento dei risultati sul lato server, che viene eseguito impostando la preferenza di ricerca ADS_edizione StandardARCHPREF_SORT_ON. Per altre informazioni sulla preferenza di ricerca ADS_edizione StandardARCHPREF_SORT_ON, vedere Ordinamento dei risultati della ricerca con IDirectorySearch.

Quando viene eseguita una ricerca VLV, viene restituita una determinata quantità di metadati sulla ricerca in una colonna recuperata chiamando IDirectorySearch::GetColumn con l'identificatore ADS_VLV_RESPONedizione Standard. Questi dati sono contenuti in una struttura ADS_VLV. Di particolare importanza sono i membri dwContentCount e lpContextID . Il membro dwContentCount conterrà il numero di risultati che soddisfano i criteri di ricerca VLV. Questo valore può essere usato come stima del numero totale di elementi che verrebbero restituiti per una ricerca di tale tipo. Il membro lpContextID contiene un valore definito dal server che può essere passato alla ricerca successiva per identificare la ricerca. L'uso di lpContextID può migliorare le prestazioni di ricerca. Tenere presente che lpContextID è un valore definito dal server e la relativa lunghezza è contenuta nel membro dwContextIDLength. Questo buffer viene liberato quando viene chiamato il metodo IDirectorySearch::FreeColumn , quindi il chiamante deve allocare un buffer delle dimensioni appropriate e copiare e salvare il contenuto del buffer tra le ricerche.

Per altre informazioni sul controllo VLV LDAP, vedere Ricerca con il controllo VLV LDAP.

Per altre informazioni, vedi:

• Recupero del numero di elementi
• Ricerca in base all'offset
• Ricerca in base a stringhe
• Codice di esempio per l'uso di una ricerca VLV

Recupero del numero di elementi

Per ottenere una stima del numero di elementi che verranno restituiti per una ricerca specifica, seguire questa procedura.

1. Riempire una struttura ADS_VLV con tutti i valori zero o NULL .

2. Compilare un ADS_edizione StandardARCHPREF_INFO con i valori seguenti.

   • Impostare il membro dwSearchPref su ADS_edizione StandardARCHPREF_VLV.
   • Impostare il membro vValue.dwType su ADSTYPE_PROV_SPECIFIC.
   • Impostare il membro vValue.ProviderSpecific.dwLength sulle dimensioni della struttura ADS_VLV .
   • Impostare il membro vValue.ProviderSpecific.lpValue sull'indirizzo della struttura ADS_VLV del passaggio 1.

3. Compilare una struttura ADS_SORTKEY come illustrato in Ordinamento dei risultati della ricerca con IDirectorySearch per ordinare l'attributo desiderato.

4. Compilare un altro ADS_edizione StandardARCHPREF_INFO per aggiungere la struttura ADS_SORTKEY alle preferenze di ricerca, come illustrato in Ordinamento dei risultati della ricerca con IDirectorySearch.

5. Aggiungere eventuali altre preferenze di ricerca desiderate e chiamare IDirectorySearch::SetSearchPreference per impostare le preferenze di ricerca.

6. Eseguire la ricerca con IDirectorySearch::ExecuteSearch.

7. Ottenere la prima riga di risultati chiamando IDirectorySearch::GetFirstRow.

8. Chiamare IDirectorySearch::GetColumn con ADS_VLV_RESPONedizione Standard per ottenere i metadati di ricerca VLV.

9. Eseguire il cast della struttura pADsValues-ProviderSpecific.lpValue> della struttura ADS_edizione StandardARCH_COLUMN a un puntatore alla struttura ADS_VLV. Il membro dwContentCount di questa struttura ADS_VLV contiene il numero approssimativo di elementi restituiti da una ricerca di quel tipo.

10. Se verranno eseguite altre ricerche VLV dello stesso tipo, creare una copia dei dati lpContextID e conservarla per la ricerca VLV successiva.

La funzione di esempio GetVLVItemCount mostra come eseguire questa operazione.

Ricerca in base all'offset

Una cosa che rende le ricerche VLV così veloci è che è possibile cercare un risultato specifico in base a un offset numerico. Ad esempio, se una ricerca genera 10.000 elementi restituiti, una ricerca VLV consente di ottenere le informazioni per circa il 4072nd elemento senza dover recuperare tutti gli elementi prima dell'elemento in questione.

Gli offset vengono specificati come rapporto tra l'offset e il conteggio dei contenuti. Le proporzioni sono utili perché il server potrebbe non avere una stima accurata del numero di voci presenti nell'elenco o la dimensione dell'elenco può essere modificata durante il periodo di esplorazione dell'utente. Poiché è necessario indicare l'inizio e la fine dell'elenco, è possibile usare un valore stimato per il conteggio dei contenuti nella prima richiesta di ricerca, insieme a un valore di offset. Il server usa questi dati per calcolare gli offset corrispondenti all'interno dell'elenco, in base all'idea del conteggio dei contenuti, che viene inviato nella risposta al client tramite il membro dwContentCount della struttura ADS_VLV . Ad esempio, se si stima che le dimensioni dell'elenco siano pari a 3000 e si vuole che l'offset sia una voce di elenco 1500, impostare dwContentCount su 3000 e dwOffset su 1500. Se il server stima le dimensioni effettive dell'elenco pari a 4500, ricalcola l'offset su 2250 e restituisce le nuove stime in dwContentCount e dwOffset.

La funzione di esempio GetVLVItemText mostra come eseguire questa operazione.

È anche possibile recuperare più righe di dati con una singola chiamata di ricerca. Questa operazione viene eseguita nel passaggio 1 impostando i membri dwBeforeCount e dwAfterCount della struttura ADS_VLV in modo appropriato. Il membro dwBeforeCount contiene il numero di elementi visualizzati nell'elenco prima dell'elemento in questione e il membro dwAfterCount contiene il numero di elementi visualizzati nell'elenco dopo l'elemento in questione. Entrambi questi conteggi escludono l'elemento stesso, quindi impostando dwBeforeCount su 10 e dwAfterCount su 10 verrà restituito un totale di 21 elementi. Questa opzione abilita la memorizzazione nella cache dei risultati della ricerca sul lato client.

Ricerca in base a stringhe

È anche possibile usare una ricerca VLV per trovare gli elementi con un attributo stringa il cui valore corrisponde a tutta o parte di una stringa senza dover recuperare tutti gli elementi. La corrispondenza di stringhe viene eseguita sull'attributo specificato nella struttura ADS_SORTKEY della preferenza di ricerca ADS_edizione StandardARCHPREF_SORT_ON.

Per cercare un particolare elemento per stringa, seguire questa procedura.

1. Compilare una struttura ADS_VLV con i valori seguenti. I membri aggiuntivi della struttura devono essere impostati su zero o NULL.

   • Impostare il membro pszTarget su un puntatore a una stringa con terminazione NULL contenente la stringa da cercare.
   • Impostare il membro lpContextID sull'indirizzo della copia del buffer ID di contesto e dwContextIDLength sulla lunghezza, in byte, del buffer ID di contesto. Se non è stato salvato alcun ID di contesto, entrambi i membri devono essere zero o NULL.

2. Impostare le preferenze di ricerca come illustrato nei passaggi da 2 a 5 della procedura Recupero del numero di elementi.

3. Eseguire la ricerca con IDirectorySearch::ExecuteSearch.

4. Ottenere la prima riga di risultati chiamando IDirectorySearch::GetFirstRow.

5. Chiamare IDirectorySearch::GetColumn con il nome dell'attributo da recuperare per ottenere i dati effettivi per l'elemento richiesto.

6. Chiamare IDirectorySearch::GetColumn con ADS_VLV_RESPONedizione Standard per ottenere i metadati di ricerca VLV.

7. Eseguire il cast della struttura pADsValues-ProviderSpecific.lpValue> della struttura ADS_edizione StandardARCH_COLUMN a un puntatore alla struttura ADS_VLV.

8. Creare una copia dei dati lpContextID e conservarla per la ricerca VLV successiva. Se necessario, il membro dwOffset contiene l'indice in base uno del primo elemento il cui attributo stringa inizia con il valore specificato in pszTarget.

La funzione di esempio GetVLVItemsByString mostra come eseguire questa operazione.

Analogamente alla ricerca in base all'indice, è anche possibile recuperare più righe di dati con una singola chiamata di ricerca. Questa operazione viene eseguita nello stesso modo impostando i membri dwBeforeCount e dwAfterCount della struttura ADS_VLV in modo appropriato.