DsCrackNamesA 함수(ntdsapi.h)

아티클
08/25/2023

DsCrackNames 함수는 디렉터리 서비스 개체 이름의 배열을 한 형식에서 다른 형식으로 변환합니다. 이름 변환을 사용하면 클라이언트 애플리케이션이 다양한 디렉터리 서비스 개체를 식별하는 데 사용되는 여러 이름 간에 매핑할 수 있습니다. 예를 들어 사용자 개체는 SAM 계정 이름(Domain\UserName), 사용자 계정 이름(UserName@Domain.com) 또는 고유 이름으로 식별할 수 있습니다.

구문

NTDSAPI DWORD DsCrackNamesA(
  [in]  HANDLE           hDS,
  [in]  DS_NAME_FLAGS    flags,
  [in]  DS_NAME_FORMAT   formatOffered,
  [in]  DS_NAME_FORMAT   formatDesired,
  [in]  DWORD            cNames,
  [in]  const LPCSTR     *rpNames,
  [out] PDS_NAME_RESULTA *ppResult
);

매개 변수

[in] hDS

DSBind 또는 DSBindWithCred 함수에서 가져온 디렉터리 서비스 핸들을 포함합니다. 플래그에 DS_NAME_FLAG_SYNTACTICAL_ONLY 포함된 경우 hDS는 NULL일 수 있습니다.

[in] flags

이름 구문을 해독하는 방법을 결정하는 데 사용되는 하나 이상의 DS_NAME_FLAGS 값을 포함합니다.

[in] formatOffered

입력 이름의 형식을 식별하는 DS_NAME_FORMAT 값 중 하나를 포함합니다.

이 매개 변수에 대해 DS_LIST_NCS 값을 전달할 수도 있습니다. 이로 인해 DsCrackNames 는 현재 포리스트에 있는 모든 명명 컨텍스트의 고유 이름을 반환합니다. formatDesired 매개 변수는 무시됩니다. cNames는 하나 이상이어야 하며 rpNames 의 모든 문자열의 길이는 0자보다 커야 합니다. rpNames 문자열의 내용은 무시됩니다.

DS_LIST_NCS 게시된 헤더 파일에 정의되어 있지 않습니다. 이 값을 사용하려면 아래와 같이 정확한 형식으로 정의합니다.

#ifndef DS_LIST_NCS
    #define DS_LIST_NCS 0xfffffff6
#endif

[in] formatDesired

출력 이름의 형식을 식별하는 DS_NAME_FORMAT 값 중 하나를 포함합니다. DS_SID_OR_SID_HISTORY_NAME 값은 지원되지 않습니다.

[in] cNames

rpNames 배열의 요소 수를 포함합니다.

[in] rpNames

변환할 이름을 포함하는 null로 끝나는 문자열에 대한 포인터 배열에 대한 포인터입니다.

[out] ppResult

변환된 이름을 포함하는 DS_NAME_RESULT 구조를 수신하는 PDS_NAME_RESULT 값에 대한 포인터입니다. 호출자는 DsFreeNameResult를 호출하여 더 이상 필요하지 않은 경우 이 메모리를 해제해야 합니다.

반환 값

Win32 오류 값, RPC 오류 값 또는 다음 중 하나를 반환합니다.

설명

이름 변환 요청의 성공 여부는 클라이언트가 바인딩된 위치에 따라 달라집니다. 클라이언트는 DsBind의 일부 변형을 사용하여 디렉터리 서비스의 특정 인스턴스에 바인딩합니다. 글로벌 카탈로그에 바인딩된 경우 이름 매핑의 scope 전체 포리스트입니다. 글로벌 카탈로그에 바인딩되지 않은 경우 이름 매핑의 scope 해당 도메인 컨트롤러에 대한 글로벌 카탈로그에서 다루지 않는 도메인입니다. 글로벌 카탈로그에 바인딩되지 않고 이름을 찾을 수 없지만 입력 이름이 해당 도메인을 명확하게 식별하고 이 도메인이 포리스트에 있는 경우 반환 데이터는 관심 있는 도메인의 DNS 도메인 이름을 식별합니다. 클라이언트는 이 데이터를 사용하여 올바른 도메인 컨트롤러 또는 글로벌 카탈로그에 바인딩하고 새 바인딩 핸들을 사용하여 DsCrackNames 를 다시 호출해야 합니다.

DsCrackNames의 반환 값은 잘못된 매개 변수 또는 메모리 부족과 같은 오류를 나타냅니다. 그러나 개별 이름을 변환하는 문제는 각 입력 이름에 대해 반환된 DS_NAME_RESULT_ITEM 구조체의 상태 멤버에 보고됩니다.

참고DsCrackNames 함수에서 사용하는 formatOffered 매개 변수의 서식 요소 값을 IADsNameTranslate 인터페이스에서 사용하는 ADS_NAME_TYPE_ENUM 열거형에 정의된 것과 비슷한 이름의 서식 요소와 혼동하지 마세요. 두 요소 형식 집합은 동일하지 않으며 서로 교환할 수 없습니다.

참고

ntdsapi.h 헤더는 유니코드 전처리기 상수의 정의에 따라 이 함수의 ANSI 또는 유니코드 버전을 자동으로 선택하는 별칭으로 DsCrackNames를 정의합니다. 인코딩 중립 별칭을 인코딩 중립이 아닌 코드와 혼합하면 컴파일 또는 런타임 오류가 발생하는 불일치가 발생할 수 있습니다. 자세한 내용은 함수 프로토타입에 대한 규칙을 참조하세요.

요구 사항

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