RtlConvertSidToUnicodeString routine

The RtlConvertSidToUnicodeString routine generates a printable Unicode string representation of a security identifier (SID).

Syntax


NTSTATUS RtlConvertSidToUnicodeString(
  _Inout_ PUNICODE_STRING UnicodeString,
  _In_    PSID            Sid,
  _In_    BOOLEAN         AllocateDestinationString
);

Parameters

UnicodeString [in, out]

A pointer to a UNICODE_STRING structure to contain the generated Unicode string. The UnicodeString->MaximumLength member is set only if AllocateDestinationString is TRUE.

Sid [in]

A pointer to the SID structure that is to be converted to Unicode (the SID structure is unaffected).

AllocateDestinationString [in]

A Boolean flag that indicates whether this routine will allocate the UnicodeString buffer. If TRUE, only the UnicodeString->Buffer member is allocated and the rest of the UnicodeString structure must be allocated by the caller.

Return value

The RtlConvertSidToUnicodeString routine can return one of the following values:

Return codeDescription
STATUS_SUCCESS

The conversion was successful.

STATUS_BUFFER_OVERFLOW

This is returned if AllocateDestinationString is FALSE and the caller supplied UnicodeString buffer is too small to hold the converted Unicode string.

STATUS_NO_MEMORY

This is returned if AllocateDestinationString is TRUE and there is insufficient memory to allocate the UnicodeString buffer.

STATUS_INVALID_SID

The specified SID structure is not structurally valid.

 

Remarks

The generated Unicode string will take one of two forms. If the value of the IdentifierAuthority member of the SID is less than or equal to 2^32, the IdentifierAuthority member will be generated as decimal. For example, a SID with an IdentifierAuthority of 281,736 generates:


 S-1-281736-12-72-9-110

Otherwise the IdentifierAuthority will be generated as hexadecimal. For example, a SID with an IdentifierAuthority of 173,495,281,736 generates:


 S-1-0x28651FE848-12-72-9-110

All other members in the SID will be generated as decimal.

If AllocateDestinationString is TRUE, the allocated buffer must be deallocated by using RtlFreeUnicodeString.

Requirements

Target platform

Universal

Version

Available in Windows 2000 and later Windows operating systems.

Header

Ntifs.h (include Ntifs.h or FltKernel.h)

Library

NtosKrnl.lib

DLL

NtosKrnl.exe

IRQL

<= APC_LEVEL

See also

RtlFreeUnicodeString
SID
UNICODE_STRING

 

 

Send comments about this topic to Microsoft

Show: