RtlStringCchCatNA - NtDoc

#ifndef _NTSTRSAFE_H_INCLUDED_
#ifndef NTSTRSAFE_LIB_IMPL
#ifndef NTSTRSAFE_NO_CCH_FUNCTIONS

/*++

  NTSTATUS
  RtlStringCchCatN(
  _Inout_updates_(cchDest) _Always_(_Post_z_) LPTSTR  pszDest,
  _In_     size_t  cchDest,
  _In_     LPCTSTR pszSrc,
  _In_     size_t  cchToAppend
  );

  Routine Description:

  This routine is a safer version of the C built-in function 'strncat'.
  The size of the destination buffer (in characters) is a parameter as well as
  the maximum number of characters to append, excluding the null terminator.
  This function will not write past the end of the destination buffer and it will
  ALWAYS null terminate pszDest (unless it is zero length).

  This function returns an NTSTATUS value, and not a pointer.  It returns
  STATUS_SUCCESS if all of pszSrc or the first cchToAppend characters were appended
  to the destination string and it was null terminated, otherwise it will
  return a failure code. In failure cases as much of pszSrc will be appended
  to pszDest as possible, and pszDest will be null terminated.

Arguments:

pszDest         -   destination string which must be null terminated

cchDest         -   size of destination buffer in characters.
length must be (_tcslen(pszDest) + min(cchToAppend, _tcslen(pszSrc)) + 1)
to hold all of the combine string plus the null
terminator.

pszSrc          -   source string

cchToAppend     -   maximum number of characters to append

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

pszDest and pszSrc should not be NULL. See RtlStringCchCatNEx if you require
the handling of NULL values.

Return Value:

STATUS_SUCCESS -   if all of pszSrc or the first cchToAppend characters
were concatenated to pszDest and the resultant dest
string was null terminated

failure        -   you can use the macro NTSTATUS_CODE() to get a win32
error code for all hresult failure cases

STATUS_BUFFER_OVERFLOW /
NTSTATUS_CODE(status) == ERROR_INSUFFICIENT_BUFFER
-   this return value is an indication that the 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
    RtlStringCchCatNA(
            _Inout_updates_(cchDest) _Always_(_Post_z_) NTSTRSAFE_PSTR pszDest,
            _In_ size_t cchDest,
            _In_reads_or_z_(cchToAppend) STRSAFE_PCNZCH pszSrc,
            _In_ size_t cchToAppend)
{
    NTSTATUS status;
    size_t cchDestLength;

    status = RtlStringValidateDestAndLengthA(pszDest,
            cchDest,
            &cchDestLength,
            NTSTRSAFE_MAX_CCH);

    if (NT_SUCCESS(status))
    {
        if (cchToAppend > NTSTRSAFE_MAX_LENGTH)
        {
            status = STATUS_INVALID_PARAMETER;
        }
        else
        {
            status = RtlStringCopyWorkerA(pszDest + cchDestLength,
                    cchDest - cchDestLength,
                    NULL,
                    pszSrc,
                    cchToAppend);
        }
    }

    return status;
}

#endif
#endif
#endif
View code on GitHub