ConvertStringSDToSDDomain Function

The ConvertStringSDToSDDomain function converts a string-format security descriptor into a valid, functional security descriptor resolved against a specified domain.

BOOL WINAPI ConvertStringSDToSDDomain(
  __in          PSID DomainSid,
  __in_opt      PSID RootDomainSid,
  __in          LPCTSTR StringSecurityDescriptor,
  __in          DWORD StringSDRevision,
  __out         PSECURITY_DESCRIPTOR* SecurityDescriptor,
  __out_opt     PULONG SecurityDescriptorSize
);

Parameters

  • DomainSid
    A pointer to a SID that represents the domain used to resolve the security descriptor.

  • RootDomainSid
    A pointer to a SID that represents the root domain used to resolve the security descriptor. This parameter can be NULL, in which case the security descriptor will be resolved against the machine controller's root domain.

  • StringSecurityDescriptor
    A pointer to a null-terminated string that contains the string-format security descriptor to convert.

  • StringSDRevision
    Specifies the revision level of the StringSecurityDescriptor string. This value must be SDDL_REVISION_1.

  • 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.

  • SecurityDescriptorSize
    A pointer to a ULONG 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 SID in the input security descriptor string could not be found in an account lookup operation.

Requirements

Client

Requires Windows Vista or Windows XP.

Server

Requires Windows Server 2008 or Windows Server 2003.

Library

Use Advapi32.lib.

DLL

Requires Advapi32.dll.

Unicode

Implemented as ConvertStringSDToSDDomainW (Unicode) and ConvertStringSDToSDDomainA (ANSI).

Send comments about this topic to Microsoft

Build date: 9/5/2007