1 out of 4 rated this helpful - Rate this topic

ConvertSecurityDescriptorToStringSecurityDescriptor function

Applies to: desktop apps only

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.

Syntax

Copy

BOOL WINAPI ConvertSecurityDescriptorToStringSecurityDescriptor(
  __in   PSECURITY_DESCRIPTOR SecurityDescriptor,
  __in   DWORD RequestedStringSDRevision,
  __in   SECURITY_INFORMATION SecurityInformation,
  __out  LPTSTR *StringSecurityDescriptor,
  __out  PULONG StringSecurityDescriptorLen
);

Parameters

SecurityDescriptor [in]

A 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 0x00000001	Include the owner.
GROUP_SECURITY_INFORMATION 0x00000002	Include the primary group.
DACL_SECURITY_INFORMATION 0x00000004	Include the discretionary access control list (DACL).
SACL_SECURITY_INFORMATION 0x00000008	Include the system access control list (SACL).
LABEL_SECURITY_INFORMATION 0x00000010	Include the mandatory integrity label access control entry (ACE).
ATTRIBUTE_SECURITY_INFORMATION 0x00000020	Include the attribute information of the SACL. Windows Server 2008 R2, Windows 7, Windows Server 2008, Windows Vista, Windows Server 2003, and Windows XP: This value is not supported.
SCOPE_SECURITY_INFORMATION 0x00000040	Include the central access policy (CAP) identifier of the SACL. Windows Server 2008 R2, Windows 7, Windows Server 2008, Windows Vista, Windows Server 2003, and Windows XP: This value is not supported.

StringSecurityDescriptor [out]

A 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]

A 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 do not need to retrieve the size.

Return value

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. The GetLastError function may return one of the following error codes.

Return code	Description
ERROR_INVALID_PARAMETER	A parameter is not valid.
ERROR_UNKNOWN_REVISION	The revision level is not valid.
ERROR_NONE_MAPPED	A security identifier (SID) in the input security descriptor could not be found in an account lookup operation.
ERROR_INVALID_ACL	The access control list (ACL) is not valid. This error is returned if the SE_DACL_PRESENT flag is set in the input security descriptor and the DACL is NULL.

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