VLV を使用して検索する方法

Active Directory では、仮想リスト ビュー (VLV) 検索がサポートされています。 この検索スタイルは、特に大きな結果セット用に設計されており、アプリケーションでは、実際にすべてのエントリを取得しなくても、数千のエントリのサブセットを表示できます。

VLV 検索を使用する方法は 2 つあります。 1 つ目は、数値オフセットに基づいて特定のエントリの属性を取得する方法です。 このメソッドは、スクロール操作に応答して検索結果を取得する場合に便利です。

VLV 検索を使用する 2 番目の方法は、テキスト属性の一部またはすべてを検索し、検索結果のみを表示することです。 この使用例は、アドレス帳です。 ユーザーが "s" を入力した場合、アプリケーションは VLV 検索を使用して、"s" で始まる共通名を持つエントリを検索できます。 ユーザーが "s" に "m" を追加すると、アプリケーションは別の VLV 検索を使用して、"sm" で始まる共通名を持つエントリを検索できます。

VLV 検索を実行するには、VLV コントロールを使用するように ADSI に指示します。 これを行うには、 IDirectorySearch::SetSearchPreference メソッドを呼び出し、 ADSTYPE_PROV_SPECIFIC 値を持つ ADS_SEARCHPREF_VLV 検索オプションを指定します。 ADSTYPE_PROV_SPECIFIC値は、検索に関するデータを含むADS_VLV構造体へのポインターです。 GetVLVItemCount サンプル関数は、これらの両方の検索設定を設定する方法を示しています。

すべての VLV 検索では、サーバー側の結果の並べ替えを使用する必要があります。これは、 ADS_SEARCHPREF_SORT_ON 検索設定を設定することによって実行されます。 ADS_SEARCHPREF_SORT_ON検索設定の詳細については、「IDirectorySearch を使用した検索結果の並べ替え」を参照してください。

VLV 検索が実行されると、 IDirectorySearch::GetColumn を呼び出して取得された列に、検索に関する一定量のメタデータが ADS_VLV_RESPONSE 識別子で返されます。 このデータは、 ADS_VLV 構造体に含まれています。 特に重要なのが dwContentCount メンバーと lpContextID メンバーです。 dwContentCount メンバーには、VLV 検索条件を満たす結果の数が含まれます。 この値は、その型の検索で返されるアイテムの合計数の見積もりとして使用できます。 lpContextID メンバーには、次の検索に渡して検索を識別できるサーバー定義の値が含まれています。 lpContextID を使用すると、検索のパフォーマンスを向上させることができます。 lpContextID はサーバー定義値であり、その長さは dwContextIDLength メンバーに含まれていることに注意してください。 IDirectorySearch::FreeColumn メソッドが呼び出されると、このバッファーは解放されるため、呼び出し元は適切なサイズのバッファーを割り当て、検索間でバッファーの内容をコピーして保存する必要があります。

LDAP VLV コントロールの詳細については、LDAP VLV コントロールを使用した検索を参照してください。

詳細については、次を参照してください。

項目数の取得

特定の検索で返されるアイテムの数の見積もりを取得するには、次の手順を実行します。

  1. ADS_VLV構造体にゼロまたは NULL 値をすべて入力します。

  2. ADS_SEARCHPREF_INFOに次の値を入力します。

    • dwSearchPref メンバーをADS_SEARCHPREF_VLVに設定します
    • vValue.dwType メンバーをADSTYPE_PROV_SPECIFICに設定します。
    • vValue.ProviderSpecific.dwLength メンバーをADS_VLV構造体のサイズに設定します。
    • vValue.ProviderSpecific.lpValue メンバーを、手順 1 のADS_VLV構造体のアドレスに設定します。
  3. 検索結果を IDirectorySearch で並べ替える」に示すように、ADS_SORTKEY構造を入力して、目的の属性で並べ替えます。

  4. 検索結果を IDirectorySearch で並べ替える」に示すように、別のADS_SEARCHPREF_INFOを入力して、検索設定にADS_SORTKEY構造を追加します。

  5. 他の必要な検索設定を追加し、 IDirectorySearch::SetSearchPreference を呼び出して検索設定を設定します。

  6. IDirectorySearch::ExecuteSearch を使用して検索を実行します。

  7. IDirectorySearch::GetFirstRow を呼び出して、結果の最初の行を取得します。

  8. ADS_VLV_RESPONSEIDirectorySearch::GetColumn を呼び出して、VLV 検索メタデータを取得します。

  9. ADS_SEARCH_COLUMN構造体の pADsValues-ProviderSpecific.lpValue>ADS_VLV構造体ポインターにキャストします。 このADS_VLV構造体の dwContentCount メンバーには、その型の検索によって返される項目のおおよその数が含まれています。

  10. 同じ型の他の VLV 検索が実行される場合は、 lpContextID データのコピーを作成し、次の VLV 検索のために保持します。

GetVLVItemCount の例関数は、これを行う方法を示しています。

オフセットによる検索

VLV 検索を非常に迅速に行う 1 つは、数値オフセットで特定の結果を検索できる点です。 たとえば、検索で 10,000 個のアイテムが返される場合、VLV 検索を使用すると、問題の項目の前にあるすべての項目を取得しなくても、約 4072 番目の項目の情報を取得できます。

