ldap_search_ext 함수(winldap.h)

아티클
08/27/2023

ldap_search_ext 함수는 LDAP 디렉터리를 검색하고 일치하는 각 항목에 대해 요청된 특성 집합을 반환합니다.

구문

WINLDAPAPI ULONG LDAPAPI ldap_search_ext(
  [in]  LDAP          *ld,
  [in]  PSTR          base,
  [in]  ULONG         scope,
  [in]  PSTR          filter,
  [in]  PZPSTR        attrs,
  [in]  ULONG         attrsonly,
  [in]  PLDAPControlA *ServerControls,
  [in]  PLDAPControlA *ClientControls,
  [in]  ULONG         TimeLimit,
  [in]  ULONG         SizeLimit,
  [out] ULONG         *MessageNumber
);

매개 변수

[in] ld

세션 핸들입니다.

[in] base

검색을 시작할 항목의 고유 이름을 포함하는 null로 끝나는 문자열에 대한 포인터입니다.

[in] scope

검색 scope 나타내기 위해 다음 값 중 하나를 지정합니다.

LDAP_SCOPE_BASE

기본 항목만 검색합니다.

LDAP_SCOPE_ONELEVEL

기본 항목을 제외한 기본 항목 아래의 첫 번째 수준에서 모든 항목을 검색합니다.

LDAP_SCOPE_SUBTREE

기본 항목 및 기본 아래 트리의 모든 항목을 검색합니다.

[in] filter

검색 필터를 지정하는 null로 끝나는 문자열에 대한 포인터입니다. 자세한 내용은 검색 필터 구문을 참조하세요.

[in] attrs

일치하는 각 항목에 대해 반환할 특성을 나타내는 null로 종료된 문자열의 null로 끝나는 배열입니다. 사용 가능한 모든 특성을 검색하려면 NULL을 전달합니다.

[in] attrsonly

특성 형식과 값이 모두 반환될 경우 0이어야 하는 부울 값이며, 형식만 반환될 경우 0이 아닌 값입니다.

[in] ServerControls

LDAP 서버 컨트롤 목록입니다.

[in] ClientControls

클라이언트 컨트롤 목록입니다.

[in] TimeLimit

로컬 검색 시간 제한 값(초)과 검색 요청 내에서 서버로 전송된 작업 시간 제한을 모두 지정합니다.

[in] SizeLimit

검색에서 반환할 항목 수에 대한 제한입니다. 값이 0이면 한도가 없음을 의미합니다.

[out] MessageNumber

요청 메시지 ID입니다.

반환 값

함수가 성공하면 반환 값이 LDAP_SUCCESS.

함수가 실패하면 오류 코드를 반환합니다. 자세한 내용은 반환 값을 참조하세요.

설명

ldap_search_ext 함수는 비동기 검색 작업을 시작합니다. ldap_search_ext 매개 변수와 효과에는 ldap_search 매개 변수가 포함됩니다. 확장 함수에는 클라이언트 및 서버 컨트롤과 스레드 보안을 지원하고 각 검색 작업에 대한 크기 및 시간 제한을 지정하는 추가 매개 변수가 포함됩니다.

ld 세션 핸들과 함께 ldap_set_option 함수를 사용하여 검색 수행 방법을 결정하는 LDAP_OPT_DEREF 옵션을 설정합니다. 자세한 내용은 세션 옵션을 참조하세요. 다른 두 세션 옵션인 LDAP_OPT_SIZELIMIT 및 LDAP_OPT_TIMELIMIT 이 함수의 SizeLimit 및 TimeLimit 매개 변수를 위해 무시됩니다.

작업이 성공하면 작업이 성공적으로 반환될 때 ldap_search_ext 메시지 ID를 호출자에게 매개 변수로 전달합니다. 메시지 ID를 사용하여 ldap_result 호출하여 작업 결과를 가져옵니다.

결과가 반환되는 속도를 제어해야 하는 LDAP 클라이언트 애플리케이션은 크기가 원하는 페이지 크기로 설정되고 쿠키가 길이가 0인 문자열로 설정된 페이징된 결과 컨트롤을 제공하도록 검색 요청을 지정할 수 있습니다. 지정된 페이지 크기가 0보다 크고 검색 요청에 지정된 SizeLimit 값보다 작을 수 있습니다.

페이지 크기가 세션 옵션에 설명된 SizeLimit 값 옵션보다 크거나 같은 경우 요청이 단일 페이지에서 충족될 수 있으므로 서버는 컨트롤을 무시해야 합니다. 서버가 이 컨트롤을 지원하지 않는 경우 클라이언트가 위험으로 요청한 경우 서버에서 지원되지 않는 중요 확장의 오류를 반환해야 합니다. 그렇지 않으면 서버는 컨트롤을 무시해야 합니다. 이 섹션의 나머지 부분에서는 서버가 클라이언트의 페이징된 결과 컨트롤을 무시하지 않는다고 가정합니다.

클라이언트는 "쿠키"라고도 하는 빈 이전 열거형 키 및 초기 페이지 크기와 함께 간단한 페이징 결과 컨트롤을 사용하여 검색 요청을 서버에 보냅니다. 그런 다음 서버는 페이지 크기로 지정된 항목 수를 반환하고 다음 클라이언트 요청에서 발급된 쿠키를 반환하여 결과의 다음 페이지를 가져옵니다. 그런 다음 클라이언트는 쿠키가 포함된 검색을 발급하고 필요에 따라 페이지 크기를 다시 설정합니다. 그러면 서버는 지정된 수의 항목까지 결과를 반환하여 응답합니다. 함수에 결과를 직접 반환하도록 지시하려면 동기 루틴 ldap_search_ext_s 사용합니다.

다중 스레딩: ldap_search_ext 대한 호출은 스레드로부터 안전합니다.

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows Vista
지원되는 최소 서버	Windows Server 2008
대상 플랫폼	Windows
헤더	winldap.h
라이브러리	Wldap32.lib
DLL	Wldap32.dll