RtlUnicodeStringInitEx - NtDoc

#ifndef _NTSTRSAFE_H_INCLUDED_
#ifndef NTSTRSAFE_LIB_IMPL
#ifndef NTSTRSAFE_NO_UNICODE_STRING_FUNCTIONS

/*++

  NTSTATUS
  RtlUnicodeStringInitEx(
  _Out_ PUNICODE_STRING DestinationString,
  _In_opt_  NTSTRSAFE_PCWSTR pszSrc              OPTIONAL,
  _In_ DWORD           dwFlags
  );

  Routine Description:

  In addition to functionality provided by RtlUnicodeStringInit, this routine
  includes the flags parameter allows additional controls.

  This function returns an NTSTATUS value.  It returns STATUS_SUCCESS if the
  counted unicode string was successfully initialized from pszSrc. In failure
  cases the unicode string buffer will be set to NULL, and the Length and
  MaximumLength members will be set to zero.

Arguments:

DestinationString - pointer to the counted unicode string to be initialized

pszSrc            - source string which must be null terminated

dwFlags           - controls some details of the initialization:

STRSAFE_IGNORE_NULLS
do not fault on a NULL DestinationString pointer

Return Value:

STATUS_SUCCESS -

failure        -   the operation did not succeed

STATUS_INVALID_PARAMETER

It is strongly recommended to use the NT_SUCCESS() macro to test the
return value of this function.

--*/

_At_(DestinationString->Buffer, _Post_equal_to_(pszSrc))
_At_(DestinationString->Length, _Post_equal_to_(_String_length_(pszSrc) * sizeof(WCHAR)))
_At_(DestinationString->MaximumLength, _Post_equal_to_((_String_length_(pszSrc)+1) * sizeof(WCHAR)))
NTSTRSAFEDDI
RtlUnicodeStringInitEx(
        _Out_ PUNICODE_STRING DestinationString,
        _In_opt_ NTSTRSAFE_PCWSTR pszSrc,
        _In_ DWORD dwFlags)
{
    NTSTATUS status;

    if (dwFlags & (~STRSAFE_UNICODE_STRING_VALID_FLAGS))
    {
        status = STATUS_INVALID_PARAMETER;
    }
    else
    {
        status = RtlUnicodeStringInitWorker(DestinationString,
                pszSrc,
                NTSTRSAFE_UNICODE_STRING_MAX_CCH,
                dwFlags);
    }

    if (!NT_SUCCESS(status) && DestinationString)
    {
        DestinationString->Length = 0;
        DestinationString->MaximumLength = 0;
        DestinationString->Buffer = NULL;
    }

    return status;
}

#endif
#endif
#endif
View code on GitHub