RtlStringCbCopyNA - NtDoc

#ifndef _NTSTRSAFE_H_INCLUDED_
#ifndef NTSTRSAFE_LIB_IMPL
#ifndef NTSTRSAFE_NO_CB_FUNCTIONS

/*++

  NTSTATUS
  RtlStringCbCopyN(
  _Out_writes_bytes_(cbDest) LPTSTR  pszDest,
  _In_  size_t  cbDest,
  _In_  LPCTSTR pszSrc,
  _In_  size_t  cbToCopy
  );

  Routine Description:

  This routine is a safer version of the C built-in function 'strncpy'.
  The size of the destination buffer (in bytes) is a parameter and 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 routine is meant as a replacement for strncpy, but it does behave
  differently. This function will not pad the destination buffer with extra
  null termination characters if cbToCopy is greater than the size of pszSrc.

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

Arguments:

pszDest        -   destination string

cbDest         -   size of destination buffer in bytes.
length must be = ((_tcslen(src) + 1) * sizeof(TCHAR)) to
hold all of the source including the null terminator

pszSrc         -   source string

cbToCopy       -   maximum number of bytes to copy from source string,
not including the null terminator.

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

pszDest and pszSrc should not be NULL.  See RtlStringCbCopyEx 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        -   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 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
    RtlStringCbCopyNA(
            _Out_writes_bytes_(cbDest) NTSTRSAFE_PSTR pszDest,
            _In_ size_t cbDest,
            _In_reads_bytes_(cbToCopy) STRSAFE_PCNZCH pszSrc,
            _In_ size_t cbToCopy)
{
    NTSTATUS status;
    size_t cchDest = cbDest / sizeof(char);

    status = RtlStringValidateDestA(pszDest, cchDest, NTSTRSAFE_MAX_CCH);

    if (NT_SUCCESS(status))
    {
        size_t cchToCopy = cbToCopy / sizeof(char);

        if (cchToCopy > NTSTRSAFE_MAX_LENGTH)
        {
            status = STATUS_INVALID_PARAMETER;

            *pszDest = '\0';
        }
        else
        {
            status = RtlStringCopyWorkerA(pszDest,
                    cchDest,
                    NULL,
                    pszSrc,
                    cchToCopy);
        }
    }

    return status;
}

#endif
#endif
#endif
View code on GitHub