DsCrackNamesA 函数（ntdsapi.h）

项目
11/20/2024

DsCrackNames 函数将目录服务对象名称数组从一种格式转换为另一种格式。通过名称转换，客户端应用程序可以在用于标识各种目录服务对象的多个名称之间进行映射。例如，用户对象可以通过 SAM 帐户名称（域\UserName）、用户主体名称（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

指向接收包含转换名称 DS_NAME_RESULT 结构的 PDS_NAME_RESULT 值的指针。调用方必须通过调用 DsFreeNameResult来释放此内存（如果不再需要）。

返回值

返回 Win32 错误值、RPC 错误值或下列值之一。

言论

名称转换请求的成功取决于客户端的绑定位置。客户端使用 DsBind的一些变体绑定到目录服务的特定实例。如果绑定到全局目录，则名称映射的范围是整个林。如果未绑定到全局目录，则名称映射的范围是该域控制器的全局目录未涵盖的域。如果未绑定到全局目录且找不到名称，但输入名称明确标识其域，并且此域位于林中，则返回数据标识感兴趣的域的 DNS 域名。客户端应使用此数据绑定到正确的域控制器或全局编录，并使用新的绑定句柄再次调用 DsCrackNames。

DsCrackNames 的返回值 指示错误，例如参数无效或内存不足。但是，转换各个名称时出现的问题会报告在每个输入名称返回 DS_NAME_RESULT_ITEM 结构的状态成员。

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

注意

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

要求

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