VLV를 사용하여 검색하는 방법

  • 아티클

Active Directory는 VLV(가상 목록 보기) 검색을 지원합니다. 이 검색 스타일은 큰 결과 집합을 위해 특별히 설계되었으며 애플리케이션이 실제로 모든 항목을 검색할 필요 없이 수천 개의 항목 하위 집합을 표시할 수 있도록 합니다.

VLV 검색을 사용할 수 있는 두 가지 방법이 있습니다. 첫 번째는 숫자 오프셋을 기반으로 특정 항목의 특성을 검색하는 것입니다. 이 메서드는 스크롤 작업에 대한 응답으로 검색 결과를 검색할 때 유용합니다.

VLV 검색을 사용하는 두 번째 방법은 텍스트 특성의 일부 또는 전체를 검색하고 검색 결과만 표시하는 것입니다. 이를 사용하는 예제는 주소록입니다. 사용자가 "s"를 입력하는 경우 애플리케이션은 VLV 검색을 사용하여 "s"로 시작하는 공통 이름의 항목을 검색할 수 있습니다. 사용자가 "s"에 "m"을 추가하는 경우 애플리케이션은 다른 VLV 검색을 사용하여 "sm"으로 시작하는 공통 이름의 항목을 검색할 수 있습니다.

VLV 검색을 수행하려면 ADSI에 VLV 컨트롤을 사용하도록 지시합니다. 이렇게 하려면 ADSTYPE_PROV_SPECIFIC 값이 있는 ADS_SEARCHPREF_VLV 검색 옵션을 사용하여 IDirectorySearch::SetSearchPreference 메서드를 호출합니다. ADSTYPE_PROV_SPECIFIC 값은 검색에 대한 데이터를 포함하는 ADS_VLV 구조체에 대한 포인터입니다. GetVLVItemCount 예제 함수는 이러한 검색 기본 설정을 모두 설정하는 방법을 보여 줍니다.

모든 VLV 검색은 ADS_SEARCHPREF_SORT_ON 검색 기본 설정을 통해 수행되는 서버 쪽 결과 정렬을 사용해야 합니다. ADS_SEARCHPREF_SORT_ON 검색 기본 설정에 대한 자세한 내용은 IDirectorySearch를 사용하여 검색 결과 정렬을 참조하세요.

VLV 검색이 수행되면 검색에 대한 일정량의 메타데이터가 ADS_VLV_RESPONSE 식별자를 사용하여 IDirectorySearch::GetColumn을 호출하여 검색되는 열에 반환됩니다. 이 데이터는 ADS_VLV 구조에 포함되어 있습니다. 특히 중요도는 dwContentCount 및 lpContextID 멤버입니다. dwContentCount 멤버에는 VLV 검색 조건을 충족하는 결과 수가 포함됩니다. 이 값은 해당 형식의 검색에 대해 반환될 총 항목 수의 추정값으로 사용할 수 있습니다. lpContextID 멤버에는 검색을 식별하기 위해 다음 검색에 전달할 수 있는 서버 정의 값이 포함되어 있습니다. lpContextID를 사용하면 검색 성능을 향상시킬 수 있습니다. lpContextID는 서버 정의 값이며 해당 길이는 dwContextIDLength 멤버에 포함되어 있습니다. 이 버퍼는 IDirectorySearch::FreeColumn 메서드가 호출되면 해제되므로 호출자는 적절한 크기의 버퍼를 할당하고 검색 간에 버퍼의 내용을 복사하여 저장해야 합니다.

LDAP VLV 컨트롤에 대한 자세한 내용은 LDAP VLV 컨트롤을 사용하여 검색을 참조하세요.

자세한 내용은 다음을 참조하세요.

항목 수 가져오기

특정 검색에 대해 반환될 항목 수를 예상하려면 다음 단계를 수행합니다.

  1. ADS_VLV 구조체를 모두 0 또는 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_RESPONSE사용하여 IDirectorySearch::GetColumn을 호출하여 VLV 검색 메타데이터를 가져옵니다.

  9. ADS_SEARCH_COLUMN 구조체의 pADsValues-ProviderSpecific.lpValue>를 ADS_VLV 구조체 포인터로 캐스팅합니다. 이 ADS_VLV 구조체의 dwContentCount 멤버에는 해당 형식의 검색에서 반환되는 대략적인 항목 수가 포함됩니다.

  10. 동일한 형식의 다른 VLV 검색이 수행되는 경우 lpContextID 데이터의 복사본을 만들고 다음 VLV 검색을 위해 유지합니다.

GetVLVItemCount 예제 함수는 이 작업을 수행하는 방법을 보여줍니다.

오프셋으로 검색