オフセットは、オフセットとコンテンツ数の比率として指定されます。 比率は、サーバーがリストに存在するエントリの数を正確に見積もっていないか、ユーザーが参照している間にリスト のサイズが変化する可能性があるために役立ちます。 リストの先頭と末尾を指定する必要があるため、最初の検索要求のコンテンツ数の推定値とオフセット値を使用できます。 サーバーはこのデータを使用して、コンテンツ数の考え方に基づいてリスト内の対応するオフセットを計算します。これは、ADS_VLV構造体の dwContentCount メンバーを介してクライアントへの応答で送信されます。 たとえば、リスト サイズを 3000 に見積もり、オフセットをリスト エントリ 1500 にする場合は、 dwContentCount を 3000 に、 dwOffset を 1500 に設定します。 サーバーは、実際のリスト サイズを 4500 と見積もった場合、オフセットを 2250 に再計算し、 dwContentCountdwOffset で新しい見積もりを返します。

注意

VLV 検索のすべての数値は近似値であり、絶対値には使用しないでください。 たとえば、100 の ration で 50 番目の項目に対して VLV 検索を発行した場合、正確な中間項目を取得する保証はありません。

オフセットで特定の項目を検索するには、次の手順を実行します。

  1. ADS_VLV構造体に次の値を入力します。 構造体の追加メンバーは、0 または NULL に設定する必要があります。

    • dwContentCount メンバーを、取得する項目の比率の最大値に設定します。
    • dwOffset メンバーを、取得する項目の dwContentCount に対する比率に設定します。
    • lpContextID メンバーをコンテキスト ID バッファーのコピーのアドレスに設定し、dwContextIDLength をコンテキスト ID バッファーの長さ (バイト単位) に設定します。 コンテキスト ID が保存されていない場合は、これらのメンバーの両方を 0 または NULL にする必要があります。
  2. 「項目数の取得」手順の手順 2 から 5 に示すように、検索設定を設定します。

  3. IDirectorySearch::ExecuteSearch を使用して検索を実行します。

  4. IDirectorySearch::GetFirstRow を呼び出して、結果の最初の行を取得します。

  5. 要求された項目の実際のデータを取得するために、取得する属性の名前を指定して IDirectorySearch::GetColumn を呼び出します。

  6. ADS_VLV_RESPONSEIDirectorySearch::GetColumn を呼び出して、VLV 検索メタデータを取得します。

  7. ADS_SEARCH_COLUMN構造体の pADsValues-ProviderSpecific.lpValue>ADS_VLV構造体ポインターにキャストします。

  8. lpContextID データのコピーを作成し、次の VLV 検索のために保持します。

 

GetVLVItemText の例関数は、これを行う方法を示しています。

1 回の検索呼び出しで複数行のデータを取得することもできます。 これは、手順 1 で、ADS_VLV構造体の dwBeforeCount メンバーと dwAfterCount メンバーを適切に設定することによって行われます。 dwBeforeCount メンバーには、対象のアイテムの前にリストに表示されるアイテムの数が含まれており、dwAfterCount メンバーには、対象のアイテムの後にリストに表示されるアイテムの数が含まれます。 どちらのカウントも項目自体を除外するため、 dwBeforeCount を 10 に設定し、 dwAfterCount を 10 に設定すると、合計 21 個の項目が返されます。 このオプションを使用すると、クライアント側で検索結果をキャッシュできます。

文字列による検索

また、VLV 検索を使用して、すべての項目を取得しなくても、値が文字列のすべてまたは一部に一致する文字列属性を持つ項目を検索することもできます。 文字列の照合は、ADS_SEARCHPREF_SORT_ON検索設定ADS_SORTKEY構造で指定された属性に対して実行されます。

文字列で特定の項目を検索するには、次の手順を実行します。

  1. ADS_VLV構造体に次の値を入力します。 構造体の追加メンバーは、0 または NULL に設定する必要があります。

    • pszTarget メンバーを、検索する文字列を含む NULL で終わる文字列へのポインターに設定します。
    • lpContextID メンバーをコンテキスト ID バッファーのコピーのアドレスに設定し、dwContextIDLength をコンテキスト ID バッファーの長さ (バイト単位) に設定します。 コンテキスト ID が保存されていない場合は、これらのメンバーの両方を 0 または NULL にする必要があります。
  2. 「項目数の取得」手順の手順 2 から 5 に示すように、検索設定を設定します。

  3. IDirectorySearch::ExecuteSearch を使用して検索を実行します。

  4. IDirectorySearch::GetFirstRow を呼び出して、結果の最初の行を取得します。

  5. 要求された項目の実際のデータを取得するために、取得する属性の名前を指定して IDirectorySearch::GetColumn を呼び出します。

  6. ADS_VLV_RESPONSEIDirectorySearch::GetColumn を呼び出して、VLV 検索メタデータを取得します。

  7. ADS_SEARCH_COLUMN構造体の pADsValues-ProviderSpecific.lpValue>ADS_VLV構造体ポインターにキャストします。

  8. lpContextID データのコピーを作成し、次の VLV 検索のために保持します。 必要に応じて、 dwOffset メンバーには、 pszTarget で指定された値で始まる文字列属性を持つ最初の項目の 1 から始まるインデックスが含まれます。

GetVLVItemsByString の例関数は、これを行う方法を示しています。

インデックスによる検索と同様に、1 回の検索呼び出しで複数のデータ行を取得することもできます。 これは、ADS_VLV構造体の dwBeforeCount メンバーと dwAfterCount メンバーを適切に設定することで、同じ方法で実現されます。