Home Library Learn Downloads Support Community
Sign in | United States - English | |
3 out of 4 rated this helpful - Rate this topic

ConvertStringSecurityDescriptorToSecurityDescriptor function

Applies to: desktop apps only

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

Copy 
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 codeDescription
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 XP

Minimum supported server

Windows Server 2003

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: 3/7/2012

Did you find this helpful?
(1500 characters remaining)
Community Content Add
Annotations FAQ
Managed counterpart RawSecurityDescriptor
In .NET 2.0 or greater you can use the RawSecurityDescriptor class RawSecurityDescriptor Class http://msdn.microsoft.com/en-us/library/system.security.accesscontrol.rawsecuritydescriptor(v=vs.80).aspx Dim rsd As New RawSecurityDescriptor("O:BAG:BAD:(A;;0xb;;;WD)S:(ML;;NX;;;LW)") Dim data(rsd.BinaryLength - 1) As Byte rsd.GetBinaryForm(data, 0)
History
C# syntax 
[return: MarshalAs(UnmanagedType.Bool)]
[DllImport("Advapi32.dll", CharSet=CharSet.Unicode, SetLastError=true)]
internal static extern bool ConvertStringSecurityDescriptorToSecurityDescriptor(string StringSecurityDescriptor, uint StringSDRevision, ref IntPtr SecurityDescriptor, IntPtr SecurityDescriptorSize);
History
vb.net syntax 
<DllImport("advapi32.dll", CharSet:=CharSet.Unicode, SetLastError:=True)> _
Public Shared Function ConvertStringSecurityDescriptorToSecurityDescriptor(ByVal StringSecurityDescriptor As String, ByVal StringSDRevision As UInt32, ByRef SecurityDescriptor As IntPtr, ByVal SecurityDescriptorSize As IntPtr) As <MarshalAs(UnmanagedType.Bool)> Boolean
End Function
History