VLV 검색을 매우 빠르게 만드는 한 가지는 숫자 오프셋으로 특정 결과를 검색할 수 있다는 것입니다. 예를 들어 검색으로 인해 10,000개 항목이 반환되는 경우 VLV 검색을 통해 해당 항목 앞에 있는 모든 항목을 검색하지 않고도 약 4072번째 항목에 대한 정보를 가져올 수 있습니다.

오프셋은 오프셋과 콘텐츠 수 사이의 비율로 지정됩니다. 비율은 서버에 목록에 있는 항목 수에 대한 정확한 추정치가 없거나 사용자가 검색하는 동안 목록 크기가 변경될 수 있기 때문에 유용합니다. 목록의 시작과 끝을 나타내야 하므로 첫 번째 검색 요청의 콘텐츠 수에 대한 예상 값과 오프셋 값을 사용할 수 있습니다. 서버는 이 데이터를 사용하여 ADS_VLV 구조의dwContentCount 멤버를 통해 클라이언트에 대한 응답으로 전송되는 콘텐츠 수의 아이디어에 따라 목록 내의 해당 오프셋을 계산합니다. 예를 들어 목록 크기를 3000으로 추정하고 오프셋을 목록 항목 1500으로 설정하려는 경우 dwContentCount 를 3000으로 설정하고 dwOffset 을 1500으로 설정합니다. 서버에서 실제 목록 크기를 4500으로 추정하는 경우 오프셋을 2250으로 다시 계산하고 dwContentCount 및 dwOffset에서 새 예상값을 반환합니다.

참고

VLV 검색의 모든 숫자 값은 근사치이며 절대 값에 사용하면 안 됩니다. 예를 들어 100의 배급에서 50번째 항목에 대한 VLV 검색을 실행하면 정확한 중간 항목을 가져올 수 없습니다.

오프셋별로 특정 항목을 검색하려면 다음 단계를 수행합니다.

  1. ADS_VLV 구조체를 다음 값으로 채웁니다. 구조체의 추가 멤버를 0 또는 NULL로 설정해야 합니다.

    • dwContentCount 멤버를 검색할 항목 비율의 최대값으로 설정합니다.
    • 검색할 항목의 dwContentCount를 기준으로 dwOffset 멤버를 비율로 설정합니다.
    • lpContextID 멤버를 컨텍스트 ID 버퍼의 복사본 주소로 설정하고 dwContextIDLength를 컨텍스트 ID 버퍼의 길이(바이트)로 설정합니다. 컨텍스트 ID가 저장되지 않은 경우 이러한 멤버는 모두 0 또는 NULL이어야 합니다.

  2. 항목 수 가져오기 절차의 2~5단계에 표시된 대로 검색 기본 설정을 지정합니다.

  3. IDirectorySearch::ExecuteSearch를 사용하여 검색을 수행합니다.

  4. IDirectorySearch::GetFirstRow를 호출하여 결과의 첫 번째 행을 가져옵니다.

  5. 요청된 항목에 대한 실제 데이터를 가져오기 위해 검색할 특성 이름으로 IDirectorySearch::GetColumn 을 호출합니다.

  6. ADS_VLV_RESPONSE사용하여 IDirectorySearch::GetColumn을 호출하여 VLV 검색 메타데이터를 가져옵니다.

  7. ADS_SEARCH_COLUMN 구조체의 pADsValues-ProviderSpecific.lpValue>를 ADS_VLV 구조체 포인터로 캐스팅합니다.

  8. lpContextID 데이터의 복사본을 만들고 다음 VLV 검색을 위해 보존합니다.

 

GetVLVItemText 예제 함수는 이 작업을 수행하는 방법을 보여줍니다.

단일 검색 호출을 사용하여 둘 이상의 데이터 행을 검색할 수도 있습니다. 이 작업은 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_RESPONSE사용하여 IDirectorySearch::GetColumn을 호출하여 VLV 검색 메타데이터를 가져옵니다.

  7. ADS_SEARCH_COLUMN 구조체의 pADsValues-ProviderSpecific.lpValue>를 ADS_VLV 구조체 포인터로 캐스팅합니다.

  8. lpContextID 데이터의 복사본을 만들고 다음 VLV 검색을 위해 보존합니다. 필요한 경우 dwOffset 멤버에는 문자열 특성이 pszTarget에 지정된 값으로 시작하는 첫 번째 항목의 1부터 시작하는 인덱스가 포함됩니다.

GetVLVItemsByString 예제 함수는 이 작업을 수행하는 방법을 보여 줍니다.

인덱스별로 검색하는 것과 마찬가지로 단일 검색 호출을 사용하여 둘 이상의 데이터 행을 검색할 수도 있습니다. 이 작업은 ADS_VLV 구조체의 dwBeforeCount 및 dwAfterCount 멤버를 적절하게 설정하여 동일한 방식으로 수행됩니다.