ConvertStringSecurityDescriptorToSecurityDescriptorA function (sddl.h)

  • Article

The ConvertStringSecurityDescriptorToSecurityDescriptor function converts a string-format security descriptor into a valid, functional security descriptor. This function retrieves a security descriptor that the ConvertSecurityDescriptorToStringSecurityDescriptor function converted to string format.

Syntax

BOOL ConvertStringSecurityDescriptorToSecurityDescriptorA(
  [in]  LPCSTR               StringSecurityDescriptor,
  [in]  DWORD                StringSDRevision,
  [out] PSECURITY_DESCRIPTOR *SecurityDescriptor,
  [out] PULONG               SecurityDescriptorSize
);

Parameters

[in] StringSecurityDescriptor

A pointer to a null-terminated string containing the string-format security descriptor to convert.

[in] StringSDRevision

Specifies the revision level of the StringSecurityDescriptor string. Currently this value must be SDDL_REVISION_1.

[out] SecurityDescriptor

A pointer to a variable that receives a pointer to the converted security descriptor. The returned security descriptor is self-relative. To free the returned buffer, call the LocalFree function. To convert the security descriptor to an absolute security descriptor, use the MakeAbsoluteSD function.

[out] SecurityDescriptorSize

A pointer to a variable that receives the size, in bytes, of the converted security descriptor. This parameter can be NULL.

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

Return code Description
ERROR_INVALID_PARAMETER
 A parameter is not valid.
ERROR_UNKNOWN_REVISION
 The SDDL revision level is not valid.
ERROR_NONE_MAPPED
 A security identifier (SID) in the input security descriptor string could not be found in an account lookup operation.

Remarks

If ace_type is ACCESS_ALLOWED_OBJECT_ACE_TYPE and neither object_guid nor inherit_object_guid has a GUID specified, then ConvertStringSecurityDescriptorToSecurityDescriptor converts ace_type to ACCESS_ALLOWED_ACE_TYPE. For information about the ace_type, object_guid, and inherit_object_guid fields, see Ace Strings.

Note

The sddl.h header defines ConvertStringSecurityDescriptorToSecurityDescriptor as an alias which 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 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

Access Control Overview

Basic Access Control Functions

ConvertSecurityDescriptorToStringSecurityDescriptor

ConvertSidToStringSid

ConvertStringSidToSid

MakeAbsoluteSD

SECURITY_DESCRIPTOR