dsCrackNamesA 函数 (ntdsapi.h)

项目
03/05/2024

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 必须至少为 1， 并且 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 结构的状态成员中报告转换各个名称时出现的问题。

注意不要将 DsCrackNames 函数使用的 formatOffered 参数的 format 元素的值与 IADsNameTranslate 接口使用的 ADS_NAME_TYPE_ENUM 枚举中定义的类似名称的格式元素混淆。这两组元素格式不相等，并且不可互换。

注意

ntdsapi.h 标头将 DsCrackNames 定义为别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。将非特定编码别名与非非特定编码的代码混合使用可能会导致不匹配，从而导致编译或运行时错误。有关详细信息，请参阅函数原型的约定。

要求

要求	值
最低受支持的客户端	Windows Vista
最低受支持的服务器	Windows Server 2008
目标平台	Windows
标头	ntdsapi.h
Library	Ntdsapi.lib
DLL	Ntdsapi.dll