ConvertSecurityDescriptorToStringSecurityDescriptorA 函数（sddl.h）

项目
11/20/2024

ConvertSecurityDescriptorToStringSecurityDescriptor 函数将安全描述符转换为字符串格式。可以使用字符串格式来存储或传输安全描述符。

若要将字符串格式的安全描述符转换回有效的功能安全描述符，请调用 ConvertStringSecurityDescriptorToSecurityDescriptor 函数。

语法

BOOL ConvertSecurityDescriptorToStringSecurityDescriptorA(
  [in]  PSECURITY_DESCRIPTOR SecurityDescriptor,
  [in]  DWORD                RequestedStringSDRevision,
  [in]  SECURITY_INFORMATION SecurityInformation,
  [out] LPSTR                *StringSecurityDescriptor,
  [out] PULONG               StringSecurityDescriptorLen
);

参数

[in] SecurityDescriptor

指向要转换的安全描述符的指针。安全描述符可以采用绝对格式或相对格式。

[in] RequestedStringSDRevision

指定 stringSecurityDescriptor 字符串输出的修订级别。目前，此值必须SDDL_REVISION_1。

[in] SecurityInformation

指定 SECURITY_INFORMATION 位标志的组合，以指示要包含在输出字符串中的安全描述符的组件。

BACKUP_SECURITY_INFORMATION标志不适用于此函数。如果传入BACKUP_SECURITY_INFORMATION标志，则 SecurityInformation 参数返回 TRUE，null 字符串输出。

[out] StringSecurityDescriptor

指向一个变量的指针，该变量接收指向 null终止的安全描述符字符串的指针。有关字符串格式的说明，请参阅安全描述符字符串格式。若要释放返回的缓冲区，请调用 LocalFree 函数。

[out] StringSecurityDescriptorLen

指向接收 StringSecurityDescriptor 缓冲区中返回的安全描述符字符串的大小（TCHARs）的变量的指针。如果不需要检索大小，则可以 NULL 此参数。大小表示 WCHARs 中的缓冲区大小，而不是字符串中 WCHAR的数目。

返回值

如果函数成功，则返回值为非零。

如果函数失败，则返回值为零。若要获取扩展的错误信息，请调用 GetLastError。 GetLastError 函数可能会返回以下错误代码之一。

返回代码	描述
ERROR_INVALID_PARAMETER	参数无效。
ERROR_UNKNOWN_REVISION	修订级别无效。
ERROR_NONE_MAPPED	在帐户查找操作中找不到输入安全描述符中的安全标识符（SID）。
ERROR_INVALID_ACL	访问控制列表（ACL）无效。如果在输入安全描述符中设置了SE_DACL_PRESENT标志，并且 DACL NULL，则返回此错误。

言论

如果 DACL NULL，并且输入安全描述符中设置了SE_DACL_PRESENT控制位，则该函数将失败。

如果 DACL NULL，并且输入安全描述符中未设置SE_DACL_PRESENT控制位，则生成的安全描述符字符串没有 D：组件。有关详细信息，请参阅安全描述符字符串格式。

注意

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

要求

要求	价值
最低支持的客户端	Windows XP [桌面应用 \|UWP 应用]
支持的最低服务器	Windows Server 2003 [桌面应用 \|UWP 应用]
目标平台	窗户
标头	sddl.h
库	Advapi32.lib
DLL	Advapi32.dll