ConvertSecurityDescriptorToStringSecurityDescriptor

The ConvertSecurityDescriptorToStringSecurityDescriptor function converts a security descriptor to a string format. You can use the string format to store or transmit the security descriptor.

To convert the string-format security descriptor back to a valid, functional security descriptor, call the ConvertStringSecurityDescriptorToSecurityDescriptor function.

BOOL ConvertSecurityDescriptorToStringSecurityDescriptor(
  PSECURITY_DESCRIPTOR SecurityDescriptor,  // SD
  DWORD RequestedStringSDRevision,          // revision level
  SECURITY_INFORMATION SecurityInformation, // component
  LPTSTR *StringSecurityDescriptor,         // security descriptor string
  PULONG StringSecurityDescriptorLen        // size of security descriptor string
);

Parameters

SecurityDescriptor

[in] Pointer to the security descriptor to convert. The security descriptor can be in absolute or self-relative format.

RequestedStringSDRevision

[in] Specifies the revision level of the output StringSecurityDescriptor string. Currently this value must be SDDL_REVISION_1.

SecurityInformation

[in] Specifies a combination of the following SECURITY_INFORMATION bit flags to indicate the components of the security descriptor to include in the output string.

Value	Meaning
OWNER_SECURITY_INFORMATION	Include the owner.
GROUP_SECURITY_INFORMATION	Include the primary group.
DACL_SECURITY_INFORMATION	Include the DACL.
SACL_SECURITY_INFORMATION	Include the SACL.

StringSecurityDescriptor

[out] Pointer to a variable that receives a pointer to a null-terminated security descriptor string. For a description of the string format, see Security Descriptor String Format. To free the returned buffer, call the LocalFree function.

StringSecurityDescriptorLen

[out] Pointer to a variable that receives the size, in TCHARs, of the security descriptor string returned in the StringSecurityDescriptor buffer. This parameter can be NULL if you don't need to retrieve the size.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To get extended error information, call GetLastError. GetLastError may return one of the following error codes.

Remarks

If the DACL is NULL and the SE_DACL_PRESENT control bit is set in the input security descriptor, the function fails.

If the DACL is NULL and the SE_DACL_PRESENT control bit is not set in the input security descriptor, the resulting security descriptor string does not have a D: component. For more information, see Security Descriptor String Format.

Requirements

  Windows NT/2000: Requires Windows 2000.
  Header: Declared in Sddl.h.
  Library: Use Advapi32.lib.
  Unicode: Implemented as Unicode and ANSI versions on Windows 2000.

See Also

Access Control Overview, Access Control Functions, ConvertSidToStringSid, ConvertStringSecurityDescriptorToSecurityDescriptor, ConvertStringSidToSid, SECURITY_DESCRIPTOR