ConvertSecurityDescriptorToStringSecurityDescriptorA function (sddl.h)
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
BOOL ConvertSecurityDescriptorToStringSecurityDescriptorA(
[in] PSECURITY_DESCRIPTOR SecurityDescriptor,
[in] DWORD RequestedStringSDRevision,
[in] SECURITY_INFORMATION SecurityInformation,
[out] LPSTR *StringSecurityDescriptor,
[out] PULONG StringSecurityDescriptorLen
);
Parameters
[in] SecurityDescriptor
A pointer to the security descriptor to convert. The security descriptor can be in absolute or self-relative format.
[in] RequestedStringSDRevision
Specifies the revision level of the output StringSecurityDescriptor string. Currently this value must be SDDL_REVISION_1.
[in] SecurityInformation
Specifies a combination of the SECURITY_INFORMATION bit flags to indicate the components of the security descriptor to include in the output string.
The BACKUP_SECURITY_INFORMATION flag is not applicable to this function. If the BACKUP_SECURITY_INFORMATION flag is passed in, the SecurityInformation parameter returns TRUE with null string output.
[out] StringSecurityDescriptor
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.
[out] StringSecurityDescriptorLen
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. The size represents the size of the buffer in WCHARs, not the number of WCHARs in the string.
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 |
|---|---|
|
A parameter is not valid. |
|
The revision level is not valid. |
|
A security identifier (SID) in the input security descriptor could not be found in an account lookup operation. |
|
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.
Note
The sddl.h header defines ConvertSecurityDescriptorToStringSecurityDescriptor as an alias that automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that is not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows XP [desktop apps | UWP apps] |
| Minimum supported server | Windows Server 2003 [desktop apps | UWP apps] |
| Target Platform | Windows |
| Header | sddl.h |
| Library | Advapi32.lib |
| DLL | Advapi32.dll |
See also
Basic Access Control Functions