Функция DsCrackNamesA (ntdsapi.h)

Статья
11/20/2024

Функция DsCrackNames преобразует массив имен объектов службы каталогов из одного формата в другой. Преобразование имен позволяет клиентским приложениям сопоставлять несколько имен, используемых для идентификации различных объектов службы каталогов. Например, пользовательские объекты можно определить по именам учетных записей SAM (доменныхUserName), имени участника-пользователя (имени пользователядоменных.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 должны иметь длину больше нуля символов. Содержимое строк 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

Указатель на значение PDS_NAME_RESULT, которое получает структуру DS_NAME_RESULT, содержащую преобразованные имена. Вызывающий объект должен освободить эту память, если она больше не требуется, вызвав DsFreeNameResult.

Возвращаемое значение

Возвращает значение ошибки Win32, значение ошибки RPC или одно из следующих значений.

Замечания

Успех запроса на преобразование имен зависит от того, где привязан клиент. Клиенты привязываются к определенным экземплярам службы каталогов с помощью некоторых вариантов DsBind. Если привязан к глобальному каталогу, область сопоставления имен — это весь лес. Если он не привязан к глобальному каталогу, область сопоставления имен — это домен, не охватываемый глобальным каталогом для этого контроллера домена. Если не привязан к глобальному каталогу и имя не найдено, но входное имя однозначно идентифицирует его домен и этот домен находится в лесу, то возвращаемые данные идентифицируют DNS-имя домена для интересующего домена. Ожидается, что клиенты будут использовать эти данные для привязки к правильному контроллеру домена или глобальному каталогу и вызову DsCrackNames снова с новым дескриптором привязки.

Возвращаемое значение из DsCrackNames указывает на ошибки, такие как недопустимые параметры или недостаточно памяти. Однако проблемы при преобразовании отдельных имен отображаются в состоянии член структуры DS_NAME_RESULT_ITEM, возвращаемой для каждого входного имени.

Примечание Не путайте значения элементов формата formatOffered, используемых функцией dsCrackNames, с аналогичными именованными элементами формата, как определено в перечислении ADS_NAME_TYPE_ENUM, используемом интерфейсом IADsNameTranslate. Два набора форматов элементов не эквивалентны и не являются взаимозаменяемыми.

Заметка

Заголовок ntdsapi.h определяет DsCrackNames в качестве псевдонима, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора UNICODE. Сочетание использования псевдонима, нейтрального для кодирования, с кодом, не зависящим от кодирования, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в соглашениях о прототипах функций.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows Vista
минимальный поддерживаемый сервер	Windows Server 2008
целевая платформа	Виндоус
заголовка	ntdsapi.h
библиотеки	Ntdsapi.lib
DLL	Ntdsapi.dll