RtlStringCchCopyUnicodeString - NtDoc

#ifndef _NTSTRSAFE_H_INCLUDED_
#ifndef NTSTRSAFE_LIB_IMPL
#ifndef NTSTRSAFE_NO_UNICODE_STRING_FUNCTIONS

/*++

  NTSTATUS
  RtlStringCchCopyUnicodeString(
  _Out_writes_(cchDest) PWSTR               pszDest,
  _In_ size_t              cchDest,
  _In_ PCUNICODE_STRING    SourceString,
  );

  Routine Description:

  This routine copies a PUNICODE_STRING to a PWSTR. This function will not
  write past the end of this buffer and it will ALWAYS null terminate the
  destination buffer (unless it is zero length).

  This function returns an NTSTATUS value, and not a pointer. It returns
  STATUS_SUCCESS if the string was copied without truncation, otherwise it
  will return a failure code. In failure cases as much of SourceString will be
  copied to pszDest as possible.

Arguments:

pszDest        -   destination string

cchDest        -   size of destination buffer in characters.
length must be = ((DestinationString->Length / sizeof(wchar_t)) + 1)
to hold all of the source and null terminate the string.

SourceString   -   pointer to the counted unicode source string

Notes:
Behavior is undefined if source and destination strings overlap.

SourceString and pszDest should not be NULL.  See RtlStringCchCopyUnicodeStringEx
if you require the handling of NULL values.

Return Value:

STATUS_SUCCESS -   if there was source data and it was all copied and the
resultant dest string was null terminated

failure        -   the operation did not succeed

STATUS_BUFFER_OVERFLOW
Note: This status has the severity class Warning - IRPs completed with this
status do have their data copied back to user mode
-   this return value is an indication that the copy
operation failed due to insufficient space. When this
error occurs, the destination buffer is modified to
contain a truncated version of the ideal result and is
null terminated. This is useful for situations where
truncation is ok.

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

--*/

NTSTRSAFEDDI
    RtlStringCchCopyUnicodeString(
            _Out_writes_(cchDest) NTSTRSAFE_PWSTR pszDest,
            _In_ size_t cchDest,
            _In_ PCUNICODE_STRING SourceString)
{
    NTSTATUS status;

    status = RtlStringValidateDestW(pszDest,
            cchDest,
            NTSTRSAFE_UNICODE_STRING_MAX_CCH);
    if (NT_SUCCESS(status))
    {
        wchar_t* pszSrc;
        size_t cchSrcLength;

        status = RtlUnicodeStringValidateSrcWorker(SourceString,
                &pszSrc,
                &cchSrcLength,
                NTSTRSAFE_UNICODE_STRING_MAX_CCH,
                0);

        if (NT_SUCCESS(status))
        {
            status = RtlStringCopyWideCharArrayWorker(pszDest,
                    cchDest,
                    NULL,
                    pszSrc,
                    cchSrcLength);
        }
        else
        {
            *pszDest = L'\0';
        }
    }

    return status;
}

#endif
#endif
#endif
View code on GitHub