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 WINAPI ConvertStringSecurityDescriptorToSecurityDescriptor(
__in LPCTSTR StringSecurityDescriptor,
__in DWORD StringSDRevision,
__out PSECURITY_DESCRIPTOR *SecurityDescriptor,
__out PULONG SecurityDescriptorSize
);
Parameters
- StringSecurityDescriptor [in]
-
A pointer to a null-terminated string containing the
string-format security descriptor to convert.
- StringSDRevision [in]
-
Specifies the revision level of the StringSecurityDescriptor string. Currently this value must be SDDL_REVISION_1.
- SecurityDescriptor [out]
-
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.
- SecurityDescriptorSize [out]
-
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.
Requirements
| Minimum supported client | Windows 2000 Professional |
|---|
| Minimum supported server | Windows 2000 Server |
|---|
| Header | Sddl.h |
|---|
| Library | Advapi32.lib |
|---|
| DLL | Advapi32.dll |
|---|
| Unicode and ANSI names | ConvertStringSecurityDescriptorToSecurityDescriptorW (Unicode) and ConvertStringSecurityDescriptorToSecurityDescriptorA (ANSI) |
|---|
See Also
- Access Control Overview
- Basic Access Control Functions
- ConvertSecurityDescriptorToStringSecurityDescriptor
- ConvertSidToStringSid
- ConvertStringSidToSid
- MakeAbsoluteSD
- SECURITY_DESCRIPTOR
Send comments about this topic to Microsoft
Build date: 6/26/2009