ConvertSecurityDescriptorToStringSecurityDescriptorA 函数 (sddl.h)

项目
08/25/2023

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 缓冲区中返回的安全描述符字符串的大小（以 TCHAR为单位）。如果不需要检索大小，此参数可以为 NULL 。大小表示 WCHAR中缓冲区的大小，而不是字符串中的 WCHAR数。

返回值

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

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

返回代码	说明
ERROR_INVALID_PARAMETER	参数无效。
ERROR_UNKNOWN_REVISION	修订级别无效。
ERROR_NONE_MAPPED	在帐户查找操作中找不到输入安全描述符中 SID (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 应用]
目标平台	Windows
标头	sddl.h
Library	Advapi32.lib
DLL	Advapi32.dll