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

Статья
08/25/2023

Функция DsCrackNames преобразует массив имен объектов службы каталогов из одного формата в другой. Преобразование имен позволяет клиентским приложениям сопоставлять несколько имен, используемых для идентификации различных объектов службы каталогов. Например, объекты-пользователи могут быть идентифицированы по именам учетных записей SAM (имя_пользователя),\ имени участника-пользователя (имя_@пользователя.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 игнорируется. Значение cName должно быть по крайней мере одним, а все строки в 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 , с аналогичными именованными элементами format, как определено в перечислении ADS_NAME_TYPE_ENUM , используемом интерфейсом IADsNameTranslate . Два набора форматов элементов не эквивалентны и не являются взаимозаменяемыми.

Примечание

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

Требования

Требование	Значение
Минимальная версия клиента	Windows Vista
Минимальная версия сервера	Windows Server 2008
Целевая платформа	Windows
Header	ntdsapi.h
Библиотека	Ntdsapi.lib
DLL	Ntdsapi.dll