RtlStringCbLengthA - NtDoc

#ifndef _NTSTRSAFE_H_INCLUDED_
#ifndef NTSTRSAFE_LIB_IMPL
#ifndef NTSTRSAFE_NO_CB_FUNCTIONS

/*++

  NTSTATUS
  RtlStringCbLength(
  _In_reads_or_z_(cbMax) LPCTSTR psz,
  _In_ _In_range_(1, NTSTRSAFE_MAX_CCH * sizeof(TCHAR)) size_t  cbMax,
  _Out_opt_ _Deref_out_range_(<, cbMax) size_t* pcbLength   OPTIONAL
  );

  Routine Description:

  This routine is a safer version of the C built-in function 'strlen'.
  It is used to make sure a string is not larger than a given length, and
  it optionally returns the current length in bytes not including
  the null terminator.

  This function returns an NTSTATUS value, and not a pointer.  It returns
  STATUS_SUCCESS if the string is non-null and the length including the null
  terminator is less than or equal to cbMax bytes.

Arguments:

psz         -   string to check the length of

cbMax       -   maximum number of bytes including the null terminator
that psz is allowed to contain

pcb         -   if the function succeeds and pcb is non-null, the current length
in bytes of psz excluding the null terminator will be returned.
This out parameter is equivalent to the return value of strlen(psz) * sizeof(TCHAR)

Notes:
psz can be null but the function will fail

cbMax should be greater than or equal to sizeof(TCHAR) or the function will fail

Return Value:

STATUS_SUCCESS -   psz is non-null and the length including the null
terminator is less than or equal to cbMax bytes

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

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

--*/


_Must_inspect_result_
NTSTRSAFEDDI
    RtlStringCbLengthA(
            _In_reads_or_z_(cbMax) STRSAFE_PCNZCH psz,
            _In_ _In_range_(1, NTSTRSAFE_MAX_CCH * sizeof(char)) size_t cbMax,
            _Out_opt_ _Deref_out_range_(<, cbMax) size_t* pcbLength)
{
    NTSTATUS status;
    size_t cchMax = cbMax / sizeof(char);
    size_t cchLength = 0;

    if ((psz == NULL) || (cchMax > NTSTRSAFE_MAX_CCH))
    {
        status = STATUS_INVALID_PARAMETER;
    }
    else
    {
        status = RtlStringLengthWorkerA(psz, cchMax, &cchLength);
    }

    if (pcbLength)
    {
        if (NT_SUCCESS(status))
        {
            // safe to multiply cchLength * sizeof(char) since cchLength < NTSTRSAFE_MAX_CCH and sizeof(char) is 1
            *pcbLength = cchLength * sizeof(char);
        }
        else
        {
            *pcbLength = 0;
        }
    }

    return status;
}

#endif
#endif
#endif
View code on GitHub