/****************************************************************** * * * ntstrsafe.h -- This module defines safer C library string * * routine replacements for drivers. These are * * meant to make C a bit more safe in reference * * to security and robustness. A similar file, * * strsafe.h, is available for applications. * * * * Copyright (c) Microsoft Corp. All rights reserved. * * * ******************************************************************/ #ifndef _NTSTRSAFE_H_INCLUDED_ #define _NTSTRSAFE_H_INCLUDED_ #if (_MSC_VER > 1000) #pragma once #endif #include // for _vsnprintf, _vsnwprintf, getc, getwc #include // for memset #include // for va_start, etc. #include // for __in, etc. #ifndef NTSTRSAFE_NO_UNICODE_STRING_FUNCTIONS #include // for UNICODE_STRING, etc. #endif #if !defined(_W64) #if !defined(__midl) && (defined(_X86_) || defined(_M_IX86)) && (_MSC_VER >= 1300) #define _W64 __w64 #else #define _W64 #endif #endif #if defined(_M_MRX000) || defined(_M_ALPHA) || defined(_M_PPC) || defined(_M_IA64) || defined(_M_AMD64) #define ALIGNMENT_MACHINE #define UNALIGNED __unaligned #if defined(_WIN64) #define UNALIGNED64 __unaligned #else #define UNALIGNED64 #endif #else #undef ALIGNMENT_MACHINE #define UNALIGNED #define UNALIGNED64 #endif // typedefs #ifdef _WIN64 typedef unsigned __int64 size_t; #else typedef _W64 unsigned int size_t; #endif #ifndef _NTSTATUS_DEFINED #define _NTSTATUS_DEFINED typedef __success(return >= 0) long NTSTATUS; #endif typedef unsigned long DWORD; #ifndef SORTPP_PASS // compiletime asserts (failure results in error C2118: negative subscript) #define C_ASSERT(e) typedef char __C_ASSERT__[(e)?1:-1] #else #define C_ASSERT(e) #endif #ifdef __cplusplus #define EXTERN_C extern "C" #else #define EXTERN_C extern #endif // use the new secure crt functions if available #ifndef NTSTRSAFE_USE_SECURE_CRT #if defined(__GOT_SECURE_LIB__) && (__GOT_SECURE_LIB__ >= 200402L) #define NTSTRSAFE_USE_SECURE_CRT 0 #else #define NTSTRSAFE_USE_SECURE_CRT 0 #endif #endif // !NTSTRSAFE_USE_SECURE_CRT #ifdef _M_CEE_PURE #define NTSTRSAFEDDI __inline NTSTATUS __clrcall #else #define NTSTRSAFEDDI __inline NTSTATUS __stdcall #endif #if defined(NTSTRSAFE_LIB_IMPL) || defined(NTSTRSAFE_LIB) #define NTSTRSAFEWORKERDDI EXTERN_C NTSTATUS __stdcall #else #define NTSTRSAFEWORKERDDI static NTSTRSAFEDDI #endif // The following steps are *REQUIRED* if ntstrsafe.h is used for drivers on: // Windows 2000 // Windows Millennium Edition // Windows 98 Second Edition // Windows 98 // // 1. #define NTSTRSAFE_LIB before including the ntstrsafe.h header file. // 2. Add ntstrsafe.lib to the TARGET_LIBS line in SOURCES // // Drivers running on XP and later can skip these steps to create a smaller // driver by running the functions inline. #if defined(NTSTRSAFE_LIB) #pragma comment(lib, "ntstrsafe.lib") #endif // The user can request no "Cb" or no "Cch" fuctions, but not both #if defined(NTSTRSAFE_NO_CB_FUNCTIONS) && defined(NTSTRSAFE_NO_CCH_FUNCTIONS) #error cannot specify both NTSTRSAFE_NO_CB_FUNCTIONS and NTSTRSAFE_NO_CCH_FUNCTIONS !! #endif // The user may override NTSTRSAFE_MAX_CCH, but it must always be less than INT_MAX #ifndef NTSTRSAFE_MAX_CCH #define NTSTRSAFE_MAX_CCH 2147483647 // max buffer size, in characters, that we support (same as INT_MAX) #endif C_ASSERT(NTSTRSAFE_MAX_CCH <= 2147483647); C_ASSERT(NTSTRSAFE_MAX_CCH > 1); #define NTSTRSAFE_MAX_LENGTH (NTSTRSAFE_MAX_CCH - 1) // max buffer length, in characters, that we support // The user may override NTSTRSAFE_UNICODE_STRING_MAX_CCH, but it must always be less than (USHORT_MAX / sizeof(wchar_t)) #ifndef NTSTRSAFE_UNICODE_STRING_MAX_CCH #define NTSTRSAFE_UNICODE_STRING_MAX_CCH (0xffff / sizeof(wchar_t)) // max buffer size, in characters, for a UNICODE_STRING #endif C_ASSERT(NTSTRSAFE_UNICODE_STRING_MAX_CCH <= (0xffff / sizeof(wchar_t))); C_ASSERT(NTSTRSAFE_UNICODE_STRING_MAX_CCH > 1); // Flags for controling the Ex functions // // STRSAFE_FILL_BYTE(0xFF) 0x000000FF // bottom byte specifies fill pattern #define STRSAFE_IGNORE_NULLS 0x00000100 // treat null string pointers as TEXT("") -- don't fault on NULL buffers #define STRSAFE_FILL_BEHIND_NULL 0x00000200 // on success, fill in extra space behind the null terminator with fill pattern #define STRSAFE_FILL_ON_FAILURE 0x00000400 // on failure, overwrite pszDest with fill pattern and null terminate it #define STRSAFE_NULL_ON_FAILURE 0x00000800 // on failure, set *pszDest = TEXT('\0') #define STRSAFE_NO_TRUNCATION 0x00001000 // instead of returning a truncated result, copy/append nothing to pszDest and null terminate it // Flags for controling UNICODE_STRING Ex functions // // STRSAFE_FILL_BYTE(0xFF) 0x000000FF // bottom byte specifies fill pattern // STRSAFE_IGNORE_NULLS 0x00000100 // don't fault on NULL UNICODE_STRING pointers, and treat null pszSrc as L"" #define STRSAFE_FILL_BEHIND 0x00000200 // on success, fill in extra space at the end of the UNICODE_STRING Buffer with fill pattern // STRSAFE_FILL_ON_FAILURE 0x00000400 // on failure, fill the UNICODE_STRING Buffer with fill pattern and set the Length to 0 #define STRSAFE_ZERO_LENGTH_ON_FAILURE 0x00000800 // on failure, set the UNICODE_STRING Length to 0 // STRSAFE_NO_TRUNCATION 0x00001000 // instead of returning a truncated result, copy/append nothing to UNICODE_STRING Buffer #define STRSAFE_VALID_FLAGS (0x000000FF | STRSAFE_IGNORE_NULLS | STRSAFE_FILL_BEHIND_NULL | STRSAFE_FILL_ON_FAILURE | STRSAFE_NULL_ON_FAILURE | STRSAFE_NO_TRUNCATION) #define STRSAFE_UNICODE_STRING_VALID_FLAGS (0x000000FF | STRSAFE_IGNORE_NULLS | STRSAFE_FILL_BEHIND | STRSAFE_FILL_ON_FAILURE | STRSAFE_ZERO_LENGTH_ON_FAILURE | STRSAFE_NO_TRUNCATION) // helper macro to set the fill character and specify buffer filling #define STRSAFE_FILL_BYTE(x) ((DWORD)((x & 0x000000FF) | STRSAFE_FILL_BEHIND_NULL)) #define STRSAFE_FAILURE_BYTE(x) ((DWORD)((x & 0x000000FF) | STRSAFE_FILL_ON_FAILURE)) #define STRSAFE_GET_FILL_PATTERN(dwFlags) ((int)(dwFlags & 0x000000FF)) // // These typedefs are used in places where the string is guaranteed to // be null terminated. // typedef __nullterminated char* NTSTRSAFE_PSTR; typedef __nullterminated const char* NTSTRSAFE_PCSTR; typedef __nullterminated wchar_t* NTSTRSAFE_PWSTR; typedef __nullterminated const wchar_t* NTSTRSAFE_PCWSTR; typedef __nullterminated const wchar_t UNALIGNED* NTSTRSAFE_PCUWSTR; // // These typedefs are used in places where the string is NOT guaranteed to // be null terminated. // typedef __possibly_notnullterminated const char* STRSAFE_PCNZCH; typedef __possibly_notnullterminated const wchar_t* STRSAFE_PCNZWCH; typedef __possibly_notnullterminated const wchar_t UNALIGNED* STRSAFE_PCUNZWCH; // prototypes for the worker functions NTSTRSAFEWORKERDDI RtlStringLengthWorkerA( __in STRSAFE_PCNZCH psz, __in __in_range(<=, NTSTRSAFE_MAX_CCH) size_t cchMax, __out_opt __deref_out_range(<, cchMax) size_t* pcchLength); NTSTRSAFEWORKERDDI RtlStringLengthWorkerW( __in STRSAFE_PCNZWCH psz, __in __in_range(<=, NTSTRSAFE_MAX_CCH) size_t cchMax, __out_opt __deref_out_range(<, cchMax) size_t* pcchLength); #ifdef ALIGNMENT_MACHINE NTSTRSAFEWORKERDDI RtlUnalignedStringLengthWorkerW( __in STRSAFE_PCUNZWCH psz, __in __in_range(<=, NTSTRSAFE_MAX_CCH) size_t cchMax, __out_opt __deref_out_range(<, cchMax) size_t* pcchLength); #endif // ALIGNMENT_MACHINE NTSTRSAFEWORKERDDI RtlStringExValidateSrcA( __deref_in_opt_out NTSTRSAFE_PCSTR* ppszSrc, __inout_opt __deref_out_range(<, cchMax) size_t* pcchToRead, __in const size_t cchMax, __in DWORD dwFlags); NTSTRSAFEWORKERDDI RtlStringExValidateSrcW( __deref_in_opt_out NTSTRSAFE_PCWSTR* ppszSrc, __inout_opt __deref_out_range(<, cchMax) size_t* pcchToRead, __in const size_t cchMax, __in DWORD dwFlags); NTSTRSAFEWORKERDDI RtlStringValidateDestA( __in_ecount_opt(cchDest) STRSAFE_PCNZCH pszDest, __in size_t cchDest, __in const size_t cchMax); NTSTRSAFEWORKERDDI RtlStringValidateDestAndLengthA( __in_ecount_opt(cchDest) NTSTRSAFE_PCSTR pszDest, __in size_t cchDest, __out __deref_out_range(<, cchDest) size_t* pcchDestLength, __in const size_t cchMax); NTSTRSAFEWORKERDDI RtlStringValidateDestW( __in_ecount_opt(cchDest) STRSAFE_PCNZWCH pszDest, __in size_t cchDest, __in const size_t cchMax); NTSTRSAFEWORKERDDI RtlStringValidateDestAndLengthW( __in_ecount_opt(cchDest) NTSTRSAFE_PCWSTR pszDest, __in size_t cchDest, __out __deref_out_range(<, cchDest) size_t* pcchDestLength, __in const size_t cchMax); NTSTRSAFEWORKERDDI RtlStringExValidateDestA( __in_ecount_opt(cchDest) STRSAFE_PCNZCH pszDest, __in size_t cchDest, __in const size_t cchMax, __in DWORD dwFlags); NTSTRSAFEWORKERDDI RtlStringExValidateDestAndLengthA( __in_ecount_opt(cchDest) NTSTRSAFE_PCSTR pszDest, __in size_t cchDest, __out __deref_out_range(<, cchDest) size_t* pcchDestLength, __in const size_t cchMax, __in DWORD dwFlags); NTSTRSAFEWORKERDDI RtlStringExValidateDestW( __in_ecount_opt(cchDest) STRSAFE_PCNZWCH pszDest, __in size_t cchDest, __in const size_t cchMax, __in DWORD dwFlags); NTSTRSAFEWORKERDDI RtlStringExValidateDestAndLengthW( __in_ecount_opt(cchDest) NTSTRSAFE_PCWSTR pszDest, __in size_t cchDest, __out __deref_out_range(<, cchDest) size_t* pcchDestLength, __in const size_t cchMax, __in DWORD dwFlags); NTSTRSAFEWORKERDDI RtlStringCopyWorkerA( __out_ecount(cchDest) NTSTRSAFE_PSTR pszDest, __in __in_range(1, NTSTRSAFE_MAX_CCH) size_t cchDest, __out_opt __deref_out_range(<=, (cchToCopy < cchDest) ? cchToCopy : cchDest - 1) size_t* pcchNewDestLength, __in_xcount(cchToCopy) STRSAFE_PCNZCH pszSrc, __in __in_range(<, NTSTRSAFE_MAX_CCH) size_t cchToCopy); NTSTRSAFEWORKERDDI RtlStringCopyWorkerW( __out_ecount(cchDest) NTSTRSAFE_PWSTR pszDest, __in __in_range(1, NTSTRSAFE_MAX_CCH) size_t cchDest, __out_opt __deref_out_range(<=, (cchToCopy < cchDest) ? cchToCopy : cchDest - 1) size_t* pcchNewDestLength, __in_xcount(cchToCopy) STRSAFE_PCNZWCH pszSrc, __in __in_range(<, NTSTRSAFE_MAX_CCH) size_t cchToCopy); NTSTRSAFEWORKERDDI RtlStringVPrintfWorkerA( __out_ecount(cchDest) NTSTRSAFE_PSTR pszDest, __in __in_range(1, NTSTRSAFE_MAX_CCH) size_t cchDest, __out_opt __deref_out_range(<=, cchDest - 1) size_t* pcchNewDestLength, __in __format_string NTSTRSAFE_PCSTR pszFormat, __in va_list argList); NTSTRSAFEWORKERDDI RtlStringVPrintfWorkerW( __out_ecount(cchDest) NTSTRSAFE_PWSTR pszDest, __in __in_range(1, NTSTRSAFE_MAX_CCH) size_t cchDest, __out_opt __deref_out_range(<=, cchDest - 1) size_t* pcchNewDestLength, __in __format_string NTSTRSAFE_PCWSTR pszFormat, __in va_list argList); NTSTRSAFEWORKERDDI RtlStringExHandleFillBehindNullA( __inout_bcount(cbRemaining) NTSTRSAFE_PSTR pszDestEnd, __in size_t cbRemaining, __in DWORD dwFlags); NTSTRSAFEWORKERDDI RtlStringExHandleFillBehindNullW( __inout_bcount(cbRemaining) NTSTRSAFE_PWSTR pszDestEnd, __in size_t cbRemaining, __in DWORD dwFlags); NTSTRSAFEWORKERDDI RtlStringExHandleOtherFlagsA( __inout_bcount(cbDest) NTSTRSAFE_PSTR pszDest, __in __in_range(sizeof(char), NTSTRSAFE_MAX_CCH * sizeof(char)) size_t cbDest, __in __in_range(<, cbDest / sizeof(char)) size_t cchOriginalDestLength, __deref_inout_ecount(*pcchRemaining) NTSTRSAFE_PSTR* ppszDestEnd, __out __deref_out_range(<=, cbDest / sizeof(char)) size_t* pcchRemaining, __in DWORD dwFlags); NTSTRSAFEWORKERDDI RtlStringExHandleOtherFlagsW( __inout_bcount(cbDest) NTSTRSAFE_PWSTR pszDest, __in __in_range(sizeof(wchar_t), NTSTRSAFE_MAX_CCH * sizeof(wchar_t)) size_t cbDest, __in __in_range(<, cbDest / sizeof(wchar_t)) size_t cchOriginalDestLength, __deref_inout_ecount(*pcchRemaining) NTSTRSAFE_PWSTR* ppszDestEnd, __out __deref_out_range(<=, cbDest / sizeof(wchar_t)) size_t* pcchRemaining, __in DWORD dwFlags); #ifndef NTSTRSAFE_NO_UNICODE_STRING_FUNCTIONS NTSTRSAFEWORKERDDI RtlUnicodeStringInitWorker( __out PUNICODE_STRING DestinationString, __in_opt NTSTRSAFE_PCWSTR pszSrc, __in const size_t cchMax, __in DWORD dwFlags); NTSTRSAFEWORKERDDI RtlUnicodeStringValidateWorker( __in_opt PCUNICODE_STRING SourceString, __in const size_t cchMax, __in DWORD dwFlags); NTSTRSAFEWORKERDDI RtlUnicodeStringValidateSrcWorker( __in PCUNICODE_STRING SourceString, __deref_out_ecount(*pcchSrcLength) wchar_t** ppszSrc, __out size_t* pcchSrcLength, __in const size_t cchMax, __in DWORD dwFlags); NTSTRSAFEWORKERDDI RtlUnicodeStringValidateDestWorker( __in PCUNICODE_STRING DestinationString, __deref_out_ecount(*pcchDest) wchar_t** ppszDest, __out size_t* pcchDest, __out_opt size_t* pcchDestLength, __in const size_t cchMax, __in DWORD dwFlags); NTSTRSAFEWORKERDDI RtlStringCopyWideCharArrayWorker( __out_ecount(cchDest) NTSTRSAFE_PWSTR pszDest, __in size_t cchDest, __out_opt size_t* pcchNewDestLength, __in_ecount(cchSrcLength) const wchar_t* pszSrc, __in size_t cchSrcLength); NTSTRSAFEWORKERDDI RtlWideCharArrayCopyStringWorker( __out_ecount(cchDest) wchar_t* pszDest, __in size_t cchDest, __out size_t* pcchNewDestLength, __in NTSTRSAFE_PCWSTR pszSrc, __in size_t cchToCopy); NTSTRSAFEWORKERDDI RtlWideCharArrayCopyWorker( __out_ecount(cchDest) wchar_t* pszDest, __in size_t cchDest, __out size_t* pcchNewDestLength, __in_ecount(cchSrcLength) const wchar_t* pszSrc, __in size_t cchSrcLength); NTSTRSAFEWORKERDDI RtlWideCharArrayVPrintfWorker( __out_ecount(cchDest) wchar_t* pszDest, __in size_t cchDest, __out size_t* pcchNewDestLength, __in __format_string NTSTRSAFE_PCWSTR pszFormat, __in va_list argList); NTSTRSAFEWORKERDDI RtlUnicodeStringExHandleFill( __out_ecount(cchRemaining) wchar_t* pszDestEnd, __in size_t cchRemaining, __in DWORD dwFlags); NTSTRSAFEWORKERDDI RtlUnicodeStringExHandleOtherFlags( __inout_ecount(cchDest) wchar_t* pszDest, __in size_t cchDest, __in size_t cchOriginalDestLength, __out size_t* pcchNewDestLength, __deref_out_ecount(*pcchRemaining) wchar_t** ppszDestEnd, __out size_t* pcchRemaining, __in DWORD dwFlags); #endif // !NTSTRSAFE_NO_UNICODE_STRING_FUNCTIONS // To allow this to stand alone. #define __WARNING_CYCLOMATIC_COMPLEXITY 28734 #define __WARNING_DEREF_NULL_PTR 6011 #define __WARNING_INVALID_PARAM_VALUE_1 6387 #define __WARNING_POTENTIAL_BUFFER_OVERFLOW_HIGH_PRIORITY 26015 #define __WARNING_RETURNING_BAD_RESULT 28196 #define __WARNING_BANNED_API_USAGE 28719 #pragma warning(push) #if _MSC_VER <= 1400 #pragma warning(disable: 4616) // turn off warning out of range so prefast pragmas won't show // show up in build.wrn/build.err #endif #pragma warning(disable : 4996) // 'function': was declared deprecated #pragma warning(disable : 4995) // name was marked as #pragma deprecated #pragma warning(disable : 4793) // vararg causes native code generation #pragma warning(disable : __WARNING_CYCLOMATIC_COMPLEXITY) #ifndef NTSTRSAFE_LIB_IMPL #ifndef NTSTRSAFE_NO_CCH_FUNCTIONS /*++ NTSTATUS RtlStringCchCopy( __out_ecount(cchDest) LPTSTR pszDest, __in size_t cchDest, __in LPCTSTR pszSrc ); Routine Description: This routine is a safer version of the C built-in function 'strcpy'. The size of the destination buffer (in characters) 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 not a replacement for strncpy. That function will pad the destination string with extra null termination characters if the count is greater than the length of the source string, and it will fail to null terminate the destination string if the source string length is greater than or equal to the count. You can not blindly use this instead of strncpy: it is common for code to use it to "patch" strings and you would introduce errors if the code started null terminating in the middle of the string. This function returns an NTSTATUS value, and not a pointer. It returns STATUS_SUCCESS if the string was copied without truncation and 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 cchDest - size of destination buffer in characters. length must be = (_tcslen(src) + 1) to hold all of the source including the null terminator pszSrc - source string which must be null terminated Notes: Behavior is undefined if source and destination strings overlap. pszDest and pszSrc should not be NULL. See RtlStringCchCopyEx 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 RtlStringCchCopyA( __out_ecount(cchDest) NTSTRSAFE_PSTR pszDest, __in size_t cchDest, __in NTSTRSAFE_PCSTR pszSrc) { NTSTATUS status; status = RtlStringValidateDestA(pszDest, cchDest, NTSTRSAFE_MAX_CCH); if (NT_SUCCESS(status)) { status = RtlStringCopyWorkerA(pszDest, cchDest, NULL, pszSrc, NTSTRSAFE_MAX_LENGTH); } return status; } NTSTRSAFEDDI RtlStringCchCopyW( __out_ecount(cchDest) NTSTRSAFE_PWSTR pszDest, __in size_t cchDest, __in NTSTRSAFE_PCWSTR pszSrc) { NTSTATUS status; status = RtlStringValidateDestW(pszDest, cchDest, NTSTRSAFE_MAX_CCH); if (NT_SUCCESS(status)) { status = RtlStringCopyWorkerW(pszDest, cchDest, NULL, pszSrc, NTSTRSAFE_MAX_LENGTH); } return status; } #endif // !NTSTRSAFE_NO_CCH_FUNCTIONS #ifndef NTSTRSAFE_NO_CB_FUNCTIONS /*++ NTSTATUS RtlStringCbCopy( __out_bcount(cbDest) LPTSTR pszDest, __in size_t cbDest, __in LPCTSTR pszSrc ); Routine Description: This routine is a safer version of the C built-in function 'strcpy'. 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 not a replacement for strncpy. That function will pad the destination string with extra null termination characters if the count is greater than the length of the source string, and it will fail to null terminate the destination string if the source string length is greater than or equal to the count. You can not blindly use this instead of strncpy: it is common for code to use it to "patch" strings and you would introduce errors if the code started null terminating in the middle of the string. This function returns an NTSTATUS value, and not a pointer. It returns STATUS_SUCCESS if the string was copied without truncation and 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 which must be null terminated 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 - 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 RtlStringCbCopyA( __out_bcount(cbDest) NTSTRSAFE_PSTR pszDest, __in size_t cbDest, __in NTSTRSAFE_PCSTR pszSrc) { NTSTATUS status; size_t cchDest = cbDest / sizeof(char); status = RtlStringValidateDestA(pszDest, cchDest, NTSTRSAFE_MAX_CCH); if (NT_SUCCESS(status)) { status = RtlStringCopyWorkerA(pszDest, cchDest, NULL, pszSrc, NTSTRSAFE_MAX_LENGTH); } return status; } NTSTRSAFEDDI RtlStringCbCopyW( __out_bcount(cbDest) NTSTRSAFE_PWSTR pszDest, __in size_t cbDest, __in NTSTRSAFE_PCWSTR pszSrc) { NTSTATUS status; size_t cchDest = cbDest / sizeof(wchar_t); status = RtlStringValidateDestW(pszDest, cchDest, NTSTRSAFE_MAX_CCH); if (NT_SUCCESS(status)) { status = RtlStringCopyWorkerW(pszDest, cchDest, NULL, pszSrc, NTSTRSAFE_MAX_LENGTH); } return status; } #endif // !NTSTRSAFE_NO_CB_FUNCTIONS #ifndef NTSTRSAFE_NO_CCH_FUNCTIONS /*++ NTSTATUS RtlStringCchCopyEx( __out_ecount(cchDest) LPTSTR pszDest OPTIONAL, __in size_t cchDest, __in LPCTSTR pszSrc OPTIONAL, __deref_opt_out_ecount(*pcchRemaining) LPTSTR* ppszDestEnd OPTIONAL, __out_opt size_t* pcchRemaining OPTIONAL, __in DWORD dwFlags ); Routine Description: This routine is a safer version of the C built-in function 'strcpy' with some additional parameters. In addition to functionality provided by RtlStringCchCopy, this routine also returns a pointer to the end of the destination string and the number of characters left in the destination string including the null terminator. The flags parameter allows additional controls. Arguments: pszDest - destination string cchDest - size of destination buffer in characters. length must be = (_tcslen(pszSrc) + 1) to hold all of the source including the null terminator pszSrc - source string which must be null terminated ppszDestEnd - if ppszDestEnd is non-null, the function will return a pointer to the end of the destination string. If the function copied any data, the result will point to the null termination character pcchRemaining - if pcchRemaining is non-null, the function will return the number of characters left in the destination string, including the null terminator dwFlags - controls some details of the string copy: STRSAFE_FILL_BEHIND_NULL if the function succeeds, the low byte of dwFlags will be used to fill the uninitialize part of destination buffer behind the null terminator STRSAFE_IGNORE_NULLS treat NULL string pointers like empty strings (TEXT("")). this flag is useful for emulating functions like lstrcpy STRSAFE_FILL_ON_FAILURE if the function fails, the low byte of dwFlags will be used to fill all of the destination buffer, and it will be null terminated. This will overwrite any truncated string returned when the failure is STATUS_BUFFER_OVERFLOW STRSAFE_NO_TRUNCATION / STRSAFE_NULL_ON_FAILURE if the function fails, the destination buffer will be set to the empty string. This will overwrite any truncated string returned when the failure is STATUS_BUFFER_OVERFLOW. Notes: Behavior is undefined if source and destination strings overlap. pszDest and pszSrc should not be NULL unless the STRSAFE_IGNORE_NULLS flag is specified. If STRSAFE_IGNORE_NULLS is passed, both pszDest and pszSrc may be NULL. An error may still be returned even though NULLS are ignored due to insufficient space. 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 RtlStringCchCopyExA( __out_ecount(cchDest) NTSTRSAFE_PSTR pszDest, __in size_t cchDest, __in NTSTRSAFE_PCSTR pszSrc, __deref_opt_out_ecount(*pcchRemaining) NTSTRSAFE_PSTR* ppszDestEnd, __out_opt size_t* pcchRemaining, __in DWORD dwFlags) { NTSTATUS status; status = RtlStringExValidateDestA(pszDest, cchDest, NTSTRSAFE_MAX_CCH, dwFlags); if (NT_SUCCESS(status)) { NTSTRSAFE_PSTR pszDestEnd = pszDest; size_t cchRemaining = cchDest; status = RtlStringExValidateSrcA(&pszSrc, NULL, NTSTRSAFE_MAX_CCH, dwFlags); if (NT_SUCCESS(status)) { if (dwFlags & (~STRSAFE_VALID_FLAGS)) { status = STATUS_INVALID_PARAMETER; if (cchDest != 0) { *pszDest = '\0'; } } else if (cchDest == 0) { // only fail if there was actually src data to copy if (*pszSrc != '\0') { if (pszDest == NULL) { status = STATUS_INVALID_PARAMETER; } else { status = STATUS_BUFFER_OVERFLOW; } } } else { size_t cchCopied = 0; status = RtlStringCopyWorkerA(pszDest, cchDest, &cchCopied, pszSrc, NTSTRSAFE_MAX_LENGTH); pszDestEnd = pszDest + cchCopied; cchRemaining = cchDest - cchCopied; if (NT_SUCCESS(status) && (dwFlags & STRSAFE_FILL_BEHIND_NULL) && (cchRemaining > 1)) { size_t cbRemaining; // safe to multiply cchRemaining * sizeof(char) since cchRemaining < NTSTRSAFE_MAX_CCH and sizeof(char) is 1 cbRemaining = cchRemaining * sizeof(char); // handle the STRSAFE_FILL_BEHIND_NULL flag RtlStringExHandleFillBehindNullA(pszDestEnd, cbRemaining, dwFlags); } } } else { if (cchDest != 0) { *pszDest = '\0'; } } if (!NT_SUCCESS(status) && (dwFlags & (STRSAFE_NO_TRUNCATION | STRSAFE_FILL_ON_FAILURE | STRSAFE_NULL_ON_FAILURE)) && (cchDest != 0)) { size_t cbDest; // safe to multiply cchDest * sizeof(char) since cchDest < NTSTRSAFE_MAX_CCH and sizeof(char) is 1 cbDest = cchDest * sizeof(char); // handle the STRSAFE_FILL_ON_FAILURE, STRSAFE_NULL_ON_FAILURE, and STRSAFE_NO_TRUNCATION flags RtlStringExHandleOtherFlagsA(pszDest, cbDest, 0, &pszDestEnd, &cchRemaining, dwFlags); } if (NT_SUCCESS(status) || (status == STATUS_BUFFER_OVERFLOW)) { if (ppszDestEnd) { *ppszDestEnd = pszDestEnd; } if (pcchRemaining) { *pcchRemaining = cchRemaining; } } } return status; } NTSTRSAFEDDI RtlStringCchCopyExW( __out_ecount(cchDest) NTSTRSAFE_PWSTR pszDest, __in size_t cchDest, __in NTSTRSAFE_PCWSTR pszSrc, __deref_opt_out_ecount(*pcchRemaining) NTSTRSAFE_PWSTR* ppszDestEnd, __out_opt size_t* pcchRemaining, __in DWORD dwFlags) { NTSTATUS status; status = RtlStringExValidateDestW(pszDest, cchDest, NTSTRSAFE_MAX_CCH, dwFlags); if (NT_SUCCESS(status)) { NTSTRSAFE_PWSTR pszDestEnd = pszDest; size_t cchRemaining = cchDest; status = RtlStringExValidateSrcW(&pszSrc, NULL, NTSTRSAFE_MAX_CCH, dwFlags); if (NT_SUCCESS(status)) { if (dwFlags & (~STRSAFE_VALID_FLAGS)) { status = STATUS_INVALID_PARAMETER; if (cchDest != 0) { *pszDest = L'\0'; } } else if (cchDest == 0) { // only fail if there was actually src data to copy if (*pszSrc != L'\0') { if (pszDest == NULL) { status = STATUS_INVALID_PARAMETER; } else { status = STATUS_BUFFER_OVERFLOW; } } } else { size_t cchCopied = 0; status = RtlStringCopyWorkerW(pszDest, cchDest, &cchCopied, pszSrc, NTSTRSAFE_MAX_LENGTH); pszDestEnd = pszDest + cchCopied; cchRemaining = cchDest - cchCopied; if (NT_SUCCESS(status) && (dwFlags & STRSAFE_FILL_BEHIND_NULL) && (cchRemaining > 1)) { size_t cbRemaining; // safe to multiply cchRemaining * sizeof(wchar_t) since cchRemaining < NTSTRSAFE_MAX_CCH and sizeof(wchar_t) is 2 cbRemaining = cchRemaining * sizeof(wchar_t); // handle the STRSAFE_FILL_BEHIND_NULL flag RtlStringExHandleFillBehindNullW(pszDestEnd, cbRemaining, dwFlags); } } } else { if (cchDest != 0) { *pszDest = L'\0'; } } if (!NT_SUCCESS(status) && (dwFlags & (STRSAFE_NO_TRUNCATION | STRSAFE_FILL_ON_FAILURE | STRSAFE_NULL_ON_FAILURE)) && (cchDest != 0)) { size_t cbDest; // safe to multiply cchDest * sizeof(wchar_t) since cchDest < NTSTRSAFE_MAX_CCH and sizeof(wchar_t) is 2 cbDest = cchDest * sizeof(wchar_t); // handle the STRSAFE_FILL_ON_FAILURE, STRSAFE_NULL_ON_FAILURE, and STRSAFE_NO_TRUNCATION flags RtlStringExHandleOtherFlagsW(pszDest, cbDest, 0, &pszDestEnd, &cchRemaining, dwFlags); } if (NT_SUCCESS(status) || (status == STATUS_BUFFER_OVERFLOW)) { if (ppszDestEnd) { *ppszDestEnd = pszDestEnd; } if (pcchRemaining) { *pcchRemaining = cchRemaining; } } } return status; } #endif // !NTSTRSAFE_NO_CCH_FUNCTIONS #ifndef NTSTRSAFE_NO_CB_FUNCTIONS /*++ NTSTATUS RtlStringCbCopyEx( __out_bcount(cbDest) LPTSTR pszDest OPTIONAL, __in size_t cbDest, __in LPCTSTR pszSrc OPTIONAL, __deref_opt_out_bcount(*pcbRemaining) LPTSTR* ppszDestEnd OPTIONAL, __out_opt size_t* pcbRemaining OPTIONAL, __in DWORD dwFlags ); Routine Description: This routine is a safer version of the C built-in function 'strcpy' with some additional parameters. In addition to functionality provided by RtlStringCbCopy, this routine also returns a pointer to the end of the destination string and the number of bytes left in the destination string including the null terminator. The flags parameter allows additional controls. Arguments: pszDest - destination string cbDest - size of destination buffer in bytes. length must be ((_tcslen(pszSrc) + 1) * sizeof(TCHAR)) to hold all of the source including the null terminator pszSrc - source string which must be null terminated ppszDestEnd - if ppszDestEnd is non-null, the function will return a pointer to the end of the destination string. If the function copied any data, the result will point to the null termination character pcbRemaining - pcbRemaining is non-null,the function will return the number of bytes left in the destination string, including the null terminator dwFlags - controls some details of the string copy: STRSAFE_FILL_BEHIND_NULL if the function succeeds, the low byte of dwFlags will be used to fill the uninitialize part of destination buffer behind the null terminator STRSAFE_IGNORE_NULLS treat NULL string pointers like empty strings (TEXT("")). this flag is useful for emulating functions like lstrcpy STRSAFE_FILL_ON_FAILURE if the function fails, the low byte of dwFlags will be used to fill all of the destination buffer, and it will be null terminated. This will overwrite any truncated string returned when the failure is STATUS_BUFFER_OVERFLOW STRSAFE_NO_TRUNCATION / STRSAFE_NULL_ON_FAILURE if the function fails, the destination buffer will be set to the empty string. This will overwrite any truncated string returned when the failure is STATUS_BUFFER_OVERFLOW. Notes: Behavior is undefined if source and destination strings overlap. pszDest and pszSrc should not be NULL unless the STRSAFE_IGNORE_NULLS flag is specified. If STRSAFE_IGNORE_NULLS is passed, both pszDest and pszSrc may be NULL. An error may still be returned even though NULLS are ignored due to insufficient space. 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 RtlStringCbCopyExA( __out_bcount(cbDest) NTSTRSAFE_PSTR pszDest, __in size_t cbDest, __in NTSTRSAFE_PCSTR pszSrc, __deref_opt_out_bcount(*pcbRemaining) NTSTRSAFE_PSTR* ppszDestEnd, __out_opt size_t* pcbRemaining, __in DWORD dwFlags) { NTSTATUS status; size_t cchDest = cbDest / sizeof(char); status = RtlStringExValidateDestA(pszDest, cchDest, NTSTRSAFE_MAX_CCH, dwFlags); if (NT_SUCCESS(status)) { NTSTRSAFE_PSTR pszDestEnd = pszDest; size_t cchRemaining = cchDest; status = RtlStringExValidateSrcA(&pszSrc, NULL, NTSTRSAFE_MAX_CCH, dwFlags); if (NT_SUCCESS(status)) { if (dwFlags & (~STRSAFE_VALID_FLAGS)) { status = STATUS_INVALID_PARAMETER; if (cchDest != 0) { *pszDest = '\0'; } } else if (cchDest == 0) { // only fail if there was actually src data to copy if (*pszSrc != '\0') { if (pszDest == NULL) { status = STATUS_INVALID_PARAMETER; } else { status = STATUS_BUFFER_OVERFLOW; } } } else { size_t cchCopied = 0; status = RtlStringCopyWorkerA(pszDest, cchDest, &cchCopied, pszSrc, NTSTRSAFE_MAX_LENGTH); pszDestEnd = pszDest + cchCopied; cchRemaining = cchDest - cchCopied; if (NT_SUCCESS(status) && (dwFlags & STRSAFE_FILL_BEHIND_NULL) && (cchRemaining > 1)) { size_t cbRemaining; // safe to multiply cchRemaining * sizeof(char) since cchRemaining < NTSTRSAFE_MAX_CCH and sizeof(char) is 1 cbRemaining = (cchRemaining * sizeof(char)) + (cbDest % sizeof(char)); // handle the STRSAFE_FILL_BEHIND_NULL flag RtlStringExHandleFillBehindNullA(pszDestEnd, cbRemaining, dwFlags); } } } else { if (cchDest != 0) { *pszDest = '\0'; } } if (!NT_SUCCESS(status) && (dwFlags & (STRSAFE_NO_TRUNCATION | STRSAFE_FILL_ON_FAILURE | STRSAFE_NULL_ON_FAILURE)) && (cbDest != 0)) { // handle the STRSAFE_FILL_ON_FAILURE, STRSAFE_NULL_ON_FAILURE, and STRSAFE_NO_TRUNCATION flags RtlStringExHandleOtherFlagsA(pszDest, cbDest, 0, &pszDestEnd, &cchRemaining, dwFlags); } if (NT_SUCCESS(status) || (status == STATUS_BUFFER_OVERFLOW)) { if (ppszDestEnd) { *ppszDestEnd = pszDestEnd; } if (pcbRemaining) { // safe to multiply cchRemaining * sizeof(char) since cchRemaining < NTSTRSAFE_MAX_CCH and sizeof(char) is 1 *pcbRemaining = (cchRemaining * sizeof(char)) + (cbDest % sizeof(char)); } } } return status; } NTSTRSAFEDDI RtlStringCbCopyExW( __out_bcount(cbDest) NTSTRSAFE_PWSTR pszDest, __in size_t cbDest, __in NTSTRSAFE_PCWSTR pszSrc, __deref_opt_out_bcount(*pcbRemaining) NTSTRSAFE_PWSTR* ppszDestEnd, __out_opt size_t* pcbRemaining, __in DWORD dwFlags) { NTSTATUS status; size_t cchDest = cbDest / sizeof(wchar_t); status = RtlStringExValidateDestW(pszDest, cchDest, NTSTRSAFE_MAX_CCH, dwFlags); if (NT_SUCCESS(status)) { NTSTRSAFE_PWSTR pszDestEnd = pszDest; size_t cchRemaining = cchDest; status = RtlStringExValidateSrcW(&pszSrc, NULL, NTSTRSAFE_MAX_CCH, dwFlags); if (NT_SUCCESS(status)) { if (dwFlags & (~STRSAFE_VALID_FLAGS)) { status = STATUS_INVALID_PARAMETER; if (cchDest != 0) { *pszDest = L'\0'; } } else if (cchDest == 0) { // only fail if there was actually src data to copy if (*pszSrc != L'\0') { if (pszDest == NULL) { status = STATUS_INVALID_PARAMETER; } else { status = STATUS_BUFFER_OVERFLOW; } } } else { size_t cchCopied = 0; status = RtlStringCopyWorkerW(pszDest, cchDest, &cchCopied, pszSrc, NTSTRSAFE_MAX_LENGTH); pszDestEnd = pszDest + cchCopied; cchRemaining = cchDest - cchCopied; if (NT_SUCCESS(status) && (dwFlags & STRSAFE_FILL_BEHIND_NULL)) { size_t cbRemaining; // safe to multiply cchRemaining * sizeof(wchar_t) since cchRemaining < NTSTRSAFE_MAX_CCH and sizeof(wchar_t) is 2 cbRemaining = (cchRemaining * sizeof(wchar_t)) + (cbDest % sizeof(wchar_t)); // handle the STRSAFE_FILL_BEHIND_NULL flag RtlStringExHandleFillBehindNullW(pszDestEnd, cbRemaining, dwFlags); } } } else { if (cchDest != 0) { *pszDest = L'\0'; } } if (!NT_SUCCESS(status) && (dwFlags & (STRSAFE_NO_TRUNCATION | STRSAFE_FILL_ON_FAILURE | STRSAFE_NULL_ON_FAILURE)) && (cbDest != 0)) { // handle the STRSAFE_FILL_ON_FAILURE, STRSAFE_NULL_ON_FAILURE, and STRSAFE_NO_TRUNCATION flags RtlStringExHandleOtherFlagsW(pszDest, cbDest, 0, &pszDestEnd, &cchRemaining, dwFlags); } if (NT_SUCCESS(status) || (status == STATUS_BUFFER_OVERFLOW)) { if (ppszDestEnd) { *ppszDestEnd = pszDestEnd; } if (pcbRemaining) { // safe to multiply cchRemaining * sizeof(wchar_t) since cchRemaining < NTSTRSAFE_MAX_CCH and sizeof(wchar_t) is 2 *pcbRemaining = (cchRemaining * sizeof(wchar_t)) + (cbDest % sizeof(wchar_t)); } } } return status; } #endif // !NTSTRSAFE_NO_CB_FUNCTIONS #ifndef NTSTRSAFE_NO_CCH_FUNCTIONS /*++ NTSTATUS RtlStringCchCopyN( __out_ecount(cchDest) LPTSTR pszDest, __in size_t cchDest, __in LPCTSTR pszSrc, __in size_t cchToCopy ); Routine Description: This routine is a safer version of the C built-in function 'strncpy'. The size of the destination buffer (in characters) 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 cchToCopy is greater than the length of pszSrc. This function returns an NTSTATUS value, and not a pointer. It returns STATUS_SUCCESS if the entire string or the first cchToCopy 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 cchDest - size of destination buffer in characters. length must be = (_tcslen(src) + 1) to hold all of the source including the null terminator pszSrc - source string cchToCopy - maximum number of characters 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 RtlStringCchCopyNEx 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 RtlStringCchCopyNA( __out_ecount(cchDest) NTSTRSAFE_PSTR pszDest, __in size_t cchDest, __in_ecount(cchToCopy) STRSAFE_PCNZCH pszSrc, __in size_t cchToCopy) { NTSTATUS status; status = RtlStringValidateDestA(pszDest, cchDest, NTSTRSAFE_MAX_CCH); if (NT_SUCCESS(status)) { if (cchToCopy > NTSTRSAFE_MAX_LENGTH) { status = STATUS_INVALID_PARAMETER; *pszDest = '\0'; } else { status = RtlStringCopyWorkerA(pszDest, cchDest, NULL, pszSrc, cchToCopy); } } return status; } NTSTRSAFEDDI RtlStringCchCopyNW( __out_ecount(cchDest) NTSTRSAFE_PWSTR pszDest, __in size_t cchDest, __in_ecount(cchToCopy) STRSAFE_PCNZWCH pszSrc, __in size_t cchToCopy) { NTSTATUS status; status = RtlStringValidateDestW(pszDest, cchDest, NTSTRSAFE_MAX_CCH); if (NT_SUCCESS(status)) { if (cchToCopy > NTSTRSAFE_MAX_LENGTH) { status = STATUS_INVALID_PARAMETER; *pszDest = L'\0'; } else { status = RtlStringCopyWorkerW(pszDest, cchDest, NULL, pszSrc, cchToCopy); } } return status; } #endif // !NTSTRSAFE_NO_CCH_FUNCTIONS #ifndef NTSTRSAFE_NO_CB_FUNCTIONS /*++ NTSTATUS RtlStringCbCopyN( __out_bcount(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 - 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 RtlStringCbCopyNA( __out_bcount(cbDest) NTSTRSAFE_PSTR pszDest, __in size_t cbDest, __in_bcount(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; } NTSTRSAFEDDI RtlStringCbCopyNW( __out_bcount(cbDest) NTSTRSAFE_PWSTR pszDest, __in size_t cbDest, __in_bcount(cbToCopy) STRSAFE_PCNZWCH pszSrc, __in size_t cbToCopy) { NTSTATUS status; size_t cchDest = cbDest / sizeof(wchar_t); status = RtlStringValidateDestW(pszDest, cchDest, NTSTRSAFE_MAX_CCH); if (NT_SUCCESS(status)) { size_t cchToCopy = cbToCopy / sizeof(wchar_t); if (cchToCopy > NTSTRSAFE_MAX_LENGTH) { status = STATUS_INVALID_PARAMETER; // Suppress espx false positive - cchDest cannot be 0 here #pragma warning(push) #pragma warning(disable : __WARNING_POTENTIAL_BUFFER_OVERFLOW_HIGH_PRIORITY) *pszDest = L'\0'; #pragma warning(pop) } else { status = RtlStringCopyWorkerW(pszDest, cchDest, NULL, pszSrc, cchToCopy); } } return status; } #endif // !NTSTRSAFE_NO_CB_FUNCTIONS #ifndef NTSTRSAFE_NO_CCH_FUNCTIONS /*++ NTSTATUS RtlStringCchCopyNEx( __out_ecount(cchDest) LPTSTR pszDest OPTIONAL, __in size_t cchDest, __in LPCTSTR pszSrc OPTIONAL, __in size_t cchToCopy, __deref_opt_out_ecount(*pcchRemaining) LPTSTR* ppszDestEnd OPTIONAL, __out_opt size_t* pcchRemaining OPTIONAL, __in DWORD dwFlags ); Routine Description: This routine is a safer version of the C built-in function 'strncpy' with some additional parameters. In addition to functionality provided by RtlStringCchCopyN, this routine also returns a pointer to the end of the destination string and the number of characters left in the destination string including the null terminator. The flags parameter allows additional controls. 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 cchToCopy is greater than the length of pszSrc. Arguments: pszDest - destination string cchDest - size of destination buffer in characters. length must be = (_tcslen(pszSrc) + 1) to hold all of the source including the null terminator pszSrc - source string cchToCopy - maximum number of characters to copy from the source string ppszDestEnd - if ppszDestEnd is non-null, the function will return a pointer to the end of the destination string. If the function copied any data, the result will point to the null termination character pcchRemaining - if pcchRemaining is non-null, the function will return the number of characters left in the destination string, including the null terminator dwFlags - controls some details of the string copy: STRSAFE_FILL_BEHIND_NULL if the function succeeds, the low byte of dwFlags will be used to fill the uninitialize part of destination buffer behind the null terminator STRSAFE_IGNORE_NULLS treat NULL string pointers like empty strings (TEXT("")). this flag is useful for emulating functions like lstrcpy STRSAFE_FILL_ON_FAILURE if the function fails, the low byte of dwFlags will be used to fill all of the destination buffer, and it will be null terminated. This will overwrite any truncated string returned when the failure is STATUS_BUFFER_OVERFLOW STRSAFE_NO_TRUNCATION / STRSAFE_NULL_ON_FAILURE if the function fails, the destination buffer will be set to the empty string. This will overwrite any truncated string returned when the failure is STATUS_BUFFER_OVERFLOW. Notes: Behavior is undefined if source and destination strings overlap. pszDest and pszSrc should not be NULL unless the STRSAFE_IGNORE_NULLS flag is specified. If STRSAFE_IGNORE_NULLS is passed, both pszDest and pszSrc may be NULL. An error may still be returned even though NULLS are ignored due to insufficient space. 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 RtlStringCchCopyNExA( __out_ecount(cchDest) NTSTRSAFE_PSTR pszDest, __in size_t cchDest, __in_ecount(cchToCopy) STRSAFE_PCNZCH pszSrc, __in size_t cchToCopy, __deref_opt_out_ecount(*pcchRemaining) NTSTRSAFE_PSTR* ppszDestEnd, __out_opt size_t* pcchRemaining, __in DWORD dwFlags) { NTSTATUS status; status = RtlStringExValidateDestA(pszDest, cchDest, NTSTRSAFE_MAX_CCH, dwFlags); if (NT_SUCCESS(status)) { NTSTRSAFE_PSTR pszDestEnd = pszDest; size_t cchRemaining = cchDest; status = RtlStringExValidateSrcA(&pszSrc, &cchToCopy, NTSTRSAFE_MAX_CCH, dwFlags); if (NT_SUCCESS(status)) { if (dwFlags & (~STRSAFE_VALID_FLAGS)) { status = STATUS_INVALID_PARAMETER; if (cchDest != 0) { *pszDest = '\0'; } } else if (cchDest == 0) { // only fail if there was actually src data to copy if ((cchToCopy != 0) && (*pszSrc != '\0')) { if (pszDest == NULL) { status = STATUS_INVALID_PARAMETER; } else { status = STATUS_BUFFER_OVERFLOW; } } } else { size_t cchCopied = 0; status = RtlStringCopyWorkerA(pszDest, cchDest, &cchCopied, pszSrc, cchToCopy); pszDestEnd = pszDest + cchCopied; cchRemaining = cchDest - cchCopied; if (NT_SUCCESS(status) && (dwFlags & STRSAFE_FILL_BEHIND_NULL) && (cchRemaining > 1)) { size_t cbRemaining; // safe to multiply cchRemaining * sizeof(char) since cchRemaining < NTSTRSAFE_MAX_CCH and sizeof(char) is 1 cbRemaining = cchRemaining * sizeof(char); // handle the STRSAFE_FILL_BEHIND_NULL flag RtlStringExHandleFillBehindNullA(pszDestEnd, cbRemaining, dwFlags); } } } else { if (cchDest != 0) { *pszDest = '\0'; } } if (!NT_SUCCESS(status) && (dwFlags & (STRSAFE_NO_TRUNCATION | STRSAFE_FILL_ON_FAILURE | STRSAFE_NULL_ON_FAILURE)) && (cchDest != 0)) { size_t cbDest; // safe to multiply cchDest * sizeof(char) since cchDest < NTSTRSAFE_MAX_CCH and sizeof(char) is 1 cbDest = cchDest * sizeof(char); // handle the STRSAFE_FILL_ON_FAILURE, STRSAFE_NULL_ON_FAILURE, and STRSAFE_NO_TRUNCATION flags RtlStringExHandleOtherFlagsA(pszDest, cbDest, 0, &pszDestEnd, &cchRemaining, dwFlags); } if (NT_SUCCESS(status) || (status == STATUS_BUFFER_OVERFLOW)) { if (ppszDestEnd) { *ppszDestEnd = pszDestEnd; } if (pcchRemaining) { *pcchRemaining = cchRemaining; } } } return status; } NTSTRSAFEDDI RtlStringCchCopyNExW( __out_ecount(cchDest) NTSTRSAFE_PWSTR pszDest, __in size_t cchDest, __in_ecount(cchToCopy) STRSAFE_PCNZWCH pszSrc, __in size_t cchToCopy, __deref_opt_out_ecount(*pcchRemaining) NTSTRSAFE_PWSTR* ppszDestEnd, __out_opt size_t* pcchRemaining, __in DWORD dwFlags) { NTSTATUS status; status = RtlStringExValidateDestW(pszDest, cchDest, NTSTRSAFE_MAX_CCH, dwFlags); if (NT_SUCCESS(status)) { NTSTRSAFE_PWSTR pszDestEnd = pszDest; size_t cchRemaining = cchDest; status = RtlStringExValidateSrcW(&pszSrc, &cchToCopy, NTSTRSAFE_MAX_CCH, dwFlags); if (NT_SUCCESS(status)) { if (dwFlags & (~STRSAFE_VALID_FLAGS)) { status = STATUS_INVALID_PARAMETER; if (cchDest != 0) { *pszDest = L'\0'; } } else if (cchDest == 0) { // only fail if there was actually src data to copy if ((cchToCopy != 0) && (*pszSrc != L'\0')) { if (pszDest == NULL) { status = STATUS_INVALID_PARAMETER; } else { status = STATUS_BUFFER_OVERFLOW; } } } else { size_t cchCopied = 0; status = RtlStringCopyWorkerW(pszDest, cchDest, &cchCopied, pszSrc, cchToCopy); pszDestEnd = pszDest + cchCopied; cchRemaining = cchDest - cchCopied; if (NT_SUCCESS(status) && (dwFlags & STRSAFE_FILL_BEHIND_NULL) && (cchRemaining > 1)) { size_t cbRemaining; // safe to multiply cchRemaining * sizeof(wchar_t) since cchRemaining < NTSTRSAFE_MAX_CCH and sizeof(wchar_t) is 2 cbRemaining = cchRemaining * sizeof(wchar_t); // handle the STRSAFE_FILL_BEHIND_NULL flag RtlStringExHandleFillBehindNullW(pszDestEnd, cbRemaining, dwFlags); } } } else { if (cchDest != 0) { *pszDest = L'\0'; } } if (!NT_SUCCESS(status) && (dwFlags & (STRSAFE_NO_TRUNCATION | STRSAFE_FILL_ON_FAILURE | STRSAFE_NULL_ON_FAILURE)) && (cchDest != 0)) { size_t cbDest; // safe to multiply cchDest * sizeof(wchar_t) since cchDest < NTSTRSAFE_MAX_CCH and sizeof(wchar_t) is 2 cbDest = cchDest * sizeof(wchar_t); // handle the STRSAFE_FILL_ON_FAILURE, STRSAFE_NULL_ON_FAILURE, and STRSAFE_NO_TRUNCATION flags RtlStringExHandleOtherFlagsW(pszDest, cbDest, 0, &pszDestEnd, &cchRemaining, dwFlags); } if (NT_SUCCESS(status) || (status == STATUS_BUFFER_OVERFLOW)) { if (ppszDestEnd) { *ppszDestEnd = pszDestEnd; } if (pcchRemaining) { *pcchRemaining = cchRemaining; } } } return status; } #endif // !NTSTRSAFE_NO_CCH_FUNCTIONS #ifndef NTSTRSAFE_NO_CB_FUNCTIONS /*++ NTSTATUS RtlStringCbCopyNEx( __out_bcount(cbDest) LPTSTR pszDest OPTIONAL, __in size_t cbDest, __in LPCTSTR pszSrc OPTIONAL, __in size_t cbToCopy, __deref_opt_out_bcount(*pcbRemaining) LPTSTR* ppszDestEnd OPTIONAL, __out_opt size_t* pcbRemaining OPTIONAL, __in DWORD dwFlags ); Routine Description: This routine is a safer version of the C built-in function 'strncpy' with some additional parameters. In addition to functionality provided by RtlStringCbCopyN, this routine also returns a pointer to the end of the destination string and the number of bytes left in the destination string including the null terminator. The flags parameter allows additional controls. 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. Arguments: pszDest - destination string cbDest - size of destination buffer in bytes. length must be ((_tcslen(pszSrc) + 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 ppszDestEnd - if ppszDestEnd is non-null, the function will return a pointer to the end of the destination string. If the function copied any data, the result will point to the null termination character pcbRemaining - pcbRemaining is non-null,the function will return the number of bytes left in the destination string, including the null terminator dwFlags - controls some details of the string copy: STRSAFE_FILL_BEHIND_NULL if the function succeeds, the low byte of dwFlags will be used to fill the uninitialize part of destination buffer behind the null terminator STRSAFE_IGNORE_NULLS treat NULL string pointers like empty strings (TEXT("")). this flag is useful for emulating functions like lstrcpy STRSAFE_FILL_ON_FAILURE if the function fails, the low byte of dwFlags will be used to fill all of the destination buffer, and it will be null terminated. This will overwrite any truncated string returned when the failure is STATUS_BUFFER_OVERFLOW STRSAFE_NO_TRUNCATION / STRSAFE_NULL_ON_FAILURE if the function fails, the destination buffer will be set to the empty string. This will overwrite any truncated string returned when the failure is STATUS_BUFFER_OVERFLOW. Notes: Behavior is undefined if source and destination strings overlap. pszDest and pszSrc should not be NULL unless the STRSAFE_IGNORE_NULLS flag is specified. If STRSAFE_IGNORE_NULLS is passed, both pszDest and pszSrc may be NULL. An error may still be returned even though NULLS are ignored due to insufficient space. 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 RtlStringCbCopyNExA( __out_bcount(cbDest) NTSTRSAFE_PSTR pszDest, __in size_t cbDest, __in_bcount(cbToCopy) STRSAFE_PCNZCH pszSrc, __in size_t cbToCopy, __deref_opt_out_bcount(*pcbRemaining) NTSTRSAFE_PSTR* ppszDestEnd, __out_opt size_t* pcbRemaining, __in DWORD dwFlags) { NTSTATUS status; size_t cchDest = cbDest / sizeof(char); status = RtlStringExValidateDestA(pszDest, cchDest, NTSTRSAFE_MAX_CCH, dwFlags); if (NT_SUCCESS(status)) { NTSTRSAFE_PSTR pszDestEnd = pszDest; size_t cchRemaining = cchDest; size_t cchToCopy = cbToCopy / sizeof(char); status = RtlStringExValidateSrcA(&pszSrc, &cchToCopy, NTSTRSAFE_MAX_CCH, dwFlags); if (NT_SUCCESS(status)) { if (dwFlags & (~STRSAFE_VALID_FLAGS)) { status = STATUS_INVALID_PARAMETER; if (cchDest != 0) { *pszDest = '\0'; } } else if (cchDest == 0) { // only fail if there was actually src data to copy if ((cchToCopy != 0) && (*pszSrc != '\0')) { if (pszDest == NULL) { status = STATUS_INVALID_PARAMETER; } else { status = STATUS_BUFFER_OVERFLOW; } } } else { size_t cchCopied = 0; status = RtlStringCopyWorkerA(pszDest, cchDest, &cchCopied, pszSrc, cchToCopy); pszDestEnd = pszDest + cchCopied; cchRemaining = cchDest - cchCopied; if (NT_SUCCESS(status) && (dwFlags & STRSAFE_FILL_BEHIND_NULL) && (cchRemaining > 1)) { size_t cbRemaining; // safe to multiply cchRemaining * sizeof(char) since cchRemaining < NTSTRSAFE_MAX_CCH and sizeof(char) is 1 cbRemaining = (cchRemaining * sizeof(char)) + (cbDest % sizeof(char)); // handle the STRSAFE_FILL_BEHIND_NULL flag RtlStringExHandleFillBehindNullA(pszDestEnd, cbRemaining, dwFlags); } } } else { if (cchDest != 0) { *pszDest = '\0'; } } if (!NT_SUCCESS(status) && (dwFlags & (STRSAFE_NO_TRUNCATION | STRSAFE_FILL_ON_FAILURE | STRSAFE_NULL_ON_FAILURE)) && (cbDest != 0)) { // handle the STRSAFE_FILL_ON_FAILURE, STRSAFE_NULL_ON_FAILURE, and STRSAFE_NO_TRUNCATION flags RtlStringExHandleOtherFlagsA(pszDest, cbDest, 0, &pszDestEnd, &cchRemaining, dwFlags); } if (NT_SUCCESS(status) || (status == STATUS_BUFFER_OVERFLOW)) { if (ppszDestEnd) { *ppszDestEnd = pszDestEnd; } if (pcbRemaining) { // safe to multiply cchRemaining * sizeof(char) since cchRemaining < NTSTRSAFE_MAX_CCH and sizeof(char) is 1 *pcbRemaining = (cchRemaining * sizeof(char)) + (cbDest % sizeof(char)); } } } return status; } NTSTRSAFEDDI RtlStringCbCopyNExW( __out_bcount(cbDest) NTSTRSAFE_PWSTR pszDest, __in size_t cbDest, __in_bcount(cbToCopy) STRSAFE_PCNZWCH pszSrc, __in size_t cbToCopy, __deref_opt_out_bcount(*pcbRemaining) NTSTRSAFE_PWSTR* ppszDestEnd, __out_opt size_t* pcbRemaining, __in DWORD dwFlags) { NTSTATUS status; size_t cchDest = cbDest / sizeof(wchar_t); status = RtlStringExValidateDestW(pszDest, cchDest, NTSTRSAFE_MAX_CCH, dwFlags); if (NT_SUCCESS(status)) { NTSTRSAFE_PWSTR pszDestEnd = pszDest; size_t cchRemaining = cchDest; size_t cchToCopy = cbToCopy / sizeof(wchar_t); #pragma warning(push) #pragma warning(disable : __WARNING_POTENTIAL_BUFFER_OVERFLOW_HIGH_PRIORITY) status = RtlStringExValidateSrcW(&pszSrc, &cchToCopy, NTSTRSAFE_MAX_CCH, dwFlags); #pragma warning(pop) if (NT_SUCCESS(status)) { if (dwFlags & (~STRSAFE_VALID_FLAGS)) { status = STATUS_INVALID_PARAMETER; if (cchDest != 0) { *pszDest = L'\0'; } } else if (cchDest == 0) { // only fail if there was actually src data to copy if ((cchToCopy != 0) && (*pszSrc != L'\0')) { if (pszDest == NULL) { status = STATUS_INVALID_PARAMETER; } else { status = STATUS_BUFFER_OVERFLOW; } } } else { size_t cchCopied = 0; status = RtlStringCopyWorkerW(pszDest, cchDest, &cchCopied, pszSrc, cchToCopy); pszDestEnd = pszDest + cchCopied; cchRemaining = cchDest - cchCopied; if (NT_SUCCESS(status) && (dwFlags & STRSAFE_FILL_BEHIND_NULL)) { size_t cbRemaining; // safe to multiply cchRemaining * sizeof(wchar_t) since cchRemaining < NTSTRSAFE_MAX_CCH and sizeof(wchar_t) is 2 cbRemaining = (cchRemaining * sizeof(wchar_t)) + (cbDest % sizeof(wchar_t)); // handle the STRSAFE_FILL_BEHIND_NULL flag RtlStringExHandleFillBehindNullW(pszDestEnd, cbRemaining, dwFlags); } } } else { if (cchDest != 0) { *pszDest = L'\0'; } } if (!NT_SUCCESS(status) && (dwFlags & (STRSAFE_NO_TRUNCATION | STRSAFE_FILL_ON_FAILURE | STRSAFE_NULL_ON_FAILURE)) && (cbDest != 0)) { // handle the STRSAFE_FILL_ON_FAILURE, STRSAFE_NULL_ON_FAILURE, and STRSAFE_NO_TRUNCATION flags RtlStringExHandleOtherFlagsW(pszDest, cbDest, 0, &pszDestEnd, &cchRemaining, dwFlags); } if (NT_SUCCESS(status) || (status == STATUS_BUFFER_OVERFLOW)) { if (ppszDestEnd) { *ppszDestEnd = pszDestEnd; } if (pcbRemaining) { // safe to multiply cchRemaining * sizeof(wchar_t) since cchRemaining < NTSTRSAFE_MAX_CCH and sizeof(wchar_t) is 2 *pcbRemaining = (cchRemaining * sizeof(wchar_t)) + (cbDest % sizeof(wchar_t)); } } } return status; } #endif // !NTSTRSAFE_NO_CB_FUNCTIONS #ifndef NTSTRSAFE_NO_CCH_FUNCTIONS /*++ NTSTATUS RtlStringCchCat( __inout_ecount(cchDest) LPTSTR pszDest, __in size_t cchDest, __in LPCTSTR pszSrc ); Routine Description: This routine is a safer version of the C built-in function 'strcat'. The size of the destination buffer (in characters) 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 function returns an NTSTATUS value, and not a pointer. It returns STATUS_SUCCESS if the string was concatenated without truncation and 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) + _tcslen(pszSrc) + 1) to hold all of the combine string plus the null terminator pszSrc - source string which must be null terminated Notes: Behavior is undefined if source and destination strings overlap. pszDest and pszSrc should not be NULL. See RtlStringCchCatEx if you require the handling of NULL values. Return Value: STATUS_SUCCESS - if there was source data and it was all concatenated 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 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 RtlStringCchCatA( __inout_ecount(cchDest) NTSTRSAFE_PSTR pszDest, __in size_t cchDest, __in NTSTRSAFE_PCSTR pszSrc) { NTSTATUS status; size_t cchDestLength; status = RtlStringValidateDestAndLengthA(pszDest, cchDest, &cchDestLength, NTSTRSAFE_MAX_CCH); if (NT_SUCCESS(status)) { status = RtlStringCopyWorkerA(pszDest + cchDestLength, cchDest - cchDestLength, NULL, pszSrc, NTSTRSAFE_MAX_CCH); } return status; } NTSTRSAFEDDI RtlStringCchCatW( __inout_ecount(cchDest) NTSTRSAFE_PWSTR pszDest, __in size_t cchDest, __in NTSTRSAFE_PCWSTR pszSrc) { NTSTATUS status; size_t cchDestLength; status = RtlStringValidateDestAndLengthW(pszDest, cchDest, &cchDestLength, NTSTRSAFE_MAX_CCH); if (NT_SUCCESS(status)) { status = RtlStringCopyWorkerW(pszDest + cchDestLength, cchDest - cchDestLength, NULL, pszSrc, NTSTRSAFE_MAX_CCH); } return status; } #endif // !NTSTRSAFE_NO_CCH_FUNCTIONS #ifndef NTSTRSAFE_NO_CB_FUNCTIONS /*++ NTSTATUS RtlStringCbCat( __inout_bcount(cbDest) LPTSTR pszDest, __in size_t cbDest, __in LPCTSTR pszSrc ); Routine Description: This routine is a safer version of the C built-in function 'strcat'. 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 function returns an NTSTATUS value, and not a pointer. It returns STATUS_SUCCESS if the string was concatenated without truncation and 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 cbDest - size of destination buffer in bytes. length must be = ((_tcslen(pszDest) + _tcslen(pszSrc) + 1) * sizeof(TCHAR) to hold all of the combine string plus the null terminator pszSrc - source string which must be null terminated Notes: Behavior is undefined if source and destination strings overlap. pszDest and pszSrc should not be NULL. See RtlStringCbCatEx if you require the handling of NULL values. Return Value: STATUS_SUCCESS - if there was source data and it was all concatenated 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 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 RtlStringCbCatA( __inout_bcount(cbDest) NTSTRSAFE_PSTR pszDest, __in size_t cbDest, __in NTSTRSAFE_PCSTR pszSrc) { NTSTATUS status; size_t cchDestLength; size_t cchDest = cbDest / sizeof(char); status = RtlStringValidateDestAndLengthA(pszDest, cchDest, &cchDestLength, NTSTRSAFE_MAX_CCH); if (NT_SUCCESS(status)) { status = RtlStringCopyWorkerA(pszDest + cchDestLength, cchDest - cchDestLength, NULL, pszSrc, NTSTRSAFE_MAX_CCH); } return status; } NTSTRSAFEDDI RtlStringCbCatW( __inout_bcount(cbDest) NTSTRSAFE_PWSTR pszDest, __in size_t cbDest, __in NTSTRSAFE_PCWSTR pszSrc) { NTSTATUS status; size_t cchDestLength; size_t cchDest = cbDest / sizeof(wchar_t); status = RtlStringValidateDestAndLengthW(pszDest, cchDest, &cchDestLength, NTSTRSAFE_MAX_CCH); if (NT_SUCCESS(status)) { status = RtlStringCopyWorkerW(pszDest + cchDestLength, cchDest - cchDestLength, NULL, pszSrc, NTSTRSAFE_MAX_CCH); } return status; } #endif // !NTSTRSAFE_NO_CB_FUNCTIONS #ifndef NTSTRSAFE_NO_CCH_FUNCTIONS /*++ NTSTATUS RtlStringCchCatEx( __inout_ecount(cchDest) LPTSTR pszDest OPTIONAL, __in size_t cchDest, __in LPCTSTR pszSrc OPTIONAL, __deref_opt_out_ecount(*pcchRemaining) LPTSTR* ppszDestEnd OPTIONAL, __out_opt size_t* pcchRemaining OPTIONAL, __in DWORD dwFlags ); Routine Description: This routine is a safer version of the C built-in function 'strcat' with some additional parameters. In addition to functionality provided by RtlStringCchCat, this routine also returns a pointer to the end of the destination string and the number of characters left in the destination string including the null terminator. The flags parameter allows additional controls. Arguments: pszDest - destination string which must be null terminated cchDest - size of destination buffer in characters length must be (_tcslen(pszDest) + _tcslen(pszSrc) + 1) to hold all of the combine string plus the null terminator. pszSrc - source string which must be null terminated ppszDestEnd - if ppszDestEnd is non-null, the function will return a pointer to the end of the destination string. If the function appended any data, the result will point to the null termination character pcchRemaining - if pcchRemaining is non-null, the function will return the number of characters left in the destination string, including the null terminator dwFlags - controls some details of the string copy: STRSAFE_FILL_BEHIND_NULL if the function succeeds, the low byte of dwFlags will be used to fill the uninitialize part of destination buffer behind the null terminator STRSAFE_IGNORE_NULLS treat NULL string pointers like empty strings (TEXT("")). this flag is useful for emulating functions like lstrcat STRSAFE_FILL_ON_FAILURE if the function fails, the low byte of dwFlags will be used to fill all of the destination buffer, and it will be null terminated. This will overwrite any pre-existing or truncated string STRSAFE_NULL_ON_FAILURE if the function fails, the destination buffer will be set to the empty string. This will overwrite any pre-existing or truncated string STRSAFE_NO_TRUNCATION if the function returns STATUS_BUFFER_OVERFLOW, pszDest will not contain a truncated string, it will remain unchanged. Notes: Behavior is undefined if source and destination strings overlap. pszDest and pszSrc should not be NULL unless the STRSAFE_IGNORE_NULLS flag is specified. If STRSAFE_IGNORE_NULLS is passed, both pszDest and pszSrc may be NULL. An error may still be returned even though NULLS are ignored due to insufficient space. Return Value: STATUS_SUCCESS - if there was source data and it was all concatenated 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 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 RtlStringCchCatExA( __inout_ecount(cchDest) NTSTRSAFE_PSTR pszDest, __in size_t cchDest, __in NTSTRSAFE_PCSTR pszSrc, __deref_opt_out_ecount(*pcchRemaining) NTSTRSAFE_PSTR* ppszDestEnd, __out_opt size_t* pcchRemaining, __in DWORD dwFlags) { NTSTATUS status; size_t cchDestLength; status = RtlStringExValidateDestAndLengthA(pszDest, cchDest, &cchDestLength, NTSTRSAFE_MAX_CCH, dwFlags); if (NT_SUCCESS(status)) { NTSTRSAFE_PSTR pszDestEnd = pszDest + cchDestLength; size_t cchRemaining = cchDest - cchDestLength; status = RtlStringExValidateSrcA(&pszSrc, NULL, NTSTRSAFE_MAX_CCH, dwFlags); if (NT_SUCCESS(status)) { if (dwFlags & (~STRSAFE_VALID_FLAGS)) { status = STATUS_INVALID_PARAMETER; } else if (cchRemaining <= 1) { // only fail if there was actually src data to append if (*pszSrc != '\0') { if (pszDest == NULL) { status = STATUS_INVALID_PARAMETER; } else { status = STATUS_BUFFER_OVERFLOW; } } } else { size_t cchCopied = 0; status = RtlStringCopyWorkerA(pszDestEnd, cchRemaining, &cchCopied, pszSrc, NTSTRSAFE_MAX_LENGTH); pszDestEnd = pszDestEnd + cchCopied; cchRemaining = cchRemaining - cchCopied; if (NT_SUCCESS(status) && (dwFlags & STRSAFE_FILL_BEHIND_NULL) && (cchRemaining > 1)) { size_t cbRemaining; // safe to multiply cchRemaining * sizeof(char) since cchRemaining < NTSTRSAFE_MAX_CCH and sizeof(char) is 1 cbRemaining = cchRemaining * sizeof(char); // handle the STRSAFE_FILL_BEHIND_NULL flag RtlStringExHandleFillBehindNullA(pszDestEnd, cbRemaining, dwFlags); } } } if (!NT_SUCCESS(status) && (dwFlags & (STRSAFE_NO_TRUNCATION | STRSAFE_FILL_ON_FAILURE | STRSAFE_NULL_ON_FAILURE)) && (cchDest != 0)) { size_t cbDest; // safe to multiply cchDest * sizeof(char) since cchDest < NTSTRSAFE_MAX_CCH and sizeof(char) is 1 cbDest = cchDest * sizeof(char); // handle the STRSAFE_FILL_ON_FAILURE, STRSAFE_NULL_ON_FAILURE, and STRSAFE_NO_TRUNCATION flags RtlStringExHandleOtherFlagsA(pszDest, cbDest, cchDestLength, &pszDestEnd, &cchRemaining, dwFlags); } if (NT_SUCCESS(status) || (status == STATUS_BUFFER_OVERFLOW)) { if (ppszDestEnd) { *ppszDestEnd = pszDestEnd; } if (pcchRemaining) { *pcchRemaining = cchRemaining; } } } return status; } NTSTRSAFEDDI RtlStringCchCatExW( __inout_ecount(cchDest) NTSTRSAFE_PWSTR pszDest, __in size_t cchDest, __in NTSTRSAFE_PCWSTR pszSrc, __deref_opt_out_ecount(*pcchRemaining) NTSTRSAFE_PWSTR* ppszDestEnd, __out_opt size_t* pcchRemaining, __in DWORD dwFlags) { NTSTATUS status; size_t cchDestLength; status = RtlStringExValidateDestAndLengthW(pszDest, cchDest, &cchDestLength, NTSTRSAFE_MAX_CCH, dwFlags); if (NT_SUCCESS(status)) { NTSTRSAFE_PWSTR pszDestEnd = pszDest + cchDestLength; size_t cchRemaining = cchDest - cchDestLength; status = RtlStringExValidateSrcW(&pszSrc, NULL, NTSTRSAFE_MAX_CCH, dwFlags); if (NT_SUCCESS(status)) { if (dwFlags & (~STRSAFE_VALID_FLAGS)) { status = STATUS_INVALID_PARAMETER; } else if (cchRemaining <= 1) { // only fail if there was actually src data to append if (*pszSrc != L'\0') { if (pszDest == NULL) { status = STATUS_INVALID_PARAMETER; } else { status = STATUS_BUFFER_OVERFLOW; } } } else { size_t cchCopied = 0; status = RtlStringCopyWorkerW(pszDestEnd, cchRemaining, &cchCopied, pszSrc, NTSTRSAFE_MAX_LENGTH); pszDestEnd = pszDestEnd + cchCopied; cchRemaining = cchRemaining - cchCopied; if (NT_SUCCESS(status) && (dwFlags & STRSAFE_FILL_BEHIND_NULL) && (cchRemaining > 1)) { size_t cbRemaining; // safe to multiply cchRemaining * sizeof(wchar_t) since cchRemaining < NTSTRSAFE_MAX_CCH and sizeof(wchar_t) is 2 cbRemaining = cchRemaining * sizeof(wchar_t); // handle the STRSAFE_FILL_BEHIND_NULL flag RtlStringExHandleFillBehindNullW(pszDestEnd, cbRemaining, dwFlags); } } } if (!NT_SUCCESS(status) && (dwFlags & (STRSAFE_NO_TRUNCATION | STRSAFE_FILL_ON_FAILURE | STRSAFE_NULL_ON_FAILURE)) && (cchDest != 0)) { size_t cbDest; // safe to multiply cchDest * sizeof(char) since cchDest < NTSTRSAFE_MAX_CCH and sizeof(char) is 1 cbDest = cchDest * sizeof(wchar_t); // handle the STRSAFE_FILL_ON_FAILURE, STRSAFE_NULL_ON_FAILURE, and STRSAFE_NO_TRUNCATION flags RtlStringExHandleOtherFlagsW(pszDest, cbDest, cchDestLength, &pszDestEnd, &cchRemaining, dwFlags); } if (NT_SUCCESS(status) || (status == STATUS_BUFFER_OVERFLOW)) { if (ppszDestEnd) { *ppszDestEnd = pszDestEnd; } if (pcchRemaining) { *pcchRemaining = cchRemaining; } } } return status; } #endif // !NTSTRSAFE_NO_CCH_FUNCTIONS #ifndef NTSTRSAFE_NO_CB_FUNCTIONS /*++ NTSTATUS RtlStringCbCatEx( __inout_bcount(cbDest) LPTSTR pszDest OPTIONAL, __in size_t cbDest, __in LPCTSTR pszSrc OPTIONAL, __deref_opt_out_bcount(*pcbRemaining) LPTSTR* ppszDestEnd OPTIONAL, __out_opt size_t* pcbRemaining OPTIONAL, __in DWORD dwFlags ); Routine Description: This routine is a safer version of the C built-in function 'strcat' with some additional parameters. In addition to functionality provided by RtlStringCbCat, this routine also returns a pointer to the end of the destination string and the number of bytes left in the destination string including the null terminator. The flags parameter allows additional controls. Arguments: pszDest - destination string which must be null terminated cbDest - size of destination buffer in bytes. length must be ((_tcslen(pszDest) + _tcslen(pszSrc) + 1) * sizeof(TCHAR) to hold all of the combine string plus the null terminator. pszSrc - source string which must be null terminated ppszDestEnd - if ppszDestEnd is non-null, the function will return a pointer to the end of the destination string. If the function appended any data, the result will point to the null termination character pcbRemaining - if pcbRemaining is non-null, the function will return the number of bytes left in the destination string, including the null terminator dwFlags - controls some details of the string copy: STRSAFE_FILL_BEHIND_NULL if the function succeeds, the low byte of dwFlags will be used to fill the uninitialize part of destination buffer behind the null terminator STRSAFE_IGNORE_NULLS treat NULL string pointers like empty strings (TEXT("")). this flag is useful for emulating functions like lstrcat STRSAFE_FILL_ON_FAILURE if the function fails, the low byte of dwFlags will be used to fill all of the destination buffer, and it will be null terminated. This will overwrite any pre-existing or truncated string STRSAFE_NULL_ON_FAILURE if the function fails, the destination buffer will be set to the empty string. This will overwrite any pre-existing or truncated string STRSAFE_NO_TRUNCATION if the function returns STATUS_BUFFER_OVERFLOW, pszDest will not contain a truncated string, it will remain unchanged. Notes: Behavior is undefined if source and destination strings overlap. pszDest and pszSrc should not be NULL unless the STRSAFE_IGNORE_NULLS flag is specified. If STRSAFE_IGNORE_NULLS is passed, both pszDest and pszSrc may be NULL. An error may still be returned even though NULLS are ignored due to insufficient space. Return Value: STATUS_SUCCESS - if there was source data and it was all concatenated 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 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 RtlStringCbCatExA( __inout_bcount(cbDest) NTSTRSAFE_PSTR pszDest, __in size_t cbDest, __in NTSTRSAFE_PCSTR pszSrc, __deref_opt_out_bcount(*pcbRemaining) NTSTRSAFE_PSTR* ppszDestEnd, __out_opt size_t* pcbRemaining, __in DWORD dwFlags) { NTSTATUS status; size_t cchDest = cbDest / sizeof(char); size_t cchDestLength; status = RtlStringExValidateDestAndLengthA(pszDest, cchDest, &cchDestLength, NTSTRSAFE_MAX_CCH, dwFlags); if (NT_SUCCESS(status)) { NTSTRSAFE_PSTR pszDestEnd = pszDest + cchDestLength; size_t cchRemaining = cchDest - cchDestLength; status = RtlStringExValidateSrcA(&pszSrc, NULL, NTSTRSAFE_MAX_CCH, dwFlags); if (NT_SUCCESS(status)) { if (dwFlags & (~STRSAFE_VALID_FLAGS)) { status = STATUS_INVALID_PARAMETER; } else if (cchRemaining <= 1) { // only fail if there was actually src data to append if (*pszSrc != '\0') { if (pszDest == NULL) { status = STATUS_INVALID_PARAMETER; } else { status = STATUS_BUFFER_OVERFLOW; } } } else { size_t cchCopied = 0; status = RtlStringCopyWorkerA(pszDestEnd, cchRemaining, &cchCopied, pszSrc, NTSTRSAFE_MAX_LENGTH); pszDestEnd = pszDestEnd + cchCopied; cchRemaining = cchRemaining - cchCopied; if (NT_SUCCESS(status) && (dwFlags & STRSAFE_FILL_BEHIND_NULL) && (cchRemaining > 1)) { size_t cbRemaining; // safe to multiply cchRemaining * sizeof(char) since cchRemaining < NTSTRSAFE_MAX_CCH and sizeof(char) is 1 cbRemaining = (cchRemaining * sizeof(char)) + (cbDest % sizeof(char)); // handle the STRSAFE_FILL_BEHIND_NULL flag RtlStringExHandleFillBehindNullA(pszDestEnd, cbRemaining, dwFlags); } } } if (!NT_SUCCESS(status) && (dwFlags & (STRSAFE_NO_TRUNCATION | STRSAFE_FILL_ON_FAILURE | STRSAFE_NULL_ON_FAILURE)) && (cbDest != 0)) { // handle the STRSAFE_FILL_ON_FAILURE, STRSAFE_NULL_ON_FAILURE, and STRSAFE_NO_TRUNCATION flags RtlStringExHandleOtherFlagsA(pszDest, cbDest, cchDestLength, &pszDestEnd, &cchRemaining, dwFlags); } if (NT_SUCCESS(status) || (status == STATUS_BUFFER_OVERFLOW)) { if (ppszDestEnd) { *ppszDestEnd = pszDestEnd; } if (pcbRemaining) { // safe to multiply cchRemaining * sizeof(char) since cchRemaining < NTSTRSAFE_MAX_CCH and sizeof(char) is 1 *pcbRemaining = (cchRemaining * sizeof(char)) + (cbDest % sizeof(char)); } } } return status; } NTSTRSAFEDDI RtlStringCbCatExW( __inout_bcount(cbDest) NTSTRSAFE_PWSTR pszDest, __in size_t cbDest, __in NTSTRSAFE_PCWSTR pszSrc, __deref_opt_out_bcount(*pcbRemaining) NTSTRSAFE_PWSTR* ppszDestEnd, __out_opt size_t* pcbRemaining, __in DWORD dwFlags) { NTSTATUS status; size_t cchDest = cbDest / sizeof(wchar_t); size_t cchDestLength; status = RtlStringExValidateDestAndLengthW(pszDest, cchDest, &cchDestLength, NTSTRSAFE_MAX_CCH, dwFlags); if (NT_SUCCESS(status)) { NTSTRSAFE_PWSTR pszDestEnd = pszDest + cchDestLength; size_t cchRemaining = cchDest - cchDestLength; status = RtlStringExValidateSrcW(&pszSrc, NULL, NTSTRSAFE_MAX_CCH, dwFlags); if (NT_SUCCESS(status)) { if (dwFlags & (~STRSAFE_VALID_FLAGS)) { status = STATUS_INVALID_PARAMETER; } else if (cchRemaining <= 1) { // only fail if there was actually src data to append if (*pszSrc != L'\0') { if (pszDest == NULL) { status = STATUS_INVALID_PARAMETER; } else { status = STATUS_BUFFER_OVERFLOW; } } } else { size_t cchCopied = 0; status = RtlStringCopyWorkerW(pszDestEnd, cchRemaining, &cchCopied, pszSrc, NTSTRSAFE_MAX_LENGTH); pszDestEnd = pszDestEnd + cchCopied; cchRemaining = cchRemaining - cchCopied; if (NT_SUCCESS(status) && (dwFlags & STRSAFE_FILL_BEHIND_NULL)) { size_t cbRemaining; // safe to multiply cchRemaining * sizeof(wchar_t) since cchRemaining < NTSTRSAFE_MAX_CCH and sizeof(wchar_t) is 2 cbRemaining = (cchRemaining * sizeof(wchar_t)) + (cbDest % sizeof(wchar_t)); // handle the STRSAFE_FILL_BEHIND_NULL flag RtlStringExHandleFillBehindNullW(pszDestEnd, cbRemaining, dwFlags); } } } if (!NT_SUCCESS(status) && (dwFlags & (STRSAFE_NO_TRUNCATION | STRSAFE_FILL_ON_FAILURE | STRSAFE_NULL_ON_FAILURE)) && (cbDest != 0)) { // handle the STRSAFE_FILL_ON_FAILURE, STRSAFE_NULL_ON_FAILURE, and STRSAFE_NO_TRUNCATION flags RtlStringExHandleOtherFlagsW(pszDest, cbDest, cchDestLength, &pszDestEnd, &cchRemaining, dwFlags); } if (NT_SUCCESS(status) || (status == STATUS_BUFFER_OVERFLOW)) { if (ppszDestEnd) { *ppszDestEnd = pszDestEnd; } if (pcbRemaining) { // safe to multiply cchRemaining * sizeof(wchar_t) since cchRemaining < NTSTRSAFE_MAX_CCH and sizeof(wchar_t) is 2 *pcbRemaining = (cchRemaining * sizeof(wchar_t)) + (cbDest % sizeof(wchar_t)); } } } return status; } #endif // !NTSTRSAFE_NO_CB_FUNCTIONS #ifndef NTSTRSAFE_NO_CCH_FUNCTIONS /*++ NTSTATUS RtlStringCchCatN( __inout_ecount(cchDest) 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 - 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 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_ecount(cchDest) NTSTRSAFE_PSTR pszDest, __in size_t cchDest, __in_ecount(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; } NTSTRSAFEDDI RtlStringCchCatNW( __inout_ecount(cchDest) NTSTRSAFE_PWSTR pszDest, __in size_t cchDest, __in_ecount(cchToAppend) STRSAFE_PCNZWCH pszSrc, __in size_t cchToAppend) { NTSTATUS status; size_t cchDestLength; status = RtlStringValidateDestAndLengthW(pszDest, cchDest, &cchDestLength, NTSTRSAFE_MAX_CCH); if (NT_SUCCESS(status)) { if (cchToAppend > NTSTRSAFE_MAX_LENGTH) { status = STATUS_INVALID_PARAMETER; } else { status = RtlStringCopyWorkerW(pszDest + cchDestLength, cchDest - cchDestLength, NULL, pszSrc, cchToAppend); } } return status; } #endif // !NTSTRSAFE_NO_CCH_FUNCTIONS #ifndef NTSTRSAFE_NO_CB_FUNCTIONS /*++ NTSTATUS RtlStringCbCatN( __inout_bcount(cbDest) LPTSTR pszDest, __in size_t cbDest, __in LPCTSTR pszSrc, __in size_t cbToAppend ); Routine Description: This routine is a safer version of the C built-in function 'strncat'. The size of the destination buffer (in bytes) is a parameter as well as the maximum number of bytes 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 cbToAppend bytes 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 cbDest - size of destination buffer in bytes. length must be ((_tcslen(pszDest) + min(cbToAppend / sizeof(TCHAR), _tcslen(pszSrc)) + 1) * sizeof(TCHAR) to hold all of the combine string plus the null terminator. pszSrc - source string cbToAppend - maximum number of bytes to append Notes: Behavior is undefined if source and destination strings overlap. pszDest and pszSrc should not be NULL. See RtlStringCbCatNEx if you require the handling of NULL values. Return Value: STATUS_SUCCESS - if all of pszSrc or the first cbToAppend bytes were concatenated to pszDest 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 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 RtlStringCbCatNA( __inout_bcount(cbDest) NTSTRSAFE_PSTR pszDest, __in size_t cbDest, __in_bcount(cbToAppend) STRSAFE_PCNZCH pszSrc, __in size_t cbToAppend) { NTSTATUS status; size_t cchDest = cbDest / sizeof(char); size_t cchDestLength; status = RtlStringValidateDestAndLengthA(pszDest, cchDest, &cchDestLength, NTSTRSAFE_MAX_CCH); if (NT_SUCCESS(status)) { size_t cchToAppend = cbToAppend / sizeof(char); if (cchToAppend > NTSTRSAFE_MAX_LENGTH) { status = STATUS_INVALID_PARAMETER; } else { status = RtlStringCopyWorkerA(pszDest + cchDestLength, cchDest - cchDestLength, NULL, pszSrc, cchToAppend); } } return status; } NTSTRSAFEDDI RtlStringCbCatNW( __inout_bcount(cbDest) NTSTRSAFE_PWSTR pszDest, __in size_t cbDest, __in_bcount(cbToAppend) STRSAFE_PCNZWCH pszSrc, __in size_t cbToAppend) { NTSTATUS status; size_t cchDest = cbDest / sizeof(wchar_t); size_t cchDestLength; status = RtlStringValidateDestAndLengthW(pszDest, cchDest, &cchDestLength, NTSTRSAFE_MAX_CCH); if (NT_SUCCESS(status)) { size_t cchToAppend = cbToAppend / sizeof(wchar_t); if (cchToAppend > NTSTRSAFE_MAX_LENGTH) { status = STATUS_INVALID_PARAMETER; } else { status = RtlStringCopyWorkerW(pszDest + cchDestLength, cchDest - cchDestLength, NULL, pszSrc, cchToAppend); } } return status; } #endif // !NTSTRSAFE_NO_CB_FUNCTIONS #ifndef NTSTRSAFE_NO_CCH_FUNCTIONS /*++ NTSTATUS RtlStringCchCatNEx( __inout_ecount(cchDest) LPTSTR pszDest OPTIONAL, __in size_t cchDest, __in LPCTSTR pszSrc OPTIONAL, __in size_t cchToAppend, __deref_opt_out_ecount(*pcchRemaining) LPTSTR* ppszDestEnd OPTIONAL, __out_opt size_t* pcchRemaining OPTIONAL, __in DWORD dwFlags ); Routine Description: This routine is a safer version of the C built-in function 'strncat', with some additional parameters. In addition to functionality provided by RtlStringCchCatN, this routine also returns a pointer to the end of the destination string and the number of characters left in the destination string including the null terminator. The flags parameter allows additional controls. 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 ppszDestEnd - if ppszDestEnd is non-null, the function will return a pointer to the end of the destination string. If the function appended any data, the result will point to the null termination character pcchRemaining - if pcchRemaining is non-null, the function will return the number of characters left in the destination string, including the null terminator dwFlags - controls some details of the string copy: STRSAFE_FILL_BEHIND_NULL if the function succeeds, the low byte of dwFlags will be used to fill the uninitialize part of destination buffer behind the null terminator STRSAFE_IGNORE_NULLS treat NULL string pointers like empty strings (TEXT("")) STRSAFE_FILL_ON_FAILURE if the function fails, the low byte of dwFlags will be used to fill all of the destination buffer, and it will be null terminated. This will overwrite any pre-existing or truncated string STRSAFE_NULL_ON_FAILURE if the function fails, the destination buffer will be set to the empty string. This will overwrite any pre-existing or truncated string STRSAFE_NO_TRUNCATION if the function returns STATUS_BUFFER_OVERFLOW, pszDest will not contain a truncated string, it will remain unchanged. Notes: Behavior is undefined if source and destination strings overlap. pszDest and pszSrc should not be NULL unless the STRSAFE_IGNORE_NULLS flag is specified. If STRSAFE_IGNORE_NULLS is passed, both pszDest and pszSrc may be NULL. An error may still be returned even though NULLS are ignored due to insufficient space. 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 - 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 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 RtlStringCchCatNExA( __inout_ecount(cchDest) NTSTRSAFE_PSTR pszDest, __in size_t cchDest, __in_ecount(cchToAppend) STRSAFE_PCNZCH pszSrc, __in size_t cchToAppend, __deref_opt_out_ecount(*pcchRemaining) NTSTRSAFE_PSTR* ppszDestEnd, __out_opt size_t* pcchRemaining, __in DWORD dwFlags) { NTSTATUS status; size_t cchDestLength; status = RtlStringExValidateDestAndLengthA(pszDest, cchDest, &cchDestLength, NTSTRSAFE_MAX_CCH, dwFlags); if (NT_SUCCESS(status)) { NTSTRSAFE_PSTR pszDestEnd = pszDest + cchDestLength; size_t cchRemaining = cchDest - cchDestLength; status = RtlStringExValidateSrcA(&pszSrc, &cchToAppend, NTSTRSAFE_MAX_CCH, dwFlags); if (NT_SUCCESS(status)) { if (dwFlags & (~STRSAFE_VALID_FLAGS)) { status = STATUS_INVALID_PARAMETER; } else if (cchRemaining <= 1) { // only fail if there was actually src data to append if ((cchToAppend != 0) && (*pszSrc != '\0')) { if (pszDest == NULL) { status = STATUS_INVALID_PARAMETER; } else { status = STATUS_BUFFER_OVERFLOW; } } } else { size_t cchCopied = 0; status = RtlStringCopyWorkerA(pszDestEnd, cchRemaining, &cchCopied, pszSrc, cchToAppend); pszDestEnd = pszDestEnd + cchCopied; cchRemaining = cchRemaining - cchCopied; if (NT_SUCCESS(status) && (dwFlags & STRSAFE_FILL_BEHIND_NULL) && (cchRemaining > 1)) { size_t cbRemaining; // safe to multiply cchRemaining * sizeof(char) since cchRemaining < NTSTRSAFE_MAX_CCH and sizeof(char) is 1 cbRemaining = cchRemaining * sizeof(char); // handle the STRSAFE_FILL_BEHIND_NULL flag RtlStringExHandleFillBehindNullA(pszDestEnd, cbRemaining, dwFlags); } } } if (!NT_SUCCESS(status) && (dwFlags & (STRSAFE_NO_TRUNCATION | STRSAFE_FILL_ON_FAILURE | STRSAFE_NULL_ON_FAILURE)) && (cchDest != 0)) { size_t cbDest; // safe to multiply cchDest * sizeof(char) since cchDest < NTSTRSAFE_MAX_CCH and sizeof(char) is 1 cbDest = cchDest * sizeof(char); // handle the STRSAFE_FILL_ON_FAILURE, STRSAFE_NULL_ON_FAILURE, and STRSAFE_NO_TRUNCATION flags RtlStringExHandleOtherFlagsA(pszDest, cbDest, cchDestLength, &pszDestEnd, &cchRemaining, dwFlags); } if (NT_SUCCESS(status) || (status == STATUS_BUFFER_OVERFLOW)) { if (ppszDestEnd) { *ppszDestEnd = pszDestEnd; } if (pcchRemaining) { *pcchRemaining = cchRemaining; } } } return status; } NTSTRSAFEDDI RtlStringCchCatNExW( __inout_ecount(cchDest) NTSTRSAFE_PWSTR pszDest, __in size_t cchDest, __in_ecount(cchToAppend) STRSAFE_PCNZWCH pszSrc, __in size_t cchToAppend, __deref_opt_out_ecount(*pcchRemaining) NTSTRSAFE_PWSTR* ppszDestEnd, __out_opt size_t* pcchRemaining, __in DWORD dwFlags) { NTSTATUS status; size_t cchDestLength; status = RtlStringExValidateDestAndLengthW(pszDest, cchDest, &cchDestLength, NTSTRSAFE_MAX_CCH, dwFlags); if (NT_SUCCESS(status)) { NTSTRSAFE_PWSTR pszDestEnd = pszDest + cchDestLength; size_t cchRemaining = cchDest - cchDestLength; status = RtlStringExValidateSrcW(&pszSrc, &cchToAppend, NTSTRSAFE_MAX_CCH, dwFlags); if (NT_SUCCESS(status)) { if (dwFlags & (~STRSAFE_VALID_FLAGS)) { status = STATUS_INVALID_PARAMETER; } else if (cchRemaining <= 1) { // only fail if there was actually src data to append if ((cchToAppend != 0) && (*pszSrc != L'\0')) { if (pszDest == NULL) { status = STATUS_INVALID_PARAMETER; } else { status = STATUS_BUFFER_OVERFLOW; } } } else { size_t cchCopied = 0; status = RtlStringCopyWorkerW(pszDestEnd, cchRemaining, &cchCopied, pszSrc, cchToAppend); pszDestEnd = pszDestEnd + cchCopied; cchRemaining = cchRemaining - cchCopied; if (NT_SUCCESS(status) && (dwFlags & STRSAFE_FILL_BEHIND_NULL) && (cchRemaining > 1)) { size_t cbRemaining; // safe to multiply cchRemaining * sizeof(wchar_t) since cchRemaining < NTSTRSAFE_MAX_CCH and sizeof(wchar_t) is 2 cbRemaining = cchRemaining * sizeof(wchar_t); // handle the STRSAFE_FILL_BEHIND_NULL flag RtlStringExHandleFillBehindNullW(pszDestEnd, cbRemaining, dwFlags); } } } if (!NT_SUCCESS(status) && (dwFlags & (STRSAFE_NO_TRUNCATION | STRSAFE_FILL_ON_FAILURE | STRSAFE_NULL_ON_FAILURE)) && (cchDest != 0)) { size_t cbDest; // safe to multiply cchDest * sizeof(wchar_t) since cchDest < NTSTRSAFE_MAX_CCH and sizeof(wchar_t) is 2 cbDest = cchDest * sizeof(wchar_t); // handle the STRSAFE_FILL_ON_FAILURE, STRSAFE_NULL_ON_FAILURE, and STRSAFE_NO_TRUNCATION flags RtlStringExHandleOtherFlagsW(pszDest, cbDest, cchDestLength, &pszDestEnd, &cchRemaining, dwFlags); } if (NT_SUCCESS(status) || (status == STATUS_BUFFER_OVERFLOW)) { if (ppszDestEnd) { *ppszDestEnd = pszDestEnd; } if (pcchRemaining) { *pcchRemaining = cchRemaining; } } } return status; } #endif // !NTSTRSAFE_NO_CCH_FUNCTIONS #ifndef NTSTRSAFE_NO_CB_FUNCTIONS /*++ NTSTATUS RtlStringCbCatNEx( __inout_bcount(cbDest) LPTSTR pszDest OPTIONAL, __in size_t cbDest, __in LPCTSTR pszSrc OPTIONAL, __in size_t cbToAppend, __deref_opt_out_bcount(*pcbRemaining) LPTSTR* ppszDestEnd OPTIONAL, __out_opt size_t* pcchRemaining OPTIONAL, __in DWORD dwFlags ); Routine Description: This routine is a safer version of the C built-in function 'strncat', with some additional parameters. In addition to functionality provided by RtlStringCbCatN, this routine also returns a pointer to the end of the destination string and the number of bytes left in the destination string including the null terminator. The flags parameter allows additional controls. Arguments: pszDest - destination string which must be null terminated cbDest - size of destination buffer in bytes. length must be ((_tcslen(pszDest) + min(cbToAppend / sizeof(TCHAR), _tcslen(pszSrc)) + 1) * sizeof(TCHAR) to hold all of the combine string plus the null terminator. pszSrc - source string cbToAppend - maximum number of bytes to append ppszDestEnd - if ppszDestEnd is non-null, the function will return a pointer to the end of the destination string. If the function appended any data, the result will point to the null termination character pcbRemaining - if pcbRemaining is non-null, the function will return the number of bytes left in the destination string, including the null terminator dwFlags - controls some details of the string copy: STRSAFE_FILL_BEHIND_NULL if the function succeeds, the low byte of dwFlags will be used to fill the uninitialize part of destination buffer behind the null terminator STRSAFE_IGNORE_NULLS treat NULL string pointers like empty strings (TEXT("")) STRSAFE_FILL_ON_FAILURE if the function fails, the low byte of dwFlags will be used to fill all of the destination buffer, and it will be null terminated. This will overwrite any pre-existing or truncated string STRSAFE_NULL_ON_FAILURE if the function fails, the destination buffer will be set to the empty string. This will overwrite any pre-existing or truncated string STRSAFE_NO_TRUNCATION if the function returns STATUS_BUFFER_OVERFLOW, pszDest will not contain a truncated string, it will remain unchanged. Notes: Behavior is undefined if source and destination strings overlap. pszDest and pszSrc should not be NULL unless the STRSAFE_IGNORE_NULLS flag is specified. If STRSAFE_IGNORE_NULLS is passed, both pszDest and pszSrc may be NULL. An error may still be returned even though NULLS are ignored due to insufficient space. Return Value: STATUS_SUCCESS - if all of pszSrc or the first cbToAppend bytes were concatenated to pszDest 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 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 RtlStringCbCatNExA( __inout_bcount(cbDest) NTSTRSAFE_PSTR pszDest, __in size_t cbDest, __in_bcount(cbToAppend) STRSAFE_PCNZCH pszSrc, __in size_t cbToAppend, __deref_opt_out_bcount(*pcbRemaining) NTSTRSAFE_PSTR* ppszDestEnd, __out_opt size_t* pcbRemaining, __in DWORD dwFlags) { NTSTATUS status; size_t cchDest = cbDest / sizeof(char); size_t cchDestLength; status = RtlStringExValidateDestAndLengthA(pszDest, cchDest, &cchDestLength, NTSTRSAFE_MAX_CCH, dwFlags); if (NT_SUCCESS(status)) { NTSTRSAFE_PSTR pszDestEnd = pszDest + cchDestLength; size_t cchRemaining = cchDest - cchDestLength; size_t cchToAppend = cbToAppend / sizeof(char); status = RtlStringExValidateSrcA(&pszSrc, &cchToAppend, NTSTRSAFE_MAX_CCH, dwFlags); if (NT_SUCCESS(status)) { if (dwFlags & (~STRSAFE_VALID_FLAGS)) { status = STATUS_INVALID_PARAMETER; } else if (cchRemaining <= 1) { // only fail if there was actually src data to append if ((cchToAppend != 0) && (*pszSrc != '\0')) { if (pszDest == NULL) { status = STATUS_INVALID_PARAMETER; } else { status = STATUS_BUFFER_OVERFLOW; } } } else { size_t cchCopied = 0; status = RtlStringCopyWorkerA(pszDestEnd, cchRemaining, &cchCopied, pszSrc, cchToAppend); pszDestEnd = pszDestEnd + cchCopied; cchRemaining = cchRemaining - cchCopied; if (NT_SUCCESS(status) && (dwFlags & STRSAFE_FILL_BEHIND_NULL) && (cchRemaining > 1)) { size_t cbRemaining; // safe to multiply cchRemaining * sizeof(char) since cchRemaining < NTSTRSAFE_MAX_CCH and sizeof(char) is 1 cbRemaining = (cchRemaining * sizeof(char)) + (cbDest % sizeof(char)); // handle the STRSAFE_FILL_BEHIND_NULL flag RtlStringExHandleFillBehindNullA(pszDestEnd, cbRemaining, dwFlags); } } } if (!NT_SUCCESS(status) && (dwFlags & (STRSAFE_NO_TRUNCATION | STRSAFE_FILL_ON_FAILURE | STRSAFE_NULL_ON_FAILURE)) && (cbDest != 0)) { // handle the STRSAFE_FILL_ON_FAILURE, STRSAFE_NULL_ON_FAILURE, and STRSAFE_NO_TRUNCATION flags RtlStringExHandleOtherFlagsA(pszDest, cbDest, cchDestLength, &pszDestEnd, &cchRemaining, dwFlags); } if (NT_SUCCESS(status) || (status == STATUS_BUFFER_OVERFLOW)) { if (ppszDestEnd) { *ppszDestEnd = pszDestEnd; } if (pcbRemaining) { // safe to multiply cchRemaining * sizeof(char) since cchRemaining < NTSTRSAFE_MAX_CCH and sizeof(char) is 1 *pcbRemaining = (cchRemaining * sizeof(char)) + (cbDest % sizeof(char)); } } } return status; } NTSTRSAFEDDI RtlStringCbCatNExW( __inout_bcount(cbDest) NTSTRSAFE_PWSTR pszDest, __in size_t cbDest, __in_bcount(cbToAppend) STRSAFE_PCNZWCH pszSrc, __in size_t cbToAppend, __deref_opt_out_bcount(*pcbRemaining) NTSTRSAFE_PWSTR* ppszDestEnd, __out_opt size_t* pcbRemaining, __in DWORD dwFlags) { NTSTATUS status; size_t cchDest = cbDest / sizeof(wchar_t); size_t cchDestLength; status = RtlStringExValidateDestAndLengthW(pszDest, cchDest, &cchDestLength, NTSTRSAFE_MAX_CCH, dwFlags); if (NT_SUCCESS(status)) { NTSTRSAFE_PWSTR pszDestEnd = pszDest + cchDestLength; size_t cchRemaining = cchDest - cchDestLength; size_t cchToAppend = cbToAppend / sizeof(wchar_t); #pragma warning(push) #pragma warning(disable : __WARNING_POTENTIAL_BUFFER_OVERFLOW_HIGH_PRIORITY) status = RtlStringExValidateSrcW(&pszSrc, &cchToAppend, NTSTRSAFE_MAX_CCH, dwFlags); #pragma warning(pop) if (NT_SUCCESS(status)) { if (dwFlags & (~STRSAFE_VALID_FLAGS)) { status = STATUS_INVALID_PARAMETER; } else if (cchRemaining <= 1) { // only fail if there was actually src data to append if ((cchToAppend != 0) && (*pszSrc != L'\0')) { if (pszDest == NULL) { status = STATUS_INVALID_PARAMETER; } else { status = STATUS_BUFFER_OVERFLOW; } } } else { size_t cchCopied = 0; status = RtlStringCopyWorkerW(pszDestEnd, cchRemaining, &cchCopied, pszSrc, cchToAppend); pszDestEnd = pszDestEnd + cchCopied; cchRemaining = cchRemaining - cchCopied; if (NT_SUCCESS(status) && (dwFlags & STRSAFE_FILL_BEHIND_NULL)) { size_t cbRemaining; // safe to multiply cchRemaining * sizeof(wchar_t) since cchRemaining < NTSTRSAFE_MAX_CCH and sizeof(wchar_t) is 2 cbRemaining = (cchRemaining * sizeof(wchar_t)) + (cbDest % sizeof(wchar_t)); // handle the STRSAFE_FILL_BEHIND_NULL flag RtlStringExHandleFillBehindNullW(pszDestEnd, cbRemaining, dwFlags); } } } if (!NT_SUCCESS(status) && (dwFlags & (STRSAFE_NO_TRUNCATION | STRSAFE_FILL_ON_FAILURE | STRSAFE_NULL_ON_FAILURE)) && (cbDest != 0)) { // handle the STRSAFE_FILL_ON_FAILURE, STRSAFE_NULL_ON_FAILURE, and STRSAFE_NO_TRUNCATION flags RtlStringExHandleOtherFlagsW(pszDest, cbDest, cchDestLength, &pszDestEnd, &cchRemaining, dwFlags); } if (NT_SUCCESS(status) || (status == STATUS_BUFFER_OVERFLOW)) { if (ppszDestEnd) { *ppszDestEnd = pszDestEnd; } if (pcbRemaining) { // safe to multiply cchRemaining * sizeof(wchar_t) since cchRemaining < NTSTRSAFE_MAX_CCH and sizeof(wchar_t) is 2 *pcbRemaining = (cchRemaining * sizeof(wchar_t)) + (cbDest % sizeof(wchar_t)); } } } return status; } #endif // !NTSTRSAFE_NO_CB_FUNCTIONS #ifndef NTSTRSAFE_NO_CCH_FUNCTIONS /*++ NTSTATUS RtlStringCchVPrintf( __out_ecount(cchDest) LPTSTR pszDest, __in size_t cchDest, __in __format_string LPCTSTR pszFormat, __in va_list argList ); Routine Description: This routine is a safer version of the C built-in function 'vsprintf'. The size of the destination buffer (in characters) 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 function returns an NTSTATUS value, and not a pointer. It returns STATUS_SUCCESS if the string was printed without truncation and null terminated, otherwise it will return a failure code. In failure cases it will return a truncated version of the ideal result. Arguments: pszDest - destination string cchDest - size of destination buffer in characters length must be sufficient to hold the resulting formatted string, including the null terminator. pszFormat - format string which must be null terminated argList - va_list from the variable arguments according to the stdarg.h convention Notes: Behavior is undefined if destination, format strings or any arguments strings overlap. pszDest and pszFormat should not be NULL. See RtlStringCchVPrintfEx if you require the handling of NULL values. Return Value: STATUS_SUCCESS - if there was sufficient space in the dest buffer for the resultant string and it 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 print 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 RtlStringCchVPrintfA( __out_ecount(cchDest) NTSTRSAFE_PSTR pszDest, __in size_t cchDest, __in __format_string NTSTRSAFE_PCSTR pszFormat, __in va_list argList) { NTSTATUS status; status = RtlStringValidateDestA(pszDest, cchDest, NTSTRSAFE_MAX_CCH); if (NT_SUCCESS(status)) { status = RtlStringVPrintfWorkerA(pszDest, cchDest, NULL, pszFormat, argList); } return status; } NTSTRSAFEDDI RtlStringCchVPrintfW( __out_ecount(cchDest) NTSTRSAFE_PWSTR pszDest, __in size_t cchDest, __in __format_string NTSTRSAFE_PCWSTR pszFormat, __in va_list argList) { NTSTATUS status; status = RtlStringValidateDestW(pszDest, cchDest, NTSTRSAFE_MAX_CCH); if (NT_SUCCESS(status)) { status = RtlStringVPrintfWorkerW(pszDest, cchDest, NULL, pszFormat, argList); } return status; } #endif // !NTSTRSAFE_NO_CCH_FUNCTIONS #ifndef NTSTRSAFE_NO_CB_FUNCTIONS /*++ NTSTATUS RtlStringCbVPrintf( __out_bcount(cbDest) LPTSTR pszDest, __in size_t cbDest, __in __format_string LPCTSTR pszFormat, __in va_list argList ); Routine Description: This routine is a safer version of the C built-in function 'vsprintf'. 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 function returns an NTSTATUS value, and not a pointer. It returns STATUS_SUCCESS if the string was printed without truncation and null terminated, otherwise it will return a failure code. In failure cases it will return a truncated version of the ideal result. Arguments: pszDest - destination string cbDest - size of destination buffer in bytes length must be sufficient to hold the resulting formatted string, including the null terminator. pszFormat - format string which must be null terminated argList - va_list from the variable arguments according to the stdarg.h convention Notes: Behavior is undefined if destination, format strings or any arguments strings overlap. pszDest and pszFormat should not be NULL. See RtlStringCbVPrintfEx if you require the handling of NULL values. Return Value: STATUS_SUCCESS - if there was sufficient space in the dest buffer for the resultant string and it 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 print 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 RtlStringCbVPrintfA( __out_bcount(cbDest) NTSTRSAFE_PSTR pszDest, __in size_t cbDest, __in __format_string NTSTRSAFE_PCSTR pszFormat, __in va_list argList) { NTSTATUS status; size_t cchDest = cbDest / sizeof(char); status = RtlStringValidateDestA(pszDest, cchDest, NTSTRSAFE_MAX_CCH); if (NT_SUCCESS(status)) { status = RtlStringVPrintfWorkerA(pszDest, cchDest, NULL, pszFormat, argList); } return status; } NTSTRSAFEDDI RtlStringCbVPrintfW( __out_bcount(cbDest) NTSTRSAFE_PWSTR pszDest, __in size_t cbDest, __in __format_string NTSTRSAFE_PCWSTR pszFormat, __in va_list argList) { NTSTATUS status; size_t cchDest = cbDest / sizeof(wchar_t); status = RtlStringValidateDestW(pszDest, cchDest, NTSTRSAFE_MAX_CCH); if (NT_SUCCESS(status)) { status = RtlStringVPrintfWorkerW(pszDest, cchDest, NULL, pszFormat, argList); } return status; } #endif // !NTSTRSAFE_NO_CB_FUNCTIONS #ifndef _M_CEE_PURE #ifndef NTSTRSAFE_NO_CCH_FUNCTIONS /*++ NTSTATUS RtlStringCchPrintf( __out_ecount(cchDest) LPTSTR pszDest, __in size_t cchDest, __in __format_string LPCTSTR pszFormat, ... ); Routine Description: This routine is a safer version of the C built-in function 'sprintf'. The size of the destination buffer (in characters) 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 function returns an NTSTATUS value, and not a pointer. It returns STATUS_SUCCESS if the string was printed without truncation and null terminated, otherwise it will return a failure code. In failure cases it will return a truncated version of the ideal result. Arguments: pszDest - destination string cchDest - size of destination buffer in characters length must be sufficient to hold the resulting formatted string, including the null terminator. pszFormat - format string which must be null terminated ... - additional parameters to be formatted according to the format string Notes: Behavior is undefined if destination, format strings or any arguments strings overlap. pszDest and pszFormat should not be NULL. See RtlStringCchPrintfEx if you require the handling of NULL values. Return Value: STATUS_SUCCESS - if there was sufficient space in the dest buffer for the resultant string and it 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 print 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 RtlStringCchPrintfA( __out_ecount(cchDest) NTSTRSAFE_PSTR pszDest, __in size_t cchDest, __in __format_string NTSTRSAFE_PCSTR pszFormat, ...) { NTSTATUS status; status = RtlStringValidateDestA(pszDest, cchDest, NTSTRSAFE_MAX_CCH); if (NT_SUCCESS(status)) { va_list argList; va_start(argList, pszFormat); status = RtlStringVPrintfWorkerA(pszDest, cchDest, NULL, pszFormat, argList); va_end(argList); } return status; } NTSTRSAFEDDI RtlStringCchPrintfW( __out_ecount(cchDest) NTSTRSAFE_PWSTR pszDest, __in size_t cchDest, __in __format_string NTSTRSAFE_PCWSTR pszFormat, ...) { NTSTATUS status; status = RtlStringValidateDestW(pszDest, cchDest, NTSTRSAFE_MAX_CCH); if (NT_SUCCESS(status)) { va_list argList; va_start(argList, pszFormat); status = RtlStringVPrintfWorkerW(pszDest, cchDest, NULL, pszFormat, argList); va_end(argList); } return status; } #endif // !NTSTRSAFE_NO_CCH_FUNCTIONS #ifndef NTSTRSAFE_NO_CB_FUNCTIONS /*++ NTSTATUS RtlStringCbPrintf( __out_bcount(cbDest) LPTSTR pszDest, __in size_t cbDest, __in __format_string LPCTSTR pszFormat, ... ); Routine Description: This routine is a safer version of the C built-in function 'sprintf'. 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 function returns an NTSTATUS value, and not a pointer. It returns STATUS_SUCCESS if the string was printed without truncation and null terminated, otherwise it will return a failure code. In failure cases it will return a truncated version of the ideal result. Arguments: pszDest - destination string cbDest - size of destination buffer in bytes length must be sufficient to hold the resulting formatted string, including the null terminator. pszFormat - format string which must be null terminated ... - additional parameters to be formatted according to the format string Notes: Behavior is undefined if destination, format strings or any arguments strings overlap. pszDest and pszFormat should not be NULL. See RtlStringCbPrintfEx if you require the handling of NULL values. Return Value: STATUS_SUCCESS - if there was sufficient space in the dest buffer for the resultant string and it 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 print 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 RtlStringCbPrintfA( __out_bcount(cbDest) NTSTRSAFE_PSTR pszDest, __in size_t cbDest, __in __format_string NTSTRSAFE_PCSTR pszFormat, ...) { NTSTATUS status; size_t cchDest = cbDest / sizeof(char); status = RtlStringValidateDestA(pszDest, cchDest, NTSTRSAFE_MAX_CCH); if (NT_SUCCESS(status)) { va_list argList; va_start(argList, pszFormat); status = RtlStringVPrintfWorkerA(pszDest, cchDest, NULL, pszFormat, argList); va_end(argList); } return status; } NTSTRSAFEDDI RtlStringCbPrintfW( __out_bcount(cbDest) NTSTRSAFE_PWSTR pszDest, __in size_t cbDest, __in __format_string NTSTRSAFE_PCWSTR pszFormat, ...) { NTSTATUS status; size_t cchDest = cbDest / sizeof(wchar_t); status = RtlStringValidateDestW(pszDest, cchDest, NTSTRSAFE_MAX_CCH); if (NT_SUCCESS(status)) { va_list argList; va_start(argList, pszFormat); status = RtlStringVPrintfWorkerW(pszDest, cchDest, NULL, pszFormat, argList); va_end(argList); } return status; } #endif // !NTSTRSAFE_NO_CB_FUNCTIONS #ifndef NTSTRSAFE_NO_CCH_FUNCTIONS /*++ NTSTATUS RtlStringCchPrintfEx( __out_ecount(cchDest) LPTSTR pszDest OPTIONAL, __in size_t cchDest, __deref_opt_out_ecount(*pcchRemaining) LPTSTR* ppszDestEnd OPTIONAL, __out_opt size_t* pcchRemaining OPTIONAL, __in DWORD dwFlags, __in __format_string LPCTSTR pszFormat OPTIONAL, ... ); Routine Description: This routine is a safer version of the C built-in function 'sprintf' with some additional parameters. In addition to functionality provided by RtlStringCchPrintf, this routine also returns a pointer to the end of the destination string and the number of characters left in the destination string including the null terminator. The flags parameter allows additional controls. Arguments: pszDest - destination string cchDest - size of destination buffer in characters. length must be sufficient to contain the resulting formatted string plus the null terminator. ppszDestEnd - if ppszDestEnd is non-null, the function will return a pointer to the end of the destination string. If the function printed any data, the result will point to the null termination character pcchRemaining - if pcchRemaining is non-null, the function will return the number of characters left in the destination string, including the null terminator dwFlags - controls some details of the string copy: STRSAFE_FILL_BEHIND_NULL if the function succeeds, the low byte of dwFlags will be used to fill the uninitialize part of destination buffer behind the null terminator STRSAFE_IGNORE_NULLS treat NULL string pointers like empty strings (TEXT("")) STRSAFE_FILL_ON_FAILURE if the function fails, the low byte of dwFlags will be used to fill all of the destination buffer, and it will be null terminated. This will overwrite any truncated string returned when the failure is STATUS_BUFFER_OVERFLOW STRSAFE_NO_TRUNCATION / STRSAFE_NULL_ON_FAILURE if the function fails, the destination buffer will be set to the empty string. This will overwrite any truncated string returned when the failure is STATUS_BUFFER_OVERFLOW. pszFormat - format string which must be null terminated ... - additional parameters to be formatted according to the format string Notes: Behavior is undefined if destination, format strings or any arguments strings overlap. pszDest and pszFormat should not be NULL unless the STRSAFE_IGNORE_NULLS flag is specified. If STRSAFE_IGNORE_NULLS is passed, both pszDest and pszFormat may be NULL. An error may still be returned even though NULLS are ignored due to insufficient space. Return Value: STATUS_SUCCESS - if there was sufficient space in the dest buffer for the resultant string and it 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 print 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 RtlStringCchPrintfExA( __out_ecount(cchDest) NTSTRSAFE_PSTR pszDest, __in size_t cchDest, __deref_opt_out_ecount(*pcchRemaining) NTSTRSAFE_PSTR* ppszDestEnd, __out_opt size_t* pcchRemaining, __in DWORD dwFlags, __in __format_string NTSTRSAFE_PCSTR pszFormat, ...) { NTSTATUS status; status = RtlStringExValidateDestA(pszDest, cchDest, NTSTRSAFE_MAX_CCH, dwFlags); if (NT_SUCCESS(status)) { NTSTRSAFE_PSTR pszDestEnd = pszDest; size_t cchRemaining = cchDest; status = RtlStringExValidateSrcA(&pszFormat, NULL, NTSTRSAFE_MAX_CCH, dwFlags); if (NT_SUCCESS(status)) { if (dwFlags & (~STRSAFE_VALID_FLAGS)) { status = STATUS_INVALID_PARAMETER; if (cchDest != 0) { *pszDest = '\0'; } } else if (cchDest == 0) { // only fail if there was actually a non-empty format string if (*pszFormat != '\0') { if (pszDest == NULL) { status = STATUS_INVALID_PARAMETER; } else { status = STATUS_BUFFER_OVERFLOW; } } } else { size_t cchNewDestLength = 0; va_list argList; va_start(argList, pszFormat); status = RtlStringVPrintfWorkerA(pszDest, cchDest, &cchNewDestLength, pszFormat, argList); va_end(argList); pszDestEnd = pszDest + cchNewDestLength; cchRemaining = cchDest - cchNewDestLength; if (NT_SUCCESS(status) && (dwFlags & STRSAFE_FILL_BEHIND_NULL) && (cchRemaining > 1)) { size_t cbRemaining; // safe to multiply cchRemaining * sizeof(char) since cchRemaining < NTSTRSAFE_MAX_CCH and sizeof(char) is 1 cbRemaining = cchRemaining * sizeof(char); // handle the STRSAFE_FILL_BEHIND_NULL flag RtlStringExHandleFillBehindNullA(pszDestEnd, cbRemaining, dwFlags); } } } else { if (cchDest != 0) { *pszDest = '\0'; } } if (!NT_SUCCESS(status) && (dwFlags & (STRSAFE_NO_TRUNCATION | STRSAFE_FILL_ON_FAILURE | STRSAFE_NULL_ON_FAILURE)) && (cchDest != 0)) { size_t cbDest; // safe to multiply cchDest * sizeof(char) since cchDest < NTSTRSAFE_MAX_CCH and sizeof(char) is 1 cbDest = cchDest * sizeof(char); // handle the STRSAFE_FILL_ON_FAILURE, STRSAFE_NULL_ON_FAILURE, and STRSAFE_NO_TRUNCATION flags RtlStringExHandleOtherFlagsA(pszDest, cbDest, 0, &pszDestEnd, &cchRemaining, dwFlags); } if (NT_SUCCESS(status) || (status == STATUS_BUFFER_OVERFLOW)) { if (ppszDestEnd) { *ppszDestEnd = pszDestEnd; } if (pcchRemaining) { *pcchRemaining = cchRemaining; } } } return status; } NTSTRSAFEDDI RtlStringCchPrintfExW( __out_ecount(cchDest) NTSTRSAFE_PWSTR pszDest, __in size_t cchDest, __deref_opt_out_ecount(*pcchRemaining) NTSTRSAFE_PWSTR* ppszDestEnd, __out_opt size_t* pcchRemaining, __in DWORD dwFlags, __in __format_string NTSTRSAFE_PCWSTR pszFormat, ...) { NTSTATUS status; status = RtlStringExValidateDestW(pszDest, cchDest, NTSTRSAFE_MAX_CCH, dwFlags); if (NT_SUCCESS(status)) { NTSTRSAFE_PWSTR pszDestEnd = pszDest; size_t cchRemaining = cchDest; status = RtlStringExValidateSrcW(&pszFormat, NULL, NTSTRSAFE_MAX_CCH, dwFlags); if (NT_SUCCESS(status)) { if (dwFlags & (~STRSAFE_VALID_FLAGS)) { status = STATUS_INVALID_PARAMETER; if (cchDest != 0) { *pszDest = L'\0'; } } else if (cchDest == 0) { // only fail if there was actually a non-empty format string if (*pszFormat != L'\0') { if (pszDest == NULL) { status = STATUS_INVALID_PARAMETER; } else { status = STATUS_BUFFER_OVERFLOW; } } } else { size_t cchNewDestLength = 0; va_list argList; va_start(argList, pszFormat); status = RtlStringVPrintfWorkerW(pszDest, cchDest, &cchNewDestLength, pszFormat, argList); va_end(argList); pszDestEnd = pszDest + cchNewDestLength; cchRemaining = cchDest - cchNewDestLength; if (NT_SUCCESS(status) && (dwFlags & STRSAFE_FILL_BEHIND_NULL) && (cchRemaining > 1)) { size_t cbRemaining; // safe to multiply cchRemaining * sizeof(wchar_t) since cchRemaining < NTSTRSAFE_MAX_CCH and sizeof(wchar_t) is 2 cbRemaining = cchRemaining * sizeof(wchar_t); // handle the STRSAFE_FILL_BEHIND_NULL flag RtlStringExHandleFillBehindNullW(pszDestEnd, cbRemaining, dwFlags); } } } else { if (cchDest != 0) { *pszDest = L'\0'; } } if (!NT_SUCCESS(status) && (dwFlags & (STRSAFE_NO_TRUNCATION | STRSAFE_FILL_ON_FAILURE | STRSAFE_NULL_ON_FAILURE)) && (cchDest != 0)) { size_t cbDest; // safe to multiply cchDest * sizeof(wchar_t) since cchDest < NTSTRSAFE_MAX_CCH and sizeof(wchar_t) is 2 cbDest = cchDest * sizeof(wchar_t); // handle the STRSAFE_FILL_ON_FAILURE, STRSAFE_NULL_ON_FAILURE, and STRSAFE_NO_TRUNCATION flags RtlStringExHandleOtherFlagsW(pszDest, cbDest, 0, &pszDestEnd, &cchRemaining, dwFlags); } if (NT_SUCCESS(status) || (status == STATUS_BUFFER_OVERFLOW)) { if (ppszDestEnd) { *ppszDestEnd = pszDestEnd; } if (pcchRemaining) { *pcchRemaining = cchRemaining; } } } return status; } #endif // !NTSTRSAFE_NO_CCH_FUNCTIONS #ifndef NTSTRSAFE_NO_CB_FUNCTIONS /*++ NTSTATUS RtlStringCbPrintfEx( __out_bcount(cbDest) LPTSTR pszDest OPTIONAL, __in size_t cbDest, __deref_opt_out_bcount(*pcbRemaining) LPTSTR* ppszDestEnd OPTIONAL, __out_opt size_t* pcbRemaining OPTIONAL, __in DWORD dwFlags, __in __format_string LPCTSTR pszFormat OPTIONAL, ... ); Routine Description: This routine is a safer version of the C built-in function 'sprintf' with some additional parameters. In addition to functionality provided by RtlStringCbPrintf, this routine also returns a pointer to the end of the destination string and the number of bytes left in the destination string including the null terminator. The flags parameter allows additional controls. Arguments: pszDest - destination string cbDest - size of destination buffer in bytes. length must be sufficient to contain the resulting formatted string plus the null terminator. ppszDestEnd - if ppszDestEnd is non-null, the function will return a pointer to the end of the destination string. If the function printed any data, the result will point to the null termination character pcbRemaining - if pcbRemaining is non-null, the function will return the number of bytes left in the destination string, including the null terminator dwFlags - controls some details of the string copy: STRSAFE_FILL_BEHIND_NULL if the function succeeds, the low byte of dwFlags will be used to fill the uninitialize part of destination buffer behind the null terminator STRSAFE_IGNORE_NULLS treat NULL string pointers like empty strings (TEXT("")) STRSAFE_FILL_ON_FAILURE if the function fails, the low byte of dwFlags will be used to fill all of the destination buffer, and it will be null terminated. This will overwrite any truncated string returned when the failure is STATUS_BUFFER_OVERFLOW STRSAFE_NO_TRUNCATION / STRSAFE_NULL_ON_FAILURE if the function fails, the destination buffer will be set to the empty string. This will overwrite any truncated string returned when the failure is STATUS_BUFFER_OVERFLOW. pszFormat - format string which must be null terminated ... - additional parameters to be formatted according to the format string Notes: Behavior is undefined if destination, format strings or any arguments strings overlap. pszDest and pszFormat should not be NULL unless the STRSAFE_IGNORE_NULLS flag is specified. If STRSAFE_IGNORE_NULLS is passed, both pszDest and pszFormat may be NULL. An error may still be returned even though NULLS are ignored due to insufficient space. Return Value: STATUS_SUCCESS - if there was source data and it was all concatenated 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 print 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 RtlStringCbPrintfExA( __out_bcount(cbDest) NTSTRSAFE_PSTR pszDest, __in size_t cbDest, __deref_opt_out_bcount(*pcbRemaining) NTSTRSAFE_PSTR* ppszDestEnd, __out_opt size_t* pcbRemaining, __in DWORD dwFlags, __in __format_string NTSTRSAFE_PCSTR pszFormat, ...) { NTSTATUS status; size_t cchDest = cbDest / sizeof(char); status = RtlStringExValidateDestA(pszDest, cchDest, NTSTRSAFE_MAX_CCH, dwFlags); if (NT_SUCCESS(status)) { NTSTRSAFE_PSTR pszDestEnd = pszDest; size_t cchRemaining = cchDest; status = RtlStringExValidateSrcA(&pszFormat, NULL, NTSTRSAFE_MAX_CCH, dwFlags); if (NT_SUCCESS(status)) { if (dwFlags & (~STRSAFE_VALID_FLAGS)) { status = STATUS_INVALID_PARAMETER; if (cchDest != 0) { *pszDest = '\0'; } } else if (cchDest == 0) { // only fail if there was actually a non-empty format string if (*pszFormat != '\0') { if (pszDest == NULL) { status = STATUS_INVALID_PARAMETER; } else { status = STATUS_BUFFER_OVERFLOW; } } } else { size_t cchNewDestLength = 0; va_list argList; va_start(argList, pszFormat); status = RtlStringVPrintfWorkerA(pszDest, cchDest, &cchNewDestLength, pszFormat, argList); va_end(argList); pszDestEnd = pszDest + cchNewDestLength; cchRemaining = cchDest - cchNewDestLength; if (NT_SUCCESS(status) && (dwFlags & STRSAFE_FILL_BEHIND_NULL) && (cchRemaining > 1)) { size_t cbRemaining; // safe to multiply cchRemaining * sizeof(char) since cchRemaining < NTSTRSAFE_MAX_CCH and sizeof(char) is 1 cbRemaining = (cchRemaining * sizeof(char)) + (cbDest % sizeof(char)); // handle the STRSAFE_FILL_BEHIND_NULL flag RtlStringExHandleFillBehindNullA(pszDestEnd, cbRemaining, dwFlags); } } } else { if (cchDest != 0) { *pszDest = '\0'; } } if (!NT_SUCCESS(status) && (dwFlags & (STRSAFE_NO_TRUNCATION | STRSAFE_FILL_ON_FAILURE | STRSAFE_NULL_ON_FAILURE)) && (cbDest != 0)) { // handle the STRSAFE_FILL_ON_FAILURE, STRSAFE_NULL_ON_FAILURE, and STRSAFE_NO_TRUNCATION flags RtlStringExHandleOtherFlagsA(pszDest, cbDest, 0, &pszDestEnd, &cchRemaining, dwFlags); } if (NT_SUCCESS(status) || (status == STATUS_BUFFER_OVERFLOW)) { if (ppszDestEnd) { *ppszDestEnd = pszDestEnd; } if (pcbRemaining) { // safe to multiply cchRemaining * sizeof(char) since cchRemaining < NTSTRSAFE_MAX_CCH and sizeof(char) is 1 *pcbRemaining = (cchRemaining * sizeof(char)) + (cbDest % sizeof(char)); } } } return status; } NTSTRSAFEDDI RtlStringCbPrintfExW( __out_bcount(cbDest) NTSTRSAFE_PWSTR pszDest, __in size_t cbDest, __deref_opt_out_bcount(*pcbRemaining) NTSTRSAFE_PWSTR* ppszDestEnd, __out_opt size_t* pcbRemaining, __in DWORD dwFlags, __in __format_string NTSTRSAFE_PCWSTR pszFormat, ...) { NTSTATUS status; size_t cchDest = cbDest / sizeof(wchar_t); status = RtlStringExValidateDestW(pszDest, cchDest, NTSTRSAFE_MAX_CCH, dwFlags); if (NT_SUCCESS(status)) { NTSTRSAFE_PWSTR pszDestEnd = pszDest; size_t cchRemaining = cchDest; status = RtlStringExValidateSrcW(&pszFormat, NULL, NTSTRSAFE_MAX_CCH, dwFlags); if (NT_SUCCESS(status)) { if (dwFlags & (~STRSAFE_VALID_FLAGS)) { status = STATUS_INVALID_PARAMETER; if (cchDest != 0) { *pszDest = L'\0'; } } else if (cchDest == 0) { // only fail if there was actually a non-empty format string if (*pszFormat != L'\0') { if (pszDest == NULL) { status = STATUS_INVALID_PARAMETER; } else { status = STATUS_BUFFER_OVERFLOW; } } } else { size_t cchNewDestLength = 0; va_list argList; va_start(argList, pszFormat); status = RtlStringVPrintfWorkerW(pszDest, cchDest, &cchNewDestLength, pszFormat, argList); va_end(argList); pszDestEnd = pszDest + cchNewDestLength; cchRemaining = cchDest - cchNewDestLength; if (NT_SUCCESS(status) && (dwFlags & STRSAFE_FILL_BEHIND_NULL)) { size_t cbRemaining; // safe to multiply cchRemaining * sizeof(wchar_t) since cchRemaining < NTSTRSAFE_MAX_CCH and sizeof(wchar_t) is 2 cbRemaining = (cchRemaining * sizeof(wchar_t)) + (cbDest % sizeof(wchar_t)); // handle the STRSAFE_FILL_BEHIND_NULL flag RtlStringExHandleFillBehindNullW(pszDestEnd, cbRemaining, dwFlags); } } } else { if (cchDest != 0) { *pszDest = L'\0'; } } if (!NT_SUCCESS(status) && (dwFlags & (STRSAFE_NO_TRUNCATION | STRSAFE_FILL_ON_FAILURE | STRSAFE_NULL_ON_FAILURE)) && (cbDest != 0)) { // handle the STRSAFE_FILL_ON_FAILURE, STRSAFE_NULL_ON_FAILURE, and STRSAFE_NO_TRUNCATION flags RtlStringExHandleOtherFlagsW(pszDest, cbDest, 0, &pszDestEnd, &cchRemaining, dwFlags); } if (NT_SUCCESS(status) || (status == STATUS_BUFFER_OVERFLOW)) { if (ppszDestEnd) { *ppszDestEnd = pszDestEnd; } if (pcbRemaining) { // safe to multiply cchRemaining * sizeof(wchar_t) since cchRemaining < NTSTRSAFE_MAX_CCH and sizeof(wchar_t) is 2 *pcbRemaining = (cchRemaining * sizeof(wchar_t)) + (cbDest % sizeof(wchar_t)); } } } return status; } #endif // !NTSTRSAFE_NO_CB_FUNCTIONS #endif // !_M_CEE_PURE #ifndef NTSTRSAFE_NO_CCH_FUNCTIONS /*++ NTSTATUS RtlStringCchVPrintfEx( __out_ecount(cchDest) LPTSTR pszDest OPTIONAL, __in size_t cchDest, __deref_opt_out_ecount(*pcchRemaining) LPTSTR* ppszDestEnd OPTIONAL, __out_opt size_t* pcchRemaining OPTIONAL, __in DWORD dwFlags, __in __format_string LPCTSTR pszFormat OPTIONAL, __in va_list argList ); Routine Description: This routine is a safer version of the C built-in function 'vsprintf' with some additional parameters. In addition to functionality provided by RtlStringCchVPrintf, this routine also returns a pointer to the end of the destination string and the number of characters left in the destination string including the null terminator. The flags parameter allows additional controls. Arguments: pszDest - destination string cchDest - size of destination buffer in characters. length must be sufficient to contain the resulting formatted string plus the null terminator. ppszDestEnd - if ppszDestEnd is non-null, the function will return a pointer to the end of the destination string. If the function printed any data, the result will point to the null termination character pcchRemaining - if pcchRemaining is non-null, the function will return the number of characters left in the destination string, including the null terminator dwFlags - controls some details of the string copy: STRSAFE_FILL_BEHIND_NULL if the function succeeds, the low byte of dwFlags will be used to fill the uninitialize part of destination buffer behind the null terminator STRSAFE_IGNORE_NULLS treat NULL string pointers like empty strings (TEXT("")) STRSAFE_FILL_ON_FAILURE if the function fails, the low byte of dwFlags will be used to fill all of the destination buffer, and it will be null terminated. This will overwrite any truncated string returned when the failure is STATUS_BUFFER_OVERFLOW STRSAFE_NO_TRUNCATION / STRSAFE_NULL_ON_FAILURE if the function fails, the destination buffer will be set to the empty string. This will overwrite any truncated string returned when the failure is STATUS_BUFFER_OVERFLOW. pszFormat - format string which must be null terminated argList - va_list from the variable arguments according to the stdarg.h convention Notes: Behavior is undefined if destination, format strings or any arguments strings overlap. pszDest and pszFormat should not be NULL unless the STRSAFE_IGNORE_NULLS flag is specified. If STRSAFE_IGNORE_NULLS is passed, both pszDest and pszFormat may be NULL. An error may still be returned even though NULLS are ignored due to insufficient space. Return Value: STATUS_SUCCESS - if there was source data and it was all concatenated 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 print 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 RtlStringCchVPrintfExA( __out_ecount(cchDest) NTSTRSAFE_PSTR pszDest, __in size_t cchDest, __deref_opt_out_ecount(*pcchRemaining) NTSTRSAFE_PSTR* ppszDestEnd, __out_opt size_t* pcchRemaining, __in DWORD dwFlags, __in __format_string NTSTRSAFE_PCSTR pszFormat, __in va_list argList) { NTSTATUS status; status = RtlStringExValidateDestA(pszDest, cchDest, NTSTRSAFE_MAX_CCH, dwFlags); if (NT_SUCCESS(status)) { NTSTRSAFE_PSTR pszDestEnd = pszDest; size_t cchRemaining = cchDest; status = RtlStringExValidateSrcA(&pszFormat, NULL, NTSTRSAFE_MAX_CCH, dwFlags); if (NT_SUCCESS(status)) { if (dwFlags & (~STRSAFE_VALID_FLAGS)) { status = STATUS_INVALID_PARAMETER; if (cchDest != 0) { *pszDest = '\0'; } } else if (cchDest == 0) { // only fail if there was actually a non-empty format string if (*pszFormat != '\0') { if (pszDest == NULL) { status = STATUS_INVALID_PARAMETER; } else { status = STATUS_BUFFER_OVERFLOW; } } } else { size_t cchNewDestLength = 0; status = RtlStringVPrintfWorkerA(pszDest, cchDest, &cchNewDestLength, pszFormat, argList); pszDestEnd = pszDest + cchNewDestLength; cchRemaining = cchDest - cchNewDestLength; if (NT_SUCCESS(status) && (dwFlags & STRSAFE_FILL_BEHIND_NULL) && (cchRemaining > 1)) { size_t cbRemaining; // safe to multiply cchRemaining * sizeof(char) since cchRemaining < NTSTRSAFE_MAX_CCH and sizeof(char) is 1 cbRemaining = cchRemaining * sizeof(char); // handle the STRSAFE_FILL_BEHIND_NULL flag RtlStringExHandleFillBehindNullA(pszDestEnd, cbRemaining, dwFlags); } } } else { if (cchDest != 0) { *pszDest = '\0'; } } if (!NT_SUCCESS(status) && (dwFlags & (STRSAFE_NO_TRUNCATION | STRSAFE_FILL_ON_FAILURE | STRSAFE_NULL_ON_FAILURE)) && (cchDest != 0)) { size_t cbDest; // safe to multiply cchDest * sizeof(char) since cchDest < NTSTRSAFE_MAX_CCH and sizeof(char) is 1 cbDest = cchDest * sizeof(char); // handle the STRSAFE_FILL_ON_FAILURE, STRSAFE_NULL_ON_FAILURE, and STRSAFE_NO_TRUNCATION flags RtlStringExHandleOtherFlagsA(pszDest, cbDest, 0, &pszDestEnd, &cchRemaining, dwFlags); } if (NT_SUCCESS(status) || (status == STATUS_BUFFER_OVERFLOW)) { if (ppszDestEnd) { *ppszDestEnd = pszDestEnd; } if (pcchRemaining) { *pcchRemaining = cchRemaining; } } } return status; } NTSTRSAFEDDI RtlStringCchVPrintfExW( __out_ecount(cchDest) NTSTRSAFE_PWSTR pszDest, __in size_t cchDest, __deref_opt_out_ecount(*pcchRemaining) NTSTRSAFE_PWSTR* ppszDestEnd, __out_opt size_t* pcchRemaining, __in DWORD dwFlags, __in __format_string NTSTRSAFE_PCWSTR pszFormat, __in va_list argList) { NTSTATUS status; status = RtlStringExValidateDestW(pszDest, cchDest, NTSTRSAFE_MAX_CCH, dwFlags); if (NT_SUCCESS(status)) { NTSTRSAFE_PWSTR pszDestEnd = pszDest; size_t cchRemaining = cchDest; status = RtlStringExValidateSrcW(&pszFormat, NULL, NTSTRSAFE_MAX_CCH, dwFlags); if (NT_SUCCESS(status)) { if (dwFlags & (~STRSAFE_VALID_FLAGS)) { status = STATUS_INVALID_PARAMETER; if (cchDest != 0) { *pszDest = L'\0'; } } else if (cchDest == 0) { // only fail if there was actually a non-empty format string if (*pszFormat != L'\0') { if (pszDest == NULL) { status = STATUS_INVALID_PARAMETER; } else { status = STATUS_BUFFER_OVERFLOW; } } } else { size_t cchNewDestLength = 0; status = RtlStringVPrintfWorkerW(pszDest, cchDest, &cchNewDestLength, pszFormat, argList); pszDestEnd = pszDest + cchNewDestLength; cchRemaining = cchDest - cchNewDestLength; if (NT_SUCCESS(status) && (dwFlags & STRSAFE_FILL_BEHIND_NULL) && (cchRemaining > 1)) { size_t cbRemaining; // safe to multiply cchRemaining * sizeof(wchar_t) since cchRemaining < NTSTRSAFE_MAX_CCH and sizeof(wchar_t) is 2 cbRemaining = cchRemaining * sizeof(wchar_t); // handle the STRSAFE_FILL_BEHIND_NULL flag RtlStringExHandleFillBehindNullW(pszDestEnd, cbRemaining, dwFlags); } } } else { if (cchDest != 0) { *pszDest = L'\0'; } } if (!NT_SUCCESS(status) && (dwFlags & (STRSAFE_NO_TRUNCATION | STRSAFE_FILL_ON_FAILURE | STRSAFE_NULL_ON_FAILURE)) && (cchDest != 0)) { size_t cbDest; // safe to multiply cchDest * sizeof(wchar_t) since cchDest < NTSTRSAFE_MAX_CCH and sizeof(wchar_t) is 2 cbDest = cchDest * sizeof(wchar_t); // handle the STRSAFE_FILL_ON_FAILURE, STRSAFE_NULL_ON_FAILURE, and STRSAFE_NO_TRUNCATION flags RtlStringExHandleOtherFlagsW(pszDest, cbDest, 0, &pszDestEnd, &cchRemaining, dwFlags); } if (NT_SUCCESS(status) || (status == STATUS_BUFFER_OVERFLOW)) { if (ppszDestEnd) { *ppszDestEnd = pszDestEnd; } if (pcchRemaining) { *pcchRemaining = cchRemaining; } } } return status; } #endif // !NTSTRSAFE_NO_CCH_FUNCTIONS #ifndef NTSTRSAFE_NO_CB_FUNCTIONS /*++ NTSTATUS RtlStringCbVPrintfEx( __out_bcount(cbDest) LPTSTR pszDest OPTIONAL, __in size_t cbDest, __deref_opt_out_bcount(*pcbRemaining) LPTSTR* ppszDestEnd OPTIONAL, __out_opt size_t* pcbRemaining OPTIONAL, __in DWORD dwFlags, __in __format_string LPCTSTR pszFormat OPTIONAL, __in va_list argList ); Routine Description: This routine is a safer version of the C built-in function 'vsprintf' with some additional parameters. In addition to functionality provided by RtlStringCbVPrintf, this routine also returns a pointer to the end of the destination string and the number of characters left in the destination string including the null terminator. The flags parameter allows additional controls. Arguments: pszDest - destination string cbDest - size of destination buffer in bytes. length must be sufficient to contain the resulting formatted string plus the null terminator. ppszDestEnd - if ppszDestEnd is non-null, the function will return a pointer to the end of the destination string. If the function printed any data, the result will point to the null termination character pcbRemaining - if pcbRemaining is non-null, the function will return the number of bytes left in the destination string, including the null terminator dwFlags - controls some details of the string copy: STRSAFE_FILL_BEHIND_NULL if the function succeeds, the low byte of dwFlags will be used to fill the uninitialize part of destination buffer behind the null terminator STRSAFE_IGNORE_NULLS treat NULL string pointers like empty strings (TEXT("")) STRSAFE_FILL_ON_FAILURE if the function fails, the low byte of dwFlags will be used to fill all of the destination buffer, and it will be null terminated. This will overwrite any truncated string returned when the failure is STATUS_BUFFER_OVERFLOW STRSAFE_NO_TRUNCATION / STRSAFE_NULL_ON_FAILURE if the function fails, the destination buffer will be set to the empty string. This will overwrite any truncated string returned when the failure is STATUS_BUFFER_OVERFLOW. pszFormat - format string which must be null terminated argList - va_list from the variable arguments according to the stdarg.h convention Notes: Behavior is undefined if destination, format strings or any arguments strings overlap. pszDest and pszFormat should not be NULL unless the STRSAFE_IGNORE_NULLS flag is specified. If STRSAFE_IGNORE_NULLS is passed, both pszDest and pszFormat may be NULL. An error may still be returned even though NULLS are ignored due to insufficient space. Return Value: STATUS_SUCCESS - if there was source data and it was all concatenated 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 print 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 RtlStringCbVPrintfExA( __out_bcount(cbDest) NTSTRSAFE_PSTR pszDest, __in size_t cbDest, __deref_opt_out_bcount(*pcbRemaining) NTSTRSAFE_PSTR* ppszDestEnd, __out_opt size_t* pcbRemaining, __in DWORD dwFlags, __in __format_string NTSTRSAFE_PCSTR pszFormat, __in va_list argList) { NTSTATUS status; size_t cchDest = cbDest / sizeof(char); status = RtlStringExValidateDestA(pszDest, cchDest, NTSTRSAFE_MAX_CCH, dwFlags); if (NT_SUCCESS(status)) { NTSTRSAFE_PSTR pszDestEnd = pszDest; size_t cchRemaining = cchDest; status = RtlStringExValidateSrcA(&pszFormat, NULL, NTSTRSAFE_MAX_CCH, dwFlags); if (NT_SUCCESS(status)) { if (dwFlags & (~STRSAFE_VALID_FLAGS)) { status = STATUS_INVALID_PARAMETER; if (cchDest != 0) { *pszDest = '\0'; } } else if (cchDest == 0) { // only fail if there was actually a non-empty format string if (*pszFormat != '\0') { if (pszDest == NULL) { status = STATUS_INVALID_PARAMETER; } else { status = STATUS_BUFFER_OVERFLOW; } } } else { size_t cchNewDestLength = 0; status = RtlStringVPrintfWorkerA(pszDest, cchDest, &cchNewDestLength, pszFormat, argList); pszDestEnd = pszDest + cchNewDestLength; cchRemaining = cchDest - cchNewDestLength; if (NT_SUCCESS(status) && (dwFlags & STRSAFE_FILL_BEHIND_NULL) && (cchRemaining > 1)) { size_t cbRemaining; // safe to multiply cchRemaining * sizeof(char) since cchRemaining < NTSTRSAFE_MAX_CCH and sizeof(char) is 1 cbRemaining = (cchRemaining * sizeof(char)) + (cbDest % sizeof(char)); // handle the STRSAFE_FILL_BEHIND_NULL flag RtlStringExHandleFillBehindNullA(pszDestEnd, cbRemaining, dwFlags); } } } else { if (cchDest != 0) { *pszDest = '\0'; } } if (!NT_SUCCESS(status) && (dwFlags & (STRSAFE_NO_TRUNCATION | STRSAFE_FILL_ON_FAILURE | STRSAFE_NULL_ON_FAILURE)) && (cbDest != 0)) { // handle the STRSAFE_FILL_ON_FAILURE, STRSAFE_NULL_ON_FAILURE, and STRSAFE_NO_TRUNCATION flags RtlStringExHandleOtherFlagsA(pszDest, cbDest, 0, &pszDestEnd, &cchRemaining, dwFlags); } if (NT_SUCCESS(status) || (status == STATUS_BUFFER_OVERFLOW)) { if (ppszDestEnd) { *ppszDestEnd = pszDestEnd; } if (pcbRemaining) { // safe to multiply cchRemaining * sizeof(char) since cchRemaining < NTSTRSAFE_MAX_CCH and sizeof(char) is 1 *pcbRemaining = (cchRemaining * sizeof(char)) + (cbDest % sizeof(char)); } } } return status; } NTSTRSAFEDDI RtlStringCbVPrintfExW( __out_bcount(cbDest) NTSTRSAFE_PWSTR pszDest, __in size_t cbDest, __deref_opt_out_bcount(*pcbRemaining) NTSTRSAFE_PWSTR* ppszDestEnd, __out_opt size_t* pcbRemaining, __in DWORD dwFlags, __in __format_string NTSTRSAFE_PCWSTR pszFormat, __in va_list argList) { NTSTATUS status; size_t cchDest = cbDest / sizeof(wchar_t); status = RtlStringExValidateDestW(pszDest, cchDest, NTSTRSAFE_MAX_CCH, dwFlags); if (NT_SUCCESS(status)) { NTSTRSAFE_PWSTR pszDestEnd = pszDest; size_t cchRemaining = cchDest; status = RtlStringExValidateSrcW(&pszFormat, NULL, NTSTRSAFE_MAX_CCH, dwFlags); if (NT_SUCCESS(status)) { if (dwFlags & (~STRSAFE_VALID_FLAGS)) { status = STATUS_INVALID_PARAMETER; if (cchDest != 0) { *pszDest = L'\0'; } } else if (cchDest == 0) { // only fail if there was actually a non-empty format string if (*pszFormat != L'\0') { if (pszDest == NULL) { status = STATUS_INVALID_PARAMETER; } else { status = STATUS_BUFFER_OVERFLOW; } } } else { size_t cchNewDestLength = 0; status = RtlStringVPrintfWorkerW(pszDest, cchDest, &cchNewDestLength, pszFormat, argList); pszDestEnd = pszDest + cchNewDestLength; cchRemaining = cchDest - cchNewDestLength; if (NT_SUCCESS(status) && (dwFlags & STRSAFE_FILL_BEHIND_NULL)) { size_t cbRemaining; // safe to multiply cchRemaining * sizeof(wchar_t) since cchRemaining < NTSTRSAFE_MAX_CCH and sizeof(wchar_t) is 2 cbRemaining = (cchRemaining * sizeof(wchar_t)) + (cbDest % sizeof(wchar_t)); // handle the STRSAFE_FILL_BEHIND_NULL flag RtlStringExHandleFillBehindNullW(pszDestEnd, cbRemaining, dwFlags); } } } else { if (cchDest != 0) { *pszDest = L'\0'; } } if (!NT_SUCCESS(status) && (dwFlags & (STRSAFE_NO_TRUNCATION | STRSAFE_FILL_ON_FAILURE | STRSAFE_NULL_ON_FAILURE)) && (cbDest != 0)) { // handle the STRSAFE_FILL_ON_FAILURE, STRSAFE_NULL_ON_FAILURE, and STRSAFE_NO_TRUNCATION flags RtlStringExHandleOtherFlagsW(pszDest, cbDest, 0, &pszDestEnd, &cchRemaining, dwFlags); } if (NT_SUCCESS(status) || (status == STATUS_BUFFER_OVERFLOW)) { if (ppszDestEnd) { *ppszDestEnd = pszDestEnd; } if (pcbRemaining) { // safe to multiply cchRemaining * sizeof(wchar_t) since cchRemaining < NTSTRSAFE_MAX_CCH and sizeof(wchar_t) is 2 *pcbRemaining = (cchRemaining * sizeof(wchar_t)) + (cbDest % sizeof(wchar_t)); } } } return status; } #endif // !NTSTRSAFE_NO_CB_FUNCTIONS #ifndef NTSTRSAFE_NO_CCH_FUNCTIONS /*++ NTSTATUS RtlStringCchLength( __in LPCTSTR psz, __in __in_range(1, NTSTRSAFE_MAX_CCH) size_t cchMax, __out_opt __deref_out_range(<, cchMax) size_t* pcchLength 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 characters 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 cchMax characters. Arguments: psz - string to check the length of cchMax - maximum number of characters including the null terminator that psz is allowed to contain pcch - if the function succeeds and pcch is non-null, the current length in characters of psz excluding the null terminator will be returned. This out parameter is equivalent to the return value of strlen(psz) Notes: psz can be null but the function will fail cchMax should be greater than zero 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 cchMax characters failure - the operation did not succeed It is strongly recommended to use the NT_SUCCESS() macro to test the return value of this function. --*/ __checkReturn NTSTRSAFEDDI RtlStringCchLengthA( __in STRSAFE_PCNZCH psz, __in __in_range(1, NTSTRSAFE_MAX_CCH) size_t cchMax, __out_opt __deref_out_range(<, cchMax) size_t* pcchLength) { NTSTATUS status; if ((psz == NULL) || (cchMax > NTSTRSAFE_MAX_CCH)) { status = STATUS_INVALID_PARAMETER; } else { status = RtlStringLengthWorkerA(psz, cchMax, pcchLength); } if (!NT_SUCCESS(status) && pcchLength) { *pcchLength = 0; } return status; } __checkReturn NTSTRSAFEDDI RtlStringCchLengthW( __in STRSAFE_PCNZWCH psz, __in __in_range(1, NTSTRSAFE_MAX_CCH) size_t cchMax, __out_opt __deref_out_range(<, cchMax) size_t* pcchLength) { NTSTATUS status; if ((psz == NULL) || (cchMax > NTSTRSAFE_MAX_CCH)) { status = STATUS_INVALID_PARAMETER; } else { status = RtlStringLengthWorkerW(psz, cchMax, pcchLength); } if (!NT_SUCCESS(status) && pcchLength) { *pcchLength = 0; } return status; } #endif // !NTSTRSAFE_NO_CCH_FUNCTIONS #ifndef NTSTRSAFE_NO_CB_FUNCTIONS /*++ NTSTATUS RtlStringCbLength( __in 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 - the operation did not succeed It is strongly recommended to use the NT_SUCCESS() macro to test the return value of this function. --*/ __checkReturn NTSTRSAFEDDI RtlStringCbLengthA( __in 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; } __checkReturn NTSTRSAFEDDI RtlStringCbLengthW( __in STRSAFE_PCNZWCH psz, __in __in_range(1, NTSTRSAFE_MAX_CCH * sizeof(wchar_t)) size_t cbMax, __out_opt __deref_out_range(<, cbMax - 1) size_t* pcbLength) { NTSTATUS status; size_t cchMax = cbMax / sizeof(wchar_t); size_t cchLength = 0; if ((psz == NULL) || (cchMax > NTSTRSAFE_MAX_CCH)) { status = STATUS_INVALID_PARAMETER; } else { status = RtlStringLengthWorkerW(psz, cchMax, &cchLength); } if (pcbLength) { if (NT_SUCCESS(status)) { // safe to multiply cchLength * sizeof(wchar_t) since cchLength < NTSTRSAFE_MAX_CCH and sizeof(wchar_t) is 2 *pcbLength = cchLength * sizeof(wchar_t); } else { *pcbLength = 0; } } return status; } #endif // !NTSTRSAFE_NO_CB_FUNCTIONS #ifndef NTSTRSAFE_NO_CCH_FUNCTIONS /*++ NTSTATUS RtlUnalignedStringCchLength( __in LPCUTSTR psz, __in __in_range(1, NTSTRSAFE_MAX_CCH) size_t cchMax, __out_opt __deref_out_range(<, cchMax) size_t* pcchLength OPTIONAL ); Routine Description: This routine is a version of RtlStringCchLength that accepts an unaligned string pointer. 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 cchMax characters. Arguments: psz - string to check the length of cchMax - maximum number of characters including the null terminator that psz is allowed to contain pcch - if the function succeeds and pcch is non-null, the current length in characters of psz excluding the null terminator will be returned. This out parameter is equivalent to the return value of strlen(psz) Notes: psz can be null but the function will fail cchMax should be greater than zero 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 cchMax characters failure - the operation did not succeed It is strongly recommended to use the NT_SUCCESS() macro to test the return value of this function. --*/ #ifdef ALIGNMENT_MACHINE __checkReturn NTSTRSAFEDDI RtlUnalignedStringCchLengthW( __in STRSAFE_PCUNZWCH psz, __in __in_range(1, NTSTRSAFE_MAX_CCH) size_t cchMax, __out_opt __deref_out_range(<, cchMax) size_t* pcchLength) { NTSTATUS status; if ((psz == NULL) || (cchMax > NTSTRSAFE_MAX_CCH)) { status = STATUS_INVALID_PARAMETER; } else { status = RtlUnalignedStringLengthWorkerW(psz, cchMax, pcchLength); } if (!NT_SUCCESS(status) && pcchLength) { *pcchLength = 0; } return status; } #else #define RtlUnalignedStringCchLengthW RtlStringCchLengthW #endif // !ALIGNMENT_MACHINE #endif // !NTSTRSAFE_NO_CCH_FUNCTIONS #ifndef NTSTRSAFE_NO_CB_FUNCTIONS /*++ NTSTATUS RtlUnalignedStringCbLength( __in LPCUTSTR 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 version of RtlStringCbLength that accepts an unaligned string pointer. 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 - the operation did not succeed It is strongly recommended to use the NT_SUCCESS() macro to test the return value of this function. --*/ #ifdef ALIGNMENT_MACHINE __checkReturn NTSTRSAFEDDI RtlUnalignedStringCbLengthW( __in STRSAFE_PCUNZWCH psz, __in __in_range(1, NTSTRSAFE_MAX_CCH * sizeof(wchar_t)) size_t cbMax, __out_opt __deref_out_range(<, cbMax - 1) size_t* pcbLength) { NTSTATUS status; size_t cchMax = cbMax / sizeof(wchar_t); size_t cchLength = 0; if ((psz == NULL) || (cchMax > NTSTRSAFE_MAX_CCH)) { status = STATUS_INVALID_PARAMETER; } else { status = RtlUnalignedStringLengthWorkerW(psz, cchMax, &cchLength); } if (pcbLength) { if (NT_SUCCESS(status)) { // safe to multiply cchLength * sizeof(wchar_t) since cchLength < NTSTRSAFE_MAX_CCH and sizeof(wchar_t) is 2 *pcbLength = cchLength * sizeof(wchar_t); } else { *pcbLength = 0; } } return status; } #else #define RtlUnalignedStringCbLengthW RtlStringCbLengthW #endif // !ALIGNMENT_MACHINE #endif // !NTSTRSAFE_NO_CB_FUNCTIONS #ifndef NTSTRSAFE_NO_UNICODE_STRING_FUNCTIONS /*++ NTSTATUS RtlUnicodeStringInit( __out PUNICODE_STRING DestinationString, __in_opt NTSTRSAFE_PCWSTR pszSrc OPTIONAL ); Routine Description: The RtlUnicodeStringInit function initializes a counted unicode string from pszSrc. This function returns an NTSTATUS value. It returns STATUS_SUCCESS if the counted unicode string was sucessfully 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 or null terminated Notes: DestinationString should not be NULL. See RtlUnicodeStringInitEx if you require the handling of NULL values. Return Value: STATUS_SUCCESS - failure - the operation did not succeed STATUS_INVALID_PARAMETER - this return value is an indication that the source string was too large and DestinationString could not be initialized It is strongly recommended to use the NT_SUCCESS() macro to test the return value of this function. --*/ NTSTRSAFEDDI RtlUnicodeStringInit( __out PUNICODE_STRING DestinationString, __in_opt NTSTRSAFE_PCWSTR pszSrc) { return RtlUnicodeStringInitWorker(DestinationString, pszSrc, NTSTRSAFE_UNICODE_STRING_MAX_CCH, 0); } /*++ 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 sucessfully 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. --*/ 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; } /*++ NTSTATUS RtlUnicodeStringValidate( __in PCUNICODE_STRING SourceString ); Routine Description: The RtlUnicodeStringValidate function checks the counted unicode string to make sure that is is valid. This function returns an NTSTATUS value. It returns STATUS_SUCCESS if the counted unicode string is valid. Arguments: SourceString - pointer to the counted unicode string to be checked Notes: SourceString should not be NULL. See RtlUnicodeStringValidateEx if you require the handling of NULL values. Return Value: STATUS_SUCCESS - SourceString is a valid counted unicode string failure - the operation did not succeed STATUS_INVALID_PARAMETER - this return value is an indication that SourceString is not a valid counted unicode string It is strongly recommended to use the NT_SUCCESS() macro to test the return value of this function. --*/ NTSTRSAFEDDI RtlUnicodeStringValidate( __in PCUNICODE_STRING SourceString) { return RtlUnicodeStringValidateWorker(SourceString, NTSTRSAFE_UNICODE_STRING_MAX_CCH, 0); } /*++ NTSTATUS RtlUnicodeStringValidateEx( __in PCUNICODE_STRING SourceString OPTIONAL, __in DWORD dwFlags ); Routine Description: In addition to functionality provided by RtlUnicodeStringValidate, this routine includes the flags parameter allows additional controls. This function returns an NTSTATUS value. It returns STATUS_SUCCESS if the counted unicode string is valid. Arguments: SourceString - pointer to the counted unicode string to be checked dwFlags - controls some details of the validation: STRSAFE_IGNORE_NULLS allows SourceString to be NULL (will return STATUS_SUCCESS for this case). Return Value: STATUS_SUCCESS - SourceString is a valid counted unicode string failure - the operation did not succeed STATUS_INVALID_PARAMETER - this return value is an indication that the source string is not a valide counted unicode string given the flags passed. It is strongly recommended to use the NT_SUCCESS() macro to test the return value of this function. --*/ NTSTRSAFEDDI RtlUnicodeStringValidateEx( __in PCUNICODE_STRING SourceString, __in DWORD dwFlags) { NTSTATUS status; if (dwFlags & (~STRSAFE_UNICODE_STRING_VALID_FLAGS)) { status = STATUS_INVALID_PARAMETER; } else { status = RtlUnicodeStringValidateWorker(SourceString, NTSTRSAFE_UNICODE_STRING_MAX_CCH, dwFlags); } return status; } /*++ NTSTATUS RtlStringCchCopyUnicodeString( __out_ecount(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_ecount(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; } /*++ NTSTATUS RtlStringCbCopyUnicodeString( __out_bcount(cbDest) PWSTR pszDest, __in size_t cbDest, __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 cbDest - size of destination buffer in bytes. length must be = (DestinationString->Length + sizeof(wchar_t)) 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 RtlStringCbCopyUnicodeStringEx 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 RtlStringCbCopyUnicodeString( __out_bcount(cbDest) NTSTRSAFE_PWSTR pszDest, __in size_t cbDest, __in PCUNICODE_STRING SourceString) { NTSTATUS status; size_t cchDest = cbDest / sizeof(wchar_t); 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 { // Suppress espx false positive - cchDest cannot be 0 here #pragma warning(push) #pragma warning(disable : __WARNING_POTENTIAL_BUFFER_OVERFLOW_HIGH_PRIORITY) *pszDest = L'\0'; #pragma warning(pop) } } return status; } /*++ NTSTATUS RtlStringCchCopyUnicodeStringEx( __out_ecount(cchDest) PWSTR pszDest OPTIONAL, __in size_t cchDest, __in PCUNICODE_STRING SourceString OPTIONAL, __deref_opt_out_ecount(*pcchRemaining) PWSTR* ppszDestEnd OPTIONAL, __out_opt size_t* pcchRemaining OPTIONAL, __in DWORD dwFlags ); Routine Description: This routine copies a PUNICODE_STRING to a PWSTR. In addition to functionality provided by RtlStringCchCopyUnicodeString, this routine also returns a pointer to the end of the destination string and the number of characters left in the destination string including the null terminator. The flags parameter allows additional controls. 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 ppszDestEnd - if ppszDestEnd is non-null, the function will return a pointer to the end of the destination string. If the function copied any data, the result will point to the null termination character pcchRemaining - if pcchRemaining is non-null, the function will return the number of characters left in the destination string, including the null terminator dwFlags - controls some details of the string copy: STRSAFE_FILL_BEHIND_NULL if the function succeeds, the low byte of dwFlags will be used to fill the uninitialize part of destination buffer behind the null terminator STRSAFE_IGNORE_NULLS treat NULL string pointers like empty strings (TEXT("")). this flag is useful for emulating functions like lstrcpy STRSAFE_FILL_ON_FAILURE if the function fails, the low byte of dwFlags will be used to fill all of the destination buffer, and it will be null terminated. This will overwrite any truncated string returned when the failure is STATUS_BUFFER_OVERFLOW STRSAFE_NO_TRUNCATION / STRSAFE_NULL_ON_FAILURE if the function fails, the destination buffer will be set to the empty string. This will overwrite any truncated string returned when the failure is STATUS_BUFFER_OVERFLOW. Notes: Behavior is undefined if source and destination strings overlap. pszDest and SourceString should not be NULL unless the STRSAFE_IGNORE_NULLS flag is specified. If STRSAFE_IGNORE_NULLS is passed, both pszDest and SourceString may be NULL. An error may still be returned even though NULLS are ignored due to insufficient space. 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. 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 RtlStringCchCopyUnicodeStringEx( __out_ecount(cchDest) NTSTRSAFE_PWSTR pszDest, __in size_t cchDest, __in PCUNICODE_STRING SourceString, __deref_opt_out_ecount(*pcchRemaining) NTSTRSAFE_PWSTR* ppszDestEnd, __out_opt size_t* pcchRemaining, __in DWORD dwFlags) { NTSTATUS status; status = RtlStringExValidateDestW(pszDest, cchDest, NTSTRSAFE_UNICODE_STRING_MAX_CCH, dwFlags); if (NT_SUCCESS(status)) { wchar_t* pszSrc; size_t cchSrcLength; wchar_t* pszDestEnd = pszDest; size_t cchRemaining = cchDest; status = RtlUnicodeStringValidateSrcWorker(SourceString, &pszSrc, &cchSrcLength, NTSTRSAFE_UNICODE_STRING_MAX_CCH, dwFlags); if (NT_SUCCESS(status)) { if (dwFlags & (~STRSAFE_VALID_FLAGS)) { status = STATUS_INVALID_PARAMETER; if (cchDest != 0) { *pszDest = L'\0'; } } else if (cchDest == 0) { // only fail if there was actually src data to copy if (cchSrcLength != 0) { if (pszDest == NULL) { status = STATUS_INVALID_PARAMETER; } else { status = STATUS_BUFFER_OVERFLOW; } } } else { size_t cchCopied = 0; status = RtlStringCopyWideCharArrayWorker(pszDest, cchDest, &cchCopied, pszSrc, cchSrcLength); pszDestEnd = pszDest + cchCopied; cchRemaining = cchDest - cchCopied; if (NT_SUCCESS(status) && (dwFlags & STRSAFE_FILL_BEHIND_NULL) && (cchRemaining > 1)) { size_t cbRemaining; // safe to multiply cchRemaining * sizeof(wchar_t) since cchRemaining < NTSTRSAFE_MAX_CCH and sizeof(wchar_t) is 2 cbRemaining = cchRemaining * sizeof(wchar_t); // handle the STRSAFE_FILL_BEHIND_NULL flag RtlStringExHandleFillBehindNullW(pszDestEnd, cbRemaining, dwFlags); } } } else { if (cchDest != 0) { *pszDest = L'\0'; } } if (!NT_SUCCESS(status) && (dwFlags & (STRSAFE_NO_TRUNCATION | STRSAFE_FILL_ON_FAILURE | STRSAFE_NULL_ON_FAILURE)) && (cchDest != 0)) { size_t cbDest; // safe to multiply cchDest * sizeof(wchar_t) since cchDest < NTSTRSAFE_MAX_CCH and sizeof(wchar_t) is 2 cbDest = cchDest * sizeof(wchar_t); // handle the STRSAFE_FILL_ON_FAILURE, STRSAFE_NULL_ON_FAILURE, and STRSAFE_NO_TRUNCATION flags RtlStringExHandleOtherFlagsW(pszDest, cbDest, 0, &pszDestEnd, &cchRemaining, dwFlags); } if (NT_SUCCESS(status) || (status == STATUS_BUFFER_OVERFLOW)) { if (ppszDestEnd) { *ppszDestEnd = pszDestEnd; } if (pcchRemaining) { *pcchRemaining = cchRemaining; } } } return status; } /*++ NTSTATUS RtlStringCbCopyUnicodeStringEx( __out_bcount(cbDest) PWSTR pszDest OPTIONAL, __in size_t cbDest, __in PCUNICODE_STRING SourceString OPTIONAL, __deref_opt_out_bcount(*pcbRemaining) PWSTR* ppszDestEnd OPTIONAL, __out_opt size_t* pcbRemaining OPTIONAL, __in DWORD dwFlags ); Routine Description: This routine copies a PUNICODE_STRING to a PWSTR. In addition to functionality provided by RtlStringCbCopyUnicodeString, this routine also returns a pointer to the end of the destination string and the number of characters left in the destination string including the null terminator. The flags parameter allows additional controls. 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 ppszDestEnd - if ppszDestEnd is non-null, the function will return a pointer to the end of the destination string. If the function copied any data, the result will point to the null termination character pcbRemaining - pcbRemaining is non-null,the function will return the number of bytes left in the destination string, including the null terminator dwFlags - controls some details of the string copy: STRSAFE_FILL_BEHIND_NULL if the function succeeds, the low byte of dwFlags will be used to fill the uninitialize part of destination buffer behind the null terminator STRSAFE_IGNORE_NULLS treat NULL string pointers like empty strings (TEXT("")). this flag is useful for emulating functions like lstrcpy STRSAFE_FILL_ON_FAILURE if the function fails, the low byte of dwFlags will be used to fill all of the destination buffer, and it will be null terminated. This will overwrite any truncated string returned when the failure is STATUS_BUFFER_OVERFLOW STRSAFE_NO_TRUNCATION / STRSAFE_NULL_ON_FAILURE if the function fails, the destination buffer will be set to the empty string. This will overwrite any truncated string returned when the failure is STATUS_BUFFER_OVERFLOW. Notes: Behavior is undefined if source and destination strings overlap. pszDest and SourceString should not be NULL unless the STRSAFE_IGNORE_NULLS flag is specified. If STRSAFE_IGNORE_NULLS is passed, both pszDest and SourceString may be NULL. An error may still be returned even though NULLS are ignored due to insufficient space. 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. 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 RtlStringCbCopyUnicodeStringEx( __out_bcount(cbDest) NTSTRSAFE_PWSTR pszDest, __in size_t cbDest, __in PCUNICODE_STRING SourceString, __deref_opt_out_bcount(*pcbRemaining) NTSTRSAFE_PWSTR* ppszDestEnd, __out_opt size_t* pcbRemaining, __in DWORD dwFlags) { NTSTATUS status; size_t cchDest = cbDest / sizeof(wchar_t); status = RtlStringExValidateDestW(pszDest, cchDest, NTSTRSAFE_UNICODE_STRING_MAX_CCH, dwFlags); if (NT_SUCCESS(status)) { wchar_t* pszSrc; size_t cchSrcLength; wchar_t* pszDestEnd = pszDest; size_t cchRemaining = cchDest; status = RtlUnicodeStringValidateSrcWorker(SourceString, &pszSrc, &cchSrcLength, NTSTRSAFE_UNICODE_STRING_MAX_CCH, dwFlags); if (NT_SUCCESS(status)) { if (dwFlags & (~STRSAFE_VALID_FLAGS)) { status = STATUS_INVALID_PARAMETER; if (cchDest != 0) { *pszDest = L'\0'; } } else if (cchDest == 0) { // only fail if there was actually src data to copy if (cchSrcLength != 0) { if (pszDest == NULL) { status = STATUS_INVALID_PARAMETER; } else { status = STATUS_BUFFER_OVERFLOW; } } } else { size_t cchCopied = 0; status = RtlStringCopyWideCharArrayWorker(pszDest, cchDest, &cchCopied, pszSrc, cchSrcLength); pszDestEnd = pszDest + cchCopied; cchRemaining = cchDest - cchCopied; if (NT_SUCCESS(status) && (dwFlags & STRSAFE_FILL_BEHIND_NULL)) { size_t cbRemaining; // safe to multiply cchRemaining * sizeof(wchar_t) since cchRemaining < NTSTRSAFE_MAX_CCH and sizeof(wchar_t) is 2 cbRemaining = (cchRemaining * sizeof(wchar_t)) + (cbDest % sizeof(wchar_t)); // handle the STRSAFE_FILL_BEHIND_NULL flag RtlStringExHandleFillBehindNullW(pszDestEnd, cbRemaining, dwFlags); } } } else { if (cchDest != 0) { *pszDest = L'\0'; } } if (!NT_SUCCESS(status) && (dwFlags & (STRSAFE_NO_TRUNCATION | STRSAFE_FILL_ON_FAILURE | STRSAFE_NULL_ON_FAILURE)) && (cbDest != 0)) { // handle the STRSAFE_FILL_ON_FAILURE, STRSAFE_NULL_ON_FAILURE, and STRSAFE_NO_TRUNCATION flags RtlStringExHandleOtherFlagsW(pszDest, cbDest, 0, &pszDestEnd, &cchRemaining, dwFlags); } if (NT_SUCCESS(status) || (status == STATUS_BUFFER_OVERFLOW)) { if (ppszDestEnd) { *ppszDestEnd = pszDestEnd; } if (pcbRemaining) { // safe to multiply cchRemaining * sizeof(wchar_t) since cchRemaining < NTSTRSAFE_MAX_CCH and sizeof(wchar_t) is 2 *pcbRemaining = (cchRemaining * sizeof(wchar_t)) + (cbDest % sizeof(wchar_t)); } } } return status; } /*++ NTSTATUS RtlUnicodeStringCopyString( __out PUNICODE_STRING DestinationString, __in LPCTSTR pszSrc ); Routine Description: This routine is a safer version of the C built-in function 'strcpy' for UNICODE_STRINGs. 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 pszSrc will be copied to DestinationString as possible. Arguments: DestinationString - pointer to the counted unicode destination string pszSrc - source string which must be null terminated Notes: Behavior is undefined if source and destination strings overlap. DestinationString and pszSrc should not be NULL. See RtlUnicodeStringCopyStringEx if you require the handling of NULL values. Return Value: STATUS_SUCCESS - if there was source data and it was all copied 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. 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 RtlUnicodeStringCopyString( __out PUNICODE_STRING DestinationString, __in NTSTRSAFE_PCWSTR pszSrc) { NTSTATUS status; wchar_t* pszDest; size_t cchDest; status = RtlUnicodeStringValidateDestWorker(DestinationString, &pszDest, &cchDest, NULL, NTSTRSAFE_UNICODE_STRING_MAX_CCH, 0); if (NT_SUCCESS(status)) { size_t cchNewDestLength = 0; status = RtlWideCharArrayCopyStringWorker(pszDest, cchDest, &cchNewDestLength, pszSrc, NTSTRSAFE_UNICODE_STRING_MAX_CCH); // safe to multiply cchNewDestLength * sizeof(wchar_t) since cchDest < NTSTRSAFE_UNICODE_STRING_MAX_CCH and sizeof(wchar_t) is 2 DestinationString->Length = (USHORT)(cchNewDestLength * sizeof(wchar_t)); } return status; } /*++ NTSTATUS RtlUnicodeStringCopy( __out PUNICODE_STRING DestinationString, __in PCUNICODE_STRING SourceString ); Routine Description: This routine is a safer version of the C built-in function 'strcpy' for UNICODE_STRINGs. 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 Dest as possible. Arguments: DestinationString - pointer to the counted unicode destination string SourceString - pointer to the counted unicode source string Notes: Behavior is undefined if source and destination strings overlap. DestinationString and SourceString should not be NULL. See RtlUnicodeStringCopyEx if you require the handling of NULL values. Return Value: STATUS_SUCCESS - if there was source data and it was all copied 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. 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 RtlUnicodeStringCopy( __out PUNICODE_STRING DestinationString, __in PCUNICODE_STRING SourceString) { NTSTATUS status; wchar_t* pszDest; size_t cchDest; status = RtlUnicodeStringValidateDestWorker(DestinationString, &pszDest, &cchDest, NULL, NTSTRSAFE_UNICODE_STRING_MAX_CCH, 0); if (NT_SUCCESS(status)) { wchar_t* pszSrc; size_t cchSrcLength; size_t cchNewDestLength = 0; status = RtlUnicodeStringValidateSrcWorker(SourceString, &pszSrc, &cchSrcLength, NTSTRSAFE_UNICODE_STRING_MAX_CCH, 0); if (NT_SUCCESS(status)) { status = RtlWideCharArrayCopyWorker(pszDest, cchDest, &cchNewDestLength, pszSrc, cchSrcLength); } // safe to multiply cchNewDestLength * sizeof(wchar_t) since cchDest < NTSTRSAFE_UNICODE_STRING_MAX_CCH and sizeof(wchar_t) is 2 DestinationString->Length = (USHORT)(cchNewDestLength * sizeof(wchar_t)); } return status; } /*++ NTSTATUS RtlUnicodeStringCopyStringEx( __out PUNICODE_STRING DestinationString OPTIONAL, __in LPCTSTR pszSrc OPTIONAL, __out_opt PUNICODE_STRING RemainingString OPTIONAL, __in DWORD dwFlags ); Routine Description: This routine is a safer version of the C built-in function 'strcpy' for UNICODE_STRINGs with some additional parameters. In addition to the functionality provided by RtlUnicodeStringCopyString, this routine also returns a PUNICODE_STRING which points to the end of the destination string. The flags parameter allows additional controls. Arguments: DestinationString - pointer to the counted unicode destination string pszSrc - source string which must be null terminated RemainingString - if RemainingString is non-null, the function will format the pointer with the remaining buffer and number of bytes left in the destination string dwFlags - controls some details of the string copy: STRSAFE_FILL_BEHIND if the function succeeds, the low byte of dwFlags will be used to fill the uninitialize part of destination buffer STRSAFE_IGNORE_NULLS do not fault if DestinationString is null and treat NULL pszSrc like empty strings (L""). This flag is useful for emulating functions like lstrcpy STRSAFE_FILL_ON_FAILURE if the function fails, the low byte of dwFlags will be used to fill all of the destination buffer. This will overwrite any truncated string returned when the failure is STATUS_BUFFER_OVERFLOW STRSAFE_NO_TRUNCATION / STRSAFE_ZERO_LENGTH_ON_FAILURE if the function fails, the destination Length will be set to zero. This will overwrite any truncated string returned when the failure is STATUS_BUFFER_OVERFLOW. Notes: Behavior is undefined if source and destination strings overlap. DestinationString and pszSrc should not be NULL unless the STRSAFE_IGNORE_NULLS flag is specified. If STRSAFE_IGNORE_NULLS is passed, both DestinationString and pszSrc may be NULL. An error may still be returned even though NULLS are ignored. Behavior is undefined if DestinationString and RemainingString are the same pointer. Return Value: STATUS_SUCCESS - if there was source data and it was all copied 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. 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 RtlUnicodeStringCopyStringEx( __out PUNICODE_STRING DestinationString, __in NTSTRSAFE_PCWSTR pszSrc, __out_opt PUNICODE_STRING RemainingString, __in DWORD dwFlags) { NTSTATUS status; wchar_t* pszDest; size_t cchDest; status = RtlUnicodeStringValidateDestWorker(DestinationString, &pszDest, &cchDest, NULL, NTSTRSAFE_UNICODE_STRING_MAX_CCH, dwFlags); if (NT_SUCCESS(status)) { wchar_t* pszDestEnd = pszDest; size_t cchRemaining = cchDest; size_t cchNewDestLength = 0; status = RtlStringExValidateSrcW(&pszSrc, NULL, NTSTRSAFE_UNICODE_STRING_MAX_CCH, dwFlags); if (NT_SUCCESS(status)) { if (dwFlags & (~STRSAFE_UNICODE_STRING_VALID_FLAGS)) { status = STATUS_INVALID_PARAMETER; } else if (cchDest == 0) { // only fail if there was actually src data to copy if (*pszSrc != L'\0') { if (pszDest == NULL) { status = STATUS_INVALID_PARAMETER; } else { status = STATUS_BUFFER_OVERFLOW; } } } else { status = RtlWideCharArrayCopyStringWorker(pszDest, cchDest, &cchNewDestLength, pszSrc, NTSTRSAFE_UNICODE_STRING_MAX_CCH); pszDestEnd = pszDest + cchNewDestLength; cchRemaining = cchDest - cchNewDestLength; if (NT_SUCCESS(status) && (dwFlags & STRSAFE_FILL_BEHIND) && (cchRemaining != 0)) { // handle the STRSAFE_FILL_BEHIND flag RtlUnicodeStringExHandleFill(pszDestEnd, cchRemaining, dwFlags); } } } if (!NT_SUCCESS(status) && (dwFlags & (STRSAFE_NO_TRUNCATION | STRSAFE_FILL_ON_FAILURE | STRSAFE_ZERO_LENGTH_ON_FAILURE)) && (cchDest != 0)) { // handle the STRSAFE_NO_TRUNCATION, STRSAFE_FILL_ON_FAILURE, and STRSAFE_ZERO_LENGTH_ON_FAILURE flags RtlUnicodeStringExHandleOtherFlags(pszDest, cchDest, 0, &cchNewDestLength, &pszDestEnd, &cchRemaining, dwFlags); } if (DestinationString) { // safe to multiply cchNewDestLength * sizeof(wchar_t) since cchDest < NTSTRSAFE_UNICODE_STRING_MAX_CCH and sizeof(wchar_t) is 2 DestinationString->Length = (USHORT)(cchNewDestLength * sizeof(wchar_t)); } if (NT_SUCCESS(status) || (status == STATUS_BUFFER_OVERFLOW)) { if (RemainingString) { RemainingString->Length = 0; // safe to multiply cchRemaining * sizeof(wchar_t) since cchRemaining < NTSTRSAFE_UNICODE_STRING_MAX_CCH and sizeof(wchar_t) is 2 RemainingString->MaximumLength = (USHORT)(cchRemaining * sizeof(wchar_t)); RemainingString->Buffer = pszDestEnd; } } } return status; } /*++ NTSTATUS RtlUnicodeStringCopyEx( __out PUNICODE_STRING DestinationString OPTIONAL, __in PCUNICODE_STRING SourceString OPTIONAL, __out_opt PUNICODE_STRING RemainingString OPTIONAL, __in DWORD dwFlags ); Routine Description: This routine is a safer version of the C built-in function 'strcpy' for UNICODE_STRINGs with some additional parameters. In addition to the functionality provided by RtlUnicodeStringCopy, this routine also returns a PUNICODE_STRING which points to the end of the destination string. The flags parameter allows additional controls. Arguments: DestinationString - pointer to the counted unicode destination string SourceString - pointer to the counted unicode source string RemainingString - if RemainingString is non-null, the function will format the pointer with the remaining buffer and number of bytes left in the destination string dwFlags - controls some details of the string copy: STRSAFE_FILL_BEHIND if the function succeeds, the low byte of dwFlags will be used to fill the uninitialize part of destination buffer STRSAFE_IGNORE_NULLS do not fault if DestinationString is null and treat NULL pszSrc like empty strings (L""). This flag is useful for emulating functions like lstrcpy STRSAFE_FILL_ON_FAILURE if the function fails, the low byte of dwFlags will be used to fill all of the destination buffer. This will overwrite any truncated string returned when the failure is STATUS_BUFFER_OVERFLOW STRSAFE_NO_TRUNCATION / STRSAFE_ZERO_LENGTH_ON_FAILURE if the function fails, the destination Length will be set to zero. This will overwrite any truncated string returned when the failure is STATUS_BUFFER_OVERFLOW. Notes: Behavior is undefined if source and destination strings overlap. DestinationString and SourceString should not be NULL unless the STRSAFE_IGNORE_NULLS flag is specified. If STRSAFE_IGNORE_NULLS is passed, both DestinationString and SourceString may be NULL. An error may still be returned even though NULLS are ignored. Behavior is undefined if DestinationString and RemainingString are the same pointer. Return Value: STATUS_SUCCESS - if there was source data and it was all copied 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. 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 RtlUnicodeStringCopyEx( __out PUNICODE_STRING DestinationString, __in PCUNICODE_STRING SourceString, __out_opt PUNICODE_STRING RemainingString, __in DWORD dwFlags) { NTSTATUS status; wchar_t* pszDest; size_t cchDest; status = RtlUnicodeStringValidateDestWorker(DestinationString, &pszDest, &cchDest, NULL, NTSTRSAFE_UNICODE_STRING_MAX_CCH, dwFlags); if (NT_SUCCESS(status)) { wchar_t* pszSrc; size_t cchSrcLength; wchar_t* pszDestEnd = pszDest; size_t cchRemaining = cchDest; size_t cchNewDestLength = 0; status = RtlUnicodeStringValidateSrcWorker(SourceString, &pszSrc, &cchSrcLength, NTSTRSAFE_UNICODE_STRING_MAX_CCH, dwFlags); if (NT_SUCCESS(status)) { if (dwFlags & (~STRSAFE_UNICODE_STRING_VALID_FLAGS)) { status = STATUS_INVALID_PARAMETER; } else if (cchDest == 0) { // only fail if there was actually src data to copy if (cchSrcLength != 0) { if (pszDest == NULL) { status = STATUS_INVALID_PARAMETER; } else { status = STATUS_BUFFER_OVERFLOW; } } } else { status = RtlWideCharArrayCopyWorker(pszDest, cchDest, &cchNewDestLength, pszSrc, cchSrcLength); pszDestEnd = pszDest + cchNewDestLength; cchRemaining = cchDest - cchNewDestLength; if (NT_SUCCESS(status) && (dwFlags & STRSAFE_FILL_BEHIND) && (cchRemaining != 0)) { // handle the STRSAFE_FILL_BEHIND flag RtlUnicodeStringExHandleFill(pszDestEnd, cchRemaining, dwFlags); } } } if (!NT_SUCCESS(status) && (dwFlags & (STRSAFE_NO_TRUNCATION | STRSAFE_FILL_ON_FAILURE | STRSAFE_ZERO_LENGTH_ON_FAILURE)) && (cchDest != 0)) { // handle the STRSAFE_NO_TRUNCATION, STRSAFE_FILL_ON_FAILURE, and STRSAFE_ZERO_LENGTH_ON_FAILURE flags RtlUnicodeStringExHandleOtherFlags(pszDest, cchDest, 0, &cchNewDestLength, &pszDestEnd, &cchRemaining, dwFlags); } if (DestinationString) { // safe to multiply cchNewDestLength * sizeof(wchar_t) since cchDest < NTSTRSAFE_UNICODE_STRING_MAX_CCH and sizeof(wchar_t) is 2 DestinationString->Length = (USHORT)(cchNewDestLength * sizeof(wchar_t)); } if (NT_SUCCESS(status) || (status == STATUS_BUFFER_OVERFLOW)) { if (RemainingString) { RemainingString->Length = 0; // safe to multiply cchRemaining * sizeof(wchar_t) since cchRemaining < NTSTRSAFE_UNICODE_STRING_MAX_CCH and sizeof(wchar_t) is 2 RemainingString->MaximumLength = (USHORT)(cchRemaining * sizeof(wchar_t)); RemainingString->Buffer = pszDestEnd; } } } return status; } #ifndef NTSTRSAFE_NO_CCH_FUNCTIONS /*++ NTSTATUS RtlUnicodeStringCchCopyStringN( __out PUNICODE_STRING DestinationString, __in LPCTSTR pszSrc, __in size_t cchToCopy ); Routine Description: This routine is a safer version of the C built-in function 'strncpy' for PUNICODE_STRINGs. This function returns an NTSTATUS value, and not a pointer. It returns STATUS_SUCCESS if the entire string or the first cchToCopy characters were copied without truncation, otherwise it will return a failure code. In failure cases as much of pszSrc will be copied to DestinationString as possible. Arguments: DestinationString - pointer to the counted unicode destination string pszSrc - source string cchToCopy - maximum number of characters to copy from source string, not including the null terminator. Notes: Behavior is undefined if source and destination strings overlap. DestinationString and pszSrc should not be NULL. See RtlUnicodeStringCchCopyStringNEx if you require the handling of NULL values. Return Value: STATUS_SUCCESS - if there was source data and it was all copied 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. 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 RtlUnicodeStringCchCopyStringN( __out PUNICODE_STRING DestinationString, __in NTSTRSAFE_PCWSTR pszSrc, __in size_t cchToCopy) { NTSTATUS status; wchar_t* pszDest; size_t cchDest; status = RtlUnicodeStringValidateDestWorker(DestinationString, &pszDest, &cchDest, NULL, NTSTRSAFE_UNICODE_STRING_MAX_CCH, 0); if (NT_SUCCESS(status)) { size_t cchNewDestLength = 0; if (cchToCopy > NTSTRSAFE_UNICODE_STRING_MAX_CCH) { status = STATUS_INVALID_PARAMETER; } else { status = RtlWideCharArrayCopyStringWorker(pszDest, cchDest, &cchNewDestLength, pszSrc, cchToCopy); } // safe to multiply cchNewDestLength * sizeof(wchar_t) since cchDest < NTSTRSAFE_UNICODE_STRING_MAX_CCH and sizeof(wchar_t) is 2 DestinationString->Length = (USHORT)(cchNewDestLength * sizeof(wchar_t)); } return status; } #endif // !NTSTRSAFE_NO_CCH_FUNCTIONS #ifndef NTSTRSAFE_NO_CB_FUNCTIONS /*++ NTSTATUS RtlUnicodeStringCbCopyStringN( __out PUNICODE_STRING DestinationString, __in LPCTSTR pszSrc, __in size_t cbToCopy ); Routine Description: This routine is a safer version of the C built-in function 'strncpy' for PUNICODE_STRINGs. This function returns an NTSTATUS value, and not a pointer. It returns STATUS_SUCCESS if the entire string or the first cbToCopy bytes were copied without truncation, otherwise it will return a failure code. In failure cases as much of pszSrc will be copied to DestinationString as possible. Arguments: DestinationString - pointer to the counted unicode destination string 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. DestinationString and pszSrc should not be NULL. See RtlUnicodeStringCopyCbStringEx if you require the handling of NULL values. Return Value: STATUS_SUCCESS - if there was source data and it was all copied 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. 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 RtlUnicodeStringCbCopyStringN( __out PUNICODE_STRING DestinationString, __in NTSTRSAFE_PCWSTR pszSrc, __in size_t cbToCopy) { NTSTATUS status; wchar_t* pszDest; size_t cchDest; status = RtlUnicodeStringValidateDestWorker(DestinationString, &pszDest, &cchDest, NULL, NTSTRSAFE_UNICODE_STRING_MAX_CCH, 0); if (NT_SUCCESS(status)) { size_t cchNewDestLength = 0; size_t cchToCopy = cbToCopy / sizeof(wchar_t); if (cchToCopy > NTSTRSAFE_UNICODE_STRING_MAX_CCH) { status = STATUS_INVALID_PARAMETER; } else { status = RtlWideCharArrayCopyStringWorker(pszDest, cchDest, &cchNewDestLength, pszSrc, cchToCopy); } // safe to multiply cchNewDestLength * sizeof(wchar_t) since cchDest < NTSTRSAFE_UNICODE_STRING_MAX_CCH and sizeof(wchar_t) is 2 DestinationString->Length = (USHORT)(cchNewDestLength * sizeof(wchar_t)); } return status; } #endif // !NTSTRSAFE_NO_CB_FUNCTIONS #ifndef NTSTRSAFE_NO_CCH_FUNCTIONS /*++ NTSTATUS RtlUnicodeStringCchCopyN( __out PUNICODE_STRING DestinationString, __in PCUNICODE_STRING SourceString, __in size_t cchToCopy ); Routine Description: This routine is a safer version of the C built-in function 'strncpy' for PUNICODE_STRINGs. This function returns an NTSTATUS value, and not a pointer. It returns STATUS_SUCCESS if the entire string or the first cchToCopy characters were copied without truncation, otherwise it will return a failure code. In failure cases as much of SourceString will be copied to DestinationString as possible. Arguments: DestinationString - pointer to the counted unicode destination string SourceString - pointer to the counted unicode source string cchToCopy - maximum number of characters to copy from source string, not including the null terminator. Notes: Behavior is undefined if source and destination strings overlap. DestinationString and SourceString should not be NULL. See RtlUnicodeStringCchCopyNEx if you require the handling of NULL values. Return Value: STATUS_SUCCESS - if there was source data and it was all copied 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. 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 RtlUnicodeStringCchCopyN( __out PUNICODE_STRING DestinationString, __in PCUNICODE_STRING SourceString, __in size_t cchToCopy) { NTSTATUS status; wchar_t* pszDest; size_t cchDest; status = RtlUnicodeStringValidateDestWorker(DestinationString, &pszDest, &cchDest, NULL, NTSTRSAFE_UNICODE_STRING_MAX_CCH, 0); if (NT_SUCCESS(status)) { wchar_t* pszSrc; size_t cchSrcLength; size_t cchNewDestLength = 0; status = RtlUnicodeStringValidateSrcWorker(SourceString, &pszSrc, &cchSrcLength, NTSTRSAFE_UNICODE_STRING_MAX_CCH, 0); if (NT_SUCCESS(status)) { if (cchToCopy > NTSTRSAFE_UNICODE_STRING_MAX_CCH) { status = STATUS_INVALID_PARAMETER; } else { if (cchSrcLength < cchToCopy) { cchToCopy = cchSrcLength; } status = RtlWideCharArrayCopyWorker(pszDest, cchDest, &cchNewDestLength, pszSrc, cchToCopy); } } // safe to multiply cchNewDestLength * sizeof(wchar_t) since cchDest < NTSTRSAFE_UNICODE_STRING_MAX_CCH and sizeof(wchar_t) is 2 DestinationString->Length = (USHORT)(cchNewDestLength * sizeof(wchar_t)); } return status; } #endif // !NTSTRSAFE_NO_CCH_FUNCTIONS #ifndef NTSTRSAFE_NO_CB_FUNCTIONS /*++ NTSTATUS RtlUnicodeStringCbCopyN( __out PUNICODE_STRING DestinationString, __in PCUNICODE_STRING SourceString, __in size_t cbToCopy ); Routine Description: This routine is a safer version of the C built-in function 'strncpy' for PUNICODE_STRINGs. This function returns an NTSTATUS value, and not a pointer. It returns STATUS_SUCCESS if the entire string or the first cbToCopy bytes were copied without truncation, otherwise it will return a failure code. In failure cases as much of SourceString will be copied to DestinationString as possible. Arguments: DestinationString - pointer to the counted unicode destination string SourceString - pointer to the counted unicode 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. DestinationString and SourceString should not be NULL. See RtlUnicodeStringCbCopyNEx if you require the handling of NULL values. Return Value: STATUS_SUCCESS - if there was source data and it was all copied 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. 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 RtlUnicodeStringCbCopyN( __out PUNICODE_STRING DestinationString, __in PCUNICODE_STRING SourceString, __in size_t cbToCopy) { NTSTATUS status; wchar_t* pszDest; size_t cchDest; status = RtlUnicodeStringValidateDestWorker(DestinationString, &pszDest, &cchDest, NULL, NTSTRSAFE_UNICODE_STRING_MAX_CCH, 0); if (NT_SUCCESS(status)) { wchar_t* pszSrc; size_t cchSrcLength; size_t cchNewDestLength = 0; status = RtlUnicodeStringValidateSrcWorker(SourceString, &pszSrc, &cchSrcLength, NTSTRSAFE_UNICODE_STRING_MAX_CCH, 0); if (NT_SUCCESS(status)) { size_t cchToCopy = cbToCopy / sizeof(wchar_t); if (cchToCopy > NTSTRSAFE_UNICODE_STRING_MAX_CCH) { status = STATUS_INVALID_PARAMETER; } else { if (cchSrcLength < cchToCopy) { cchToCopy = cchSrcLength; } status = RtlWideCharArrayCopyWorker(pszDest, cchDest, &cchNewDestLength, pszSrc, cchToCopy); } } // safe to multiply cchNewDestLength * sizeof(wchar_t) since cchDest < NTSTRSAFE_UNICODE_STRING_MAX_CCH and sizeof(wchar_t) is 2 DestinationString->Length = (USHORT)(cchNewDestLength * sizeof(wchar_t)); } return status; } #endif // !NTSTRSAFE_NO_CB_FUNCTIONS #ifndef NTSTRSAFE_NO_CCH_FUNCTIONS /*++ NTSTATUS RtlUnicodeStringCchCopyStringNEx( __out PUNICODE_STRING DestinationString OPTIONAL, __in LPCTSTR pszSrc OPTIONAL, __in size_t cchToCopy, __out_opt PUNICODE_STRING RemainingString OPTIONAL, __in DWORD dwFlags ); Routine Description: This routine is a safer version of the C built-in function 'strncpy' with some additional parameters and for PUNICODE_STRINGs. In addition to the functionality provided by RtlUnicodeStringCchCopyStringN, this routine also returns a PUNICODE_STRING which points to the end of the destination string. The flags parameter allows additional controls. Arguments: DestinationString - pointer to the counted unicode destination string pszSrc - source string cchToCopy - maximum number of characters to copy from source string RemainingString - if RemainingString is non-null, the function will format the pointer with the remaining buffer and number of bytes left in the destination string dwFlags - controls some details of the string copy: STRSAFE_FILL_BEHIND if the function succeeds, the low byte of dwFlags will be used to fill the uninitialize part of destination buffer STRSAFE_IGNORE_NULLS do not fault if DestinationString is null and treat NULL pszSrc like empty strings (L""). This flag is useful for emulating functions like lstrcpy STRSAFE_FILL_ON_FAILURE if the function fails, the low byte of dwFlags will be used to fill all of the destination buffer. This will overwrite any truncated string returned when the failure is STATUS_BUFFER_OVERFLOW STRSAFE_NO_TRUNCATION / STRSAFE_ZERO_LENGTH_ON_FAILURE if the function fails, the destination Length will be set to zero. This will overwrite any truncated string returned when the failure is STATUS_BUFFER_OVERFLOW. Notes: Behavior is undefined if source and destination strings overlap. pszDest and pszSrc should not be NULL unless the STRSAFE_IGNORE_NULLS flag is specified. If STRSAFE_IGNORE_NULLS is passed, both pszDest and pszSrc may be NULL. An error may still be returned even though NULLS are ignored due to insufficient space. Return Value: STATUS_SUCCESS - if there was source data and it was all copied 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. 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 RtlUnicodeStringCchCopyStringNEx( __out PUNICODE_STRING DestinationString, __in NTSTRSAFE_PCWSTR pszSrc, __in size_t cchToCopy, __out_opt PUNICODE_STRING RemainingString, __in DWORD dwFlags) { NTSTATUS status; wchar_t* pszDest; size_t cchDest; status = RtlUnicodeStringValidateDestWorker(DestinationString, &pszDest, &cchDest, NULL, NTSTRSAFE_UNICODE_STRING_MAX_CCH, dwFlags); if (NT_SUCCESS(status)) { wchar_t* pszDestEnd = pszDest; size_t cchRemaining = cchDest; size_t cchNewDestLength = 0; status = RtlStringExValidateSrcW(&pszSrc, &cchToCopy, NTSTRSAFE_UNICODE_STRING_MAX_CCH, dwFlags); if (NT_SUCCESS(status)) { if (dwFlags & (~STRSAFE_UNICODE_STRING_VALID_FLAGS)) { status = STATUS_INVALID_PARAMETER; } else if (cchDest == 0) { // only fail if there was actually src data to copy if ((cchToCopy != 0) && (*pszSrc != L'\0')) { if (pszDest == NULL) { status = STATUS_INVALID_PARAMETER; } else { status = STATUS_BUFFER_OVERFLOW; } } } else { status = RtlWideCharArrayCopyStringWorker(pszDest, cchDest, &cchNewDestLength, pszSrc, cchToCopy); pszDestEnd = pszDest + cchNewDestLength; cchRemaining = cchDest - cchNewDestLength; if (NT_SUCCESS(status) && (dwFlags & STRSAFE_FILL_BEHIND) && (cchRemaining != 0)) { // handle the STRSAFE_FILL_BEHIND flag RtlUnicodeStringExHandleFill(pszDestEnd, cchRemaining, dwFlags); } } } if (!NT_SUCCESS(status) && (dwFlags & (STRSAFE_NO_TRUNCATION | STRSAFE_FILL_ON_FAILURE | STRSAFE_ZERO_LENGTH_ON_FAILURE)) && (cchDest != 0)) { // handle the STRSAFE_NO_TRUNCATION, STRSAFE_FILL_ON_FAILURE, and STRSAFE_ZERO_LENGTH_ON_FAILURE flags RtlUnicodeStringExHandleOtherFlags(pszDest, cchDest, 0, &cchNewDestLength, &pszDestEnd, &cchRemaining, dwFlags); } if (DestinationString) { // safe to multiply cchNewDestLength * sizeof(wchar_t) since cchDest < NTSTRSAFE_UNICODE_STRING_MAX_CCH and sizeof(wchar_t) is 2 DestinationString->Length = (USHORT)(cchNewDestLength * sizeof(wchar_t)); } if (NT_SUCCESS(status) || (status == STATUS_BUFFER_OVERFLOW)) { if (RemainingString) { RemainingString->Length = 0; // safe to multiply cchRemaining * sizeof(wchar_t) since cchRemaining < NTSTRSAFE_UNICODE_STRING_MAX_CCH and sizeof(wchar_t) is 2 RemainingString->MaximumLength = (USHORT)(cchRemaining * sizeof(wchar_t)); RemainingString->Buffer = pszDestEnd; } } } return status; } #endif // !NTSTRSAFE_NO_CCH_FUNCTIONS #ifndef NTSTRSAFE_NO_CB_FUNCTIONS /*++ NTSTATUS RtlUnicodeStringCbCopyStringNEx( __out PUNICODE_STRING DestinationString OPTIONAL, __in LPCTSTR pszSrc OPTIONAL, __in size_t cbToCopy, __out_opt PUNICODE_STRING RemainingString OPTIONAL, __in DWORD dwFlags ); Routine Description: This routine is a safer version of the C built-in function 'strncpy' with some additional parameters and for PUNICODE_STRINGs. In addition to the functionality provided by RtlUnicodeStringCbCopyStringN, this routine also returns a PUNICODE_STRING which points to the end of the destination string. The flags parameter allows additional controls. Arguments: DestinationString - pointer to the counted unicode destination string pszSrc - source string cbToCopy - maximum number of bytes to copy from source string RemainingString - if RemainingString is non-null, the function will format the pointer with the remaining buffer and number of bytes left in the destination string dwFlags - controls some details of the string copy: STRSAFE_FILL_BEHIND if the function succeeds, the low byte of dwFlags will be used to fill the uninitialize part of destination buffer STRSAFE_IGNORE_NULLS do not fault if DestinationString is null and treat NULL pszSrc like empty strings (L""). This flag is useful for emulating functions like lstrcpy STRSAFE_FILL_ON_FAILURE if the function fails, the low byte of dwFlags will be used to fill all of the destination buffer. This will overwrite any truncated string returned when the failure is STATUS_BUFFER_OVERFLOW STRSAFE_NO_TRUNCATION / STRSAFE_ZERO_LENGTH_ON_FAILURE if the function fails, the destination Length will be set to zero. This will overwrite any truncated string returned when the failure is STATUS_BUFFER_OVERFLOW. Notes: Behavior is undefined if source and destination strings overlap. DestinationString and pszSrc should not be NULL unless the STRSAFE_IGNORE_NULLS flag is specified. If STRSAFE_IGNORE_NULLS is passed, both DestinationString and pszSrc may be NULL. An error may still be returned even though NULLS are ignored due to insufficient space. Return Value: STATUS_SUCCESS - if there was source data and it was all copied 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. 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 RtlUnicodeStringCbCopyStringNEx( __out PUNICODE_STRING DestinationString, __in NTSTRSAFE_PCWSTR pszSrc, __in size_t cbToCopy, __out_opt PUNICODE_STRING RemainingString, __in DWORD dwFlags) { NTSTATUS status; wchar_t* pszDest; size_t cchDest; status = RtlUnicodeStringValidateDestWorker(DestinationString, &pszDest, &cchDest, NULL, NTSTRSAFE_UNICODE_STRING_MAX_CCH, dwFlags); if (NT_SUCCESS(status)) { wchar_t* pszDestEnd = pszDest; size_t cchRemaining = cchDest; size_t cchNewDestLength = 0; size_t cchToCopy = cbToCopy / sizeof(wchar_t); status = RtlStringExValidateSrcW(&pszSrc, &cchToCopy, NTSTRSAFE_UNICODE_STRING_MAX_CCH, dwFlags); if (NT_SUCCESS(status)) { if (dwFlags & (~STRSAFE_UNICODE_STRING_VALID_FLAGS)) { status = STATUS_INVALID_PARAMETER; } else if (cchDest == 0) { // only fail if there was actually src data to copy if ((cchToCopy != 0) && (*pszSrc != L'\0')) { if (pszDest == NULL) { status = STATUS_INVALID_PARAMETER; } else { status = STATUS_BUFFER_OVERFLOW; } } } else { status = RtlWideCharArrayCopyStringWorker(pszDest, cchDest, &cchNewDestLength, pszSrc, cchToCopy); pszDestEnd = pszDest + cchNewDestLength; cchRemaining = cchDest - cchNewDestLength; if (NT_SUCCESS(status) && (dwFlags & STRSAFE_FILL_BEHIND) && (cchRemaining != 0)) { // handle the STRSAFE_FILL_BEHIND flag RtlUnicodeStringExHandleFill(pszDestEnd, cchRemaining, dwFlags); } } } if (!NT_SUCCESS(status) && (dwFlags & (STRSAFE_NO_TRUNCATION | STRSAFE_FILL_ON_FAILURE | STRSAFE_ZERO_LENGTH_ON_FAILURE)) && (cchDest != 0)) { // handle the STRSAFE_NO_TRUNCATION, STRSAFE_FILL_ON_FAILURE, and STRSAFE_ZERO_LENGTH_ON_FAILURE flags RtlUnicodeStringExHandleOtherFlags(pszDest, cchDest, 0, &cchNewDestLength, &pszDestEnd, &cchRemaining, dwFlags); } if (DestinationString) { // safe to multiply cchNewDestLength * sizeof(wchar_t) since cchDest < NTSTRSAFE_UNICODE_STRING_MAX_CCH and sizeof(wchar_t) is 2 DestinationString->Length = (USHORT)(cchNewDestLength * sizeof(wchar_t)); } if (NT_SUCCESS(status) || (status == STATUS_BUFFER_OVERFLOW)) { if (RemainingString) { RemainingString->Length = 0; // safe to multiply cchRemaining * sizeof(wchar_t) since cchRemaining < NTSTRSAFE_UNICODE_STRING_MAX_CCH and sizeof(wchar_t) is 2 RemainingString->MaximumLength = (USHORT)(cchRemaining * sizeof(wchar_t)); RemainingString->Buffer = pszDestEnd; } } } return status; } #endif // !NTSTRSAFE_NO_CB_FUNCTIONS #ifndef NTSTRSAFE_NO_CCH_FUNCTIONS /*++ NTSTATUS RtlUnicodeStringCchCopyNEx( __out PUNICODE_STRING DestinationString OPTIONAL, __in PCUNICODE_STRING SourceString OPTIONAL, __in size_t cchToCopy, __out_opt PUNICODE_STRING RemainingString OPTIONAL, __in DWORD dwFlags ); Routine Description: This routine is a safer version of the C built-in function 'strncpy' with some additional parameters and for PUNICODE_STRINGs. In addition to the functionality provided by RtlUnicodeStringCchCopyN, this routine also returns a PUNICODE_STRING which points to the end of the destination string. The flags parameter allows additional controls. Arguments: DestinationString - pointer to the counted unicode destination string SourceString - pointer to the counted unicode source string cchToCopy - maximum number of characters to copy from source string RemainingString - if RemainingString is non-null, the function will format the pointer with the remaining buffer and number of bytes left in the destination string dwFlags - controls some details of the string copy: STRSAFE_FILL_BEHIND if the function succeeds, the low byte of dwFlags will be used to fill the uninitialize part of destination buffer STRSAFE_IGNORE_NULLS do not fault if DestinationString is null and treat NULL SourceString like empty strings (L""). This flag is useful for emulating functions like lstrcpy STRSAFE_FILL_ON_FAILURE if the function fails, the low byte of dwFlags will be used to fill all of the destination buffer. This will overwrite any truncated string returned when the failure is STATUS_BUFFER_OVERFLOW STRSAFE_NO_TRUNCATION / STRSAFE_ZERO_LENGTH_ON_FAILURE if the function fails, the destination Length will be set to zero. This will overwrite any truncated string returned when the failure is STATUS_BUFFER_OVERFLOW. Notes: Behavior is undefined if source and destination strings overlap. DestinationString and SourceString should not be NULL unless the STRSAFE_IGNORE_NULLS flag is specified. If STRSAFE_IGNORE_NULLS is passed, both DestinationString and SourceString may be NULL. An error may still be returned even though NULLS are ignored due to insufficient space. Return Value: STATUS_SUCCESS - if there was source data and it was all copied 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. 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 RtlUnicodeStringCchCopyNEx( __out PUNICODE_STRING DestinationString, __in PCUNICODE_STRING SourceString, __in size_t cchToCopy, __out_opt PUNICODE_STRING RemainingString, __in DWORD dwFlags) { NTSTATUS status; wchar_t* pszDest; size_t cchDest; status = RtlUnicodeStringValidateDestWorker(DestinationString, &pszDest, &cchDest, NULL, NTSTRSAFE_UNICODE_STRING_MAX_CCH, dwFlags); if (NT_SUCCESS(status)) { wchar_t* pszSrc; size_t cchSrcLength; wchar_t* pszDestEnd = pszDest; size_t cchRemaining = cchDest; size_t cchNewDestLength = 0; status = RtlUnicodeStringValidateSrcWorker(SourceString, &pszSrc, &cchSrcLength, NTSTRSAFE_UNICODE_STRING_MAX_CCH, dwFlags); if (NT_SUCCESS(status)) { if (cchToCopy > NTSTRSAFE_UNICODE_STRING_MAX_CCH) { status = STATUS_INVALID_PARAMETER; } else { if (cchSrcLength < cchToCopy) { cchToCopy = cchSrcLength; } if (dwFlags & (~STRSAFE_UNICODE_STRING_VALID_FLAGS)) { status = STATUS_INVALID_PARAMETER; } else if (cchDest == 0) { // only fail if there was actually src data to copy if (cchToCopy != 0) { if (pszDest == NULL) { status = STATUS_INVALID_PARAMETER; } else { status = STATUS_BUFFER_OVERFLOW; } } } else { status = RtlWideCharArrayCopyWorker(pszDest, cchDest, &cchNewDestLength, pszSrc, cchToCopy); pszDestEnd = pszDest + cchNewDestLength; cchRemaining = cchDest - cchNewDestLength; if (NT_SUCCESS(status) && (dwFlags & STRSAFE_FILL_BEHIND) && (cchRemaining != 0)) { // handle the STRSAFE_FILL_BEHIND flag RtlUnicodeStringExHandleFill(pszDestEnd, cchRemaining, dwFlags); } } } } if (!NT_SUCCESS(status) && (dwFlags & (STRSAFE_NO_TRUNCATION | STRSAFE_FILL_ON_FAILURE | STRSAFE_ZERO_LENGTH_ON_FAILURE)) && (cchDest != 0)) { // handle the STRSAFE_NO_TRUNCATION, STRSAFE_FILL_ON_FAILURE, and STRSAFE_ZERO_LENGTH_ON_FAILURE flags RtlUnicodeStringExHandleOtherFlags(pszDest, cchDest, 0, &cchNewDestLength, &pszDestEnd, &cchRemaining, dwFlags); } if (DestinationString) { // safe to multiply cchNewDestLength * sizeof(wchar_t) since cchDest < NTSTRSAFE_UNICODE_STRING_MAX_CCH and sizeof(wchar_t) is 2 DestinationString->Length = (USHORT)(cchNewDestLength * sizeof(wchar_t)); } if (NT_SUCCESS(status) || (status == STATUS_BUFFER_OVERFLOW)) { if (RemainingString) { RemainingString->Length = 0; // safe to multiply cchRemaining * sizeof(wchar_t) since cchRemaining < NTSTRSAFE_UNICODE_STRING_MAX_CCH and sizeof(wchar_t) is 2 RemainingString->MaximumLength = (USHORT)(cchRemaining * sizeof(wchar_t)); RemainingString->Buffer = pszDestEnd; } } } return status; } #endif // !NTSTRSAFE_NO_CCH_FUNCTIONS #ifndef NTSTRSAFE_NO_CB_FUNCTIONS /*++ NTSTATUS RtlUnicodeStringCbCopyNEx( __out PUNICODE_STRING DestinationString OPTIONAL, __in PCUNICODE_STRING SourceString OPTIONAL, __in size_t cbToCopy, __out_opt PUNICODE_STRING RemainingString OPTIONAL, __in DWORD dwFlags ); Routine Description: This routine is a safer version of the C built-in function 'strncpy' with some additional parameters and for PUNICODE_STRINGs. In addition to the functionality provided by RtlUnicodeStringCbCopyN, this routine also returns a PUNICODE_STRING which points to the end of the destination string. The flags parameter allows additional controls. Arguments: DestinationString - pointer to the counted unicode destination string SourceString - pointer to the counted unicode source string cbToCopy - maximum number of bytes to copy from source string RemainingString - if RemainingString is non-null, the function will format the pointer with the remaining buffer and number of bytes left in the destination string dwFlags - controls some details of the string copy: STRSAFE_FILL_BEHIND if the function succeeds, the low byte of dwFlags will be used to fill the uninitialize part of destination buffer STRSAFE_IGNORE_NULLS do not fault if DestinationString is null and treat NULL SourceString like empty strings (L""). This flag is useful for emulating functions like lstrcpy STRSAFE_FILL_ON_FAILURE if the function fails, the low byte of dwFlags will be used to fill all of the destination buffer. This will overwrite any truncated string returned when the failure is STATUS_BUFFER_OVERFLOW STRSAFE_NO_TRUNCATION / STRSAFE_ZERO_LENGTH_ON_FAILURE if the function fails, the destination Length will be set to zero. This will overwrite any truncated string returned when the failure is STATUS_BUFFER_OVERFLOW. Notes: Behavior is undefined if source and destination strings overlap. DestinationString and SourceString should not be NULL unless the STRSAFE_IGNORE_NULLS flag is specified. If STRSAFE_IGNORE_NULLS is passed, both DestinationString and SourceString may be NULL. An error may still be returned even though NULLS are ignored due to insufficient space. Return Value: STATUS_SUCCESS - if there was source data and it was all copied 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. 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 RtlUnicodeStringCbCopyNEx( __out PUNICODE_STRING DestinationString, __in PCUNICODE_STRING SourceString, __in size_t cbToCopy, __out_opt PUNICODE_STRING RemainingString, __in DWORD dwFlags) { NTSTATUS status; wchar_t* pszDest; size_t cchDest; status = RtlUnicodeStringValidateDestWorker(DestinationString, &pszDest, &cchDest, NULL, NTSTRSAFE_UNICODE_STRING_MAX_CCH, dwFlags); if (NT_SUCCESS(status)) { wchar_t* pszSrc; size_t cchSrcLength; wchar_t* pszDestEnd = pszDest; size_t cchRemaining = cchDest; size_t cchNewDestLength = 0; status = RtlUnicodeStringValidateSrcWorker(SourceString, &pszSrc, &cchSrcLength, NTSTRSAFE_UNICODE_STRING_MAX_CCH, dwFlags); if (NT_SUCCESS(status)) { size_t cchToCopy = cbToCopy / sizeof(wchar_t); if (cchToCopy > NTSTRSAFE_UNICODE_STRING_MAX_CCH) { status = STATUS_INVALID_PARAMETER; } else { if (cchSrcLength < cchToCopy) { cchToCopy = cchSrcLength; } if (dwFlags & (~STRSAFE_UNICODE_STRING_VALID_FLAGS)) { status = STATUS_INVALID_PARAMETER; } else if (cchDest == 0) { // only fail if there was actually src data to copy if (cchToCopy != 0) { if (pszDest == NULL) { status = STATUS_INVALID_PARAMETER; } else { status = STATUS_BUFFER_OVERFLOW; } } } else { status = RtlWideCharArrayCopyWorker(pszDest, cchDest, &cchNewDestLength, pszSrc, cchToCopy); pszDestEnd = pszDest + cchNewDestLength; cchRemaining = cchDest - cchNewDestLength; if (NT_SUCCESS(status) && (dwFlags & STRSAFE_FILL_BEHIND) && (cchRemaining != 0)) { // handle the STRSAFE_FILL_BEHIND flag RtlUnicodeStringExHandleFill(pszDestEnd, cchRemaining, dwFlags); } } } } if (!NT_SUCCESS(status) && (dwFlags & (STRSAFE_NO_TRUNCATION | STRSAFE_FILL_ON_FAILURE | STRSAFE_ZERO_LENGTH_ON_FAILURE)) && (cchDest != 0)) { // handle the STRSAFE_NO_TRUNCATION, STRSAFE_FILL_ON_FAILURE, and STRSAFE_ZERO_LENGTH_ON_FAILURE flags RtlUnicodeStringExHandleOtherFlags(pszDest, cchDest, 0, &cchNewDestLength, &pszDestEnd, &cchRemaining, dwFlags); } if (DestinationString) { // safe to multiply cchNewDestLength * sizeof(wchar_t) since cchDest < NTSTRSAFE_UNICODE_STRING_MAX_CCH and sizeof(wchar_t) is 2 DestinationString->Length = (USHORT)(cchNewDestLength * sizeof(wchar_t)); } if (NT_SUCCESS(status) || (status == STATUS_BUFFER_OVERFLOW)) { if (RemainingString) { RemainingString->Length = 0; // safe to multiply cchRemaining * sizeof(wchar_t) since cchRemaining < NTSTRSAFE_UNICODE_STRING_MAX_CCH and sizeof(wchar_t) is 2 RemainingString->MaximumLength = (USHORT)(cchRemaining * sizeof(wchar_t)); RemainingString->Buffer = pszDestEnd; } } } return status; } #endif // !NTSTRSAFE_NO_CB_FUNCTIONS /*++ NTSTATUS RtlUnicodeStringCatString( __inout PUNICODE_STRING DestinationString, __in LPCTSTR pszSrc ); Routine Description: This routine is a safer version of the C built-in function 'strcat' for UNICODE_STRINGs. This function returns an NTSTATUS value, and not a pointer. It returns STATUS_SUCCESS if the string was concatenated without truncation, otherwise it will return a failure code. In failure cases as much of pszSrc will be appended to DestinationString as possible. Arguments: DestinationString - pointer to the counted unicode destination string pszSrc - source string which must be null terminated Notes: Behavior is undefined if source and destination strings overlap. DestinationString and pszSrc should not be NULL. See RtlUnicodeStringCatStringEx if you require the handling of NULL values. Return Value: STATUS_SUCCESS - if there was source data and it was all concatenated 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 operation failed due to insufficient space. When this error occurs, the destination buffer is modified to contain a truncated version of the ideal result. 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 RtlUnicodeStringCatString( __inout PUNICODE_STRING DestinationString, __in NTSTRSAFE_PCWSTR pszSrc) { NTSTATUS status; wchar_t* pszDest; size_t cchDest; size_t cchDestLength; status = RtlUnicodeStringValidateDestWorker(DestinationString, &pszDest, &cchDest, &cchDestLength, NTSTRSAFE_UNICODE_STRING_MAX_CCH, 0); if (NT_SUCCESS(status)) { size_t cchCopied = 0; status = RtlWideCharArrayCopyStringWorker(pszDest + cchDestLength, cchDest - cchDestLength, &cchCopied, pszSrc, NTSTRSAFE_UNICODE_STRING_MAX_CCH); // safe to multiply (cchDestLength + cchCopied) * sizeof(wchar_t) since (cchDestLength + cchCopied) < NTSTRSAFE_UNICODE_STRING_MAX_CCH and sizeof(wchar_t) is 2 DestinationString->Length = (USHORT)((cchDestLength + cchCopied) * sizeof(wchar_t)); } return status; } /*++ NTSTATUS RtlUnicodeStringCat( __inout PUNICODE_STRING DestinationString, __in PCUNICODE_STRING SourceString ); Routine Description: This routine is a safer version of the C built-in function 'strcat' for UNICODE_STRINGs. This function returns an NTSTATUS value, and not a pointer. It returns STATUS_SUCCESS if the string was concatenated without truncation, otherwise it will return a failure code. In failure cases as much of SourceString will be appended to DestinationString as possible. Arguments: DestinationString - pointer to the counted unicode destination string SourceString - pointer to the counted unicode source string Notes: Behavior is undefined if source and destination strings overlap. DestinationString and pszSrc should not be NULL. See RtlUnicodeStringCatEx if you require the handling of NULL values. Return Value: STATUS_SUCCESS - if there was source data and it was all concatenated 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 operation failed due to insufficient space. When this error occurs, the destination buffer is modified to contain a truncated version of the ideal result. 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 RtlUnicodeStringCat( __inout PUNICODE_STRING DestinationString, __in PCUNICODE_STRING SourceString) { NTSTATUS status; wchar_t* pszDest; size_t cchDest; size_t cchDestLength; status = RtlUnicodeStringValidateDestWorker(DestinationString, &pszDest, &cchDest, &cchDestLength, NTSTRSAFE_UNICODE_STRING_MAX_CCH, 0); 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)) { size_t cchCopied = 0; status = RtlWideCharArrayCopyWorker(pszDest + cchDestLength, cchDest - cchDestLength, &cchCopied, pszSrc, cchSrcLength); // safe to multiply (cchDestLength + cchCopied) * sizeof(wchar_t) since (cchDestLength + cchCopied) < NTSTRSAFE_UNICODE_STRING_MAX_CCH and sizeof(wchar_t) is 2 DestinationString->Length = (USHORT)((cchDestLength + cchCopied) * sizeof(wchar_t)); } } return status; } /*++ NTSTATUS RtlUnicodeStringCatStringEx( __inout PUNICODE_STRING DestinationString OPTTONAL, __in LPCTSTR pszSrc OPTIONAL, __out_opt PUNICODE_STRING RemainingString OPTIONAL, __in DWORD dwFlags ); Routine Description: This routine is a safer version of the C built-in function 'strcat' for PUNICODE_STRINGs with some additional parameters. In addition to the functionality provided by RtlUnicodeStringCatString, this routine also returns a PUNICODE_STRING which points to the end of the destination string. The flags parameter allows additional controls. Arguments: DestinationString - pointer to the counted unicode destination string pszSrc - source string which must be null terminated RemainingString - if RemainingString is non-null, the function will format the pointer with the remaining buffer and number of bytes left in the destination string dwFlags - controls some details of the string copy: STRSAFE_FILL_BEHIND if the function succeeds, the low byte of dwFlags will be used to fill the uninitialize part of destination buffer STRSAFE_IGNORE_NULLS do not fault if DestinationString is null and treat NULL pszSrc like empty strings (L""). This flag is useful for emulating functions like lstrcpy STRSAFE_FILL_ON_FAILURE if the function fails, the low byte of dwFlags will be used to fill all of the destination buffer. This will overwrite any truncated string returned when the failure is STATUS_BUFFER_OVERFLOW STRSAFE_ZERO_LENGTH_ON_FAILURE if the function fails, the destination Length will be set to zero. This will overwrite any truncated string returned when the failure is STATUS_BUFFER_OVERFLOW. STRSAFE_NO_TRUNCATION if the function returns STATUS_BUFFER_OVERFLOW, pszDest will not contain a truncated string, it will remain unchanged. Notes: Behavior is undefined if source and destination strings overlap or if DestinationString and RemainingString are the same pointer. DestinationString and pszSrc should not be NULL unless the STRSAFE_IGNORE_NULLS flag is specified. If STRSAFE_IGNORE_NULLS is passed, both DestinationString and pszSrc may be NULL. An error may still be returned even though NULLS are ignored due to insufficient space. Return Value: STATUS_SUCCESS - if there was source data and it was all concatenated 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 operation failed due to insufficient space. When this error occurs, the destination buffer is modified to contain a truncated version of the ideal result. 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 RtlUnicodeStringCatStringEx( __inout PUNICODE_STRING DestinationString, __in NTSTRSAFE_PCWSTR pszSrc, __out_opt PUNICODE_STRING RemainingString, __in DWORD dwFlags) { NTSTATUS status; wchar_t* pszDest; size_t cchDest; size_t cchDestLength; status = RtlUnicodeStringValidateDestWorker(DestinationString, &pszDest, &cchDest, &cchDestLength, NTSTRSAFE_UNICODE_STRING_MAX_CCH, dwFlags); if (NT_SUCCESS(status)) { wchar_t* pszDestEnd = pszDest + cchDestLength; size_t cchRemaining = cchDest - cchDestLength; size_t cchNewDestLength = cchDestLength; status = RtlStringExValidateSrcW(&pszSrc, NULL, NTSTRSAFE_UNICODE_STRING_MAX_CCH, dwFlags); if (NT_SUCCESS(status)) { if (dwFlags & (~STRSAFE_UNICODE_STRING_VALID_FLAGS)) { status = STATUS_INVALID_PARAMETER; } else if (cchRemaining == 0) { // only fail if there was actually src data to append if (*pszSrc != L'\0') { if (pszDest == NULL) { status = STATUS_INVALID_PARAMETER; } else { status = STATUS_BUFFER_OVERFLOW; } } } else { size_t cchCopied = 0; status = RtlWideCharArrayCopyStringWorker(pszDestEnd, cchRemaining, &cchCopied, pszSrc, NTSTRSAFE_UNICODE_STRING_MAX_CCH); pszDestEnd = pszDestEnd + cchCopied; cchRemaining = cchRemaining - cchCopied; cchNewDestLength = cchDestLength + cchCopied; if (NT_SUCCESS(status) && (dwFlags & STRSAFE_FILL_BEHIND) && (cchRemaining != 0)) { // handle the STRSAFE_FILL_BEHIND flag RtlUnicodeStringExHandleFill(pszDestEnd, cchRemaining, dwFlags); } } } if (!NT_SUCCESS(status) && (dwFlags & (STRSAFE_NO_TRUNCATION | STRSAFE_FILL_ON_FAILURE | STRSAFE_ZERO_LENGTH_ON_FAILURE)) && (cchDest != 0)) { // handle the STRSAFE_NO_TRUNCATION, STRSAFE_FILL_ON_FAILURE, and STRSAFE_ZERO_LENGTH_ON_FAILURE flags RtlUnicodeStringExHandleOtherFlags(pszDest, cchDest, cchDestLength, &cchNewDestLength, &pszDestEnd, &cchRemaining, dwFlags); } if (DestinationString) { // safe to multiply cchNewDestLength * sizeof(wchar_t) since cchDest < NTSTRSAFE_UNICODE_STRING_MAX_CCH and sizeof(wchar_t) is 2 DestinationString->Length = (USHORT)(cchNewDestLength * sizeof(wchar_t)); } if (NT_SUCCESS(status) || (status == STATUS_BUFFER_OVERFLOW)) { if (RemainingString) { RemainingString->Length = 0; // safe to multiply cchRemaining * sizeof(wchar_t) since cchRemaining < NTSTRSAFE_UNICODE_STRING_MAX_CCH and sizeof(wchar_t) is 2 RemainingString->MaximumLength = (USHORT)(cchRemaining * sizeof(wchar_t)); RemainingString->Buffer = pszDestEnd; } } } return status; } /*++ NTSTATUS RtlUnicodeStringCatEx( __inout PUNICODE_STRING DestinationString OPTIONAL, __in PCUNICODE_STRING SourceString OPTIONAL, __out_opt PUNICODE_STRING RemainingString OPTIONAL, __in DWORD dwFlags ); Routine Description: This routine is a safer version of the C built-in function 'strcat' for PUNICODE_STRINGs with some additional parameters. In addition to the functionality provided by RtlUnicodeStringCat, this routine also returns a PUNICODE_STRING which points to the end of the destination string. The flags parameter allows additional controls. Arguments: DestinationString - pointer to the counted unicode destination string SourceString - pointer to the counted unicode source string RemainingString - if RemainingString is non-null, the function will format the pointer with the remaining buffer and number of bytes left in the destination string dwFlags - controls some details of the string copy: STRSAFE_FILL_BEHIND if the function succeeds, the low byte of dwFlags will be used to fill the uninitialize part of destination buffer STRSAFE_IGNORE_NULLS do not fault if DestinationString is null and treat NULL pszSrc like empty strings (L""). This flag is useful for emulating functions like lstrcpy STRSAFE_FILL_ON_FAILURE if the function fails, the low byte of dwFlags will be used to fill all of the destination buffer. This will overwrite any truncated string returned when the failure is STATUS_BUFFER_OVERFLOW STRSAFE_ZERO_LENGTH_ON_FAILURE if the function fails, the destination Length will be set to zero. This will overwrite any truncated string returned when the failure is STATUS_BUFFER_OVERFLOW. STRSAFE_NO_TRUNCATION if the function returns STATUS_BUFFER_OVERFLOW, pszDest will not contain a truncated string, it will remain unchanged. Notes: Behavior is undefined if source and destination strings overlap or if DestinationString and RemainingString are the same pointer. DestinationString and SourceString should not be NULL unless the STRSAFE_IGNORE_NULLS flag is specified. If STRSAFE_IGNORE_NULLS is passed, both DestinationString and SourceString may be NULL. An error may still be returned even though NULLS are ignored due to insufficient space. Return Value: STATUS_SUCCESS - if there was source data and it was all concatenated 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 operation failed due to insufficient space. When this error occurs, the destination buffer is modified to contain a truncated version of the ideal result. 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 RtlUnicodeStringCatEx( __inout PUNICODE_STRING DestinationString, __in PCUNICODE_STRING SourceString, __out_opt PUNICODE_STRING RemainingString, __in DWORD dwFlags) { NTSTATUS status; wchar_t* pszDest; size_t cchDest; size_t cchDestLength; status = RtlUnicodeStringValidateDestWorker(DestinationString, &pszDest, &cchDest, &cchDestLength, NTSTRSAFE_UNICODE_STRING_MAX_CCH, dwFlags); if (NT_SUCCESS(status)) { wchar_t* pszSrc; size_t cchSrcLength; wchar_t* pszDestEnd = pszDest + cchDestLength; size_t cchRemaining = cchDest - cchDestLength; size_t cchNewDestLength = cchDestLength; status = RtlUnicodeStringValidateSrcWorker(SourceString, &pszSrc, &cchSrcLength, NTSTRSAFE_UNICODE_STRING_MAX_CCH, dwFlags); if (NT_SUCCESS(status)) { if (dwFlags & (~STRSAFE_UNICODE_STRING_VALID_FLAGS)) { status = STATUS_INVALID_PARAMETER; } else if (cchRemaining == 0) { // only fail if there was actually src data to append if (cchSrcLength != 0) { if (pszDest == NULL) { status = STATUS_INVALID_PARAMETER; } else { status = STATUS_BUFFER_OVERFLOW; } } } else { size_t cchCopied = 0; status = RtlWideCharArrayCopyWorker(pszDestEnd, cchRemaining, &cchCopied, pszSrc, cchSrcLength); pszDestEnd = pszDestEnd + cchCopied; cchRemaining = cchRemaining - cchCopied; cchNewDestLength = cchDestLength + cchCopied; if (NT_SUCCESS(status) && (dwFlags & STRSAFE_FILL_BEHIND) && (cchRemaining != 0)) { // handle the STRSAFE_FILL_BEHIND flag RtlUnicodeStringExHandleFill(pszDestEnd, cchRemaining, dwFlags); } } } if (!NT_SUCCESS(status) && (dwFlags & (STRSAFE_NO_TRUNCATION | STRSAFE_FILL_ON_FAILURE | STRSAFE_ZERO_LENGTH_ON_FAILURE)) && (cchDest != 0)) { // handle the STRSAFE_NO_TRUNCATION, STRSAFE_FILL_ON_FAILURE, and STRSAFE_ZERO_LENGTH_ON_FAILURE flags RtlUnicodeStringExHandleOtherFlags(pszDest, cchDest, cchDestLength, &cchNewDestLength, &pszDestEnd, &cchRemaining, dwFlags); } if (DestinationString) { // safe to multiply cchNewDestLength * sizeof(wchar_t) since cchDest < NTSTRSAFE_UNICODE_STRING_MAX_CCH and sizeof(wchar_t) is 2 DestinationString->Length = (USHORT)(cchNewDestLength * sizeof(wchar_t)); } if (NT_SUCCESS(status) || (status == STATUS_BUFFER_OVERFLOW)) { if (RemainingString) { RemainingString->Length = 0; // safe to multiply cchRemaining * sizeof(wchar_t) since cchRemaining < NTSTRSAFE_UNICODE_STRING_MAX_CCH and sizeof(wchar_t) is 2 RemainingString->MaximumLength = (USHORT)(cchRemaining * sizeof(wchar_t)); RemainingString->Buffer = pszDestEnd; } } } return status; } #ifndef NTSTRSAFE_NO_CCH_FUNCTIONS /*++ NTSTATUS RtlUnicodeStringCchCatStringN( __inout PUNICODE_STRING DestinationString, __in LPCTSTR pszSrc, __in size_t cchToAppend ); Routine Description: This routine is a safer version of the C built-in function 'strncat' for PUNICODE_STRINGs. 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, otherwise it will return a failure code. In failure cases as much of pszSrc will be appended to DestinationString as possible. Arguments: DestinationString - pointer to the counted unicode destination string pszSrc - source string cchToAppend - maximum number of characters to append Notes: Behavior is undefined if source and destination strings overlap. DestinationString and pszSrc should not be NULL. See RtlUnicodeStringCchCatStringNEx if you require the handling of NULL values. Return Value: STATUS_SUCCESS - if all of pszSrc or the first cchToAppend characters were concatenated to DestinationString 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 operation failed due to insufficient space. When this error occurs, the destination buffer is modified to contain a truncated version of the ideal result. 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 RtlUnicodeStringCchCatStringN( __inout PUNICODE_STRING DestinationString, __in NTSTRSAFE_PCWSTR pszSrc, __in size_t cchToAppend) { NTSTATUS status; wchar_t* pszDest; size_t cchDest; size_t cchDestLength; status = RtlUnicodeStringValidateDestWorker(DestinationString, &pszDest, &cchDest, &cchDestLength, NTSTRSAFE_UNICODE_STRING_MAX_CCH, 0); if (NT_SUCCESS(status)) { if (cchToAppend > NTSTRSAFE_UNICODE_STRING_MAX_CCH) { status = STATUS_INVALID_PARAMETER; } else { size_t cchCopied = 0; status = RtlWideCharArrayCopyStringWorker(pszDest + cchDestLength, cchDest - cchDestLength, &cchCopied, pszSrc, cchToAppend); // safe to multiply (cchDestLength + cchCopied) * sizeof(wchar_t) since (cchDestLength + cchCopied) < NTSTRSAFE_UNICODE_STRING_MAX_CCH and sizeof(wchar_t) is 2 DestinationString->Length = (USHORT)((cchDestLength + cchCopied) * sizeof(wchar_t)); } } return status; } #endif // !NTSTRSAFE_NO_CCH_FUNCTIONS #ifndef NTSTRSAFE_NO_CB_FUNCTIONS /*++ NTSTATUS RtlUnicodeStringCbCatStringN( __inout PUNICODE_STRING DestinationString, __in LPCTSTR pszSrc, __in size_t cbToAppend ); Routine Description: This routine is a safer version of the C built-in function 'strncat' for PUNICODE_STRINGs. This function returns an NTSTATUS value, and not a pointer. It returns STATUS_SUCCESS if all of pszSrc or the first cbToAppend bytes were appended to the destination string, otherwise it will return a failure code. In failure cases as much of pszSrc will be appended to DestinationString as possible. Arguments: DestinationString - pointer to the counted unicode destination string pszSrc - source string cbToAppend - maximum number of bytes to append Notes: Behavior is undefined if source and destination strings overlap. DestinationString and pszSrc should not be NULL. See RtlUnicodeStringCbCatStringNEx if you require the handling of NULL values. Return Value: STATUS_SUCCESS - if all of pszSrc or the first cbToAppend bytes were concatenated to pszDest 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 operation failed due to insufficient space. When this error occurs, the destination buffer is modified to contain a truncated version of the ideal result. 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 RtlUnicodeStringCbCatStringN( __inout PUNICODE_STRING DestinationString, __in NTSTRSAFE_PCWSTR pszSrc, __in size_t cbToAppend) { NTSTATUS status; wchar_t* pszDest; size_t cchDest; size_t cchDestLength; status = RtlUnicodeStringValidateDestWorker(DestinationString, &pszDest, &cchDest, &cchDestLength, NTSTRSAFE_UNICODE_STRING_MAX_CCH, 0); if (NT_SUCCESS(status)) { size_t cchToAppend = cbToAppend / sizeof(wchar_t); if (cchToAppend > NTSTRSAFE_UNICODE_STRING_MAX_CCH) { status = STATUS_INVALID_PARAMETER; } else { size_t cchCopied = 0; status = RtlWideCharArrayCopyStringWorker(pszDest + cchDestLength, cchDest - cchDestLength, &cchCopied, pszSrc, cchToAppend); // safe to multiply (cchDestLength + cchCopied) * sizeof(wchar_t) since (cchDestLength + cchCopied) < NTSTRSAFE_UNICODE_STRING_MAX_CCH and sizeof(wchar_t) is 2 DestinationString->Length = (USHORT)((cchDestLength + cchCopied) * sizeof(wchar_t)); } } return status; } #endif // !NTSTRSAFE_NO_CB_FUNCTIONS #ifndef NTSTRSAFE_NO_CCH_FUNCTIONS /*++ NTSTATUS RtlUnicodeStringCchCatN( __inout PUNICODE_STRING DestinationString, __in PCUNICODE_STRING SourceString, __in size_t cchToAppend ); Routine Description: This routine is a safer version of the C built-in function 'strncat' for PUNICODE_STRINGs. This function returns an NTSTATUS value, and not a pointer. It returns STATUS_SUCCESS if all of SourceString or the first cchToAppend characters were appended to the destination string, otherwise it will return a failure code. In failure cases as much of SourceString will be appended to DestinationString as possible. Arguments: DestinationString - pointer to the counted unicode destination string SourceString - pointer to the counted unicode source string cchToAppend - maximum number of characters to append Notes: Behavior is undefined if source and destination strings overlap. DestinationString and SourceString should not be NULL. See RtlUnicodeStringCchCatNEx if you require the handling of NULL values. Return Value: STATUS_SUCCESS - if all of SourceString or the first cchToAppend characters were concatenated to DestinationString 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 operation failed due to insufficient space. When this error occurs, the destination buffer is modified to contain a truncated version of the ideal result. 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 RtlUnicodeStringCchCatN( __inout PUNICODE_STRING DestinationString, __in PCUNICODE_STRING SourceString, __in size_t cchToAppend) { NTSTATUS status; wchar_t* pszDest; size_t cchDest; size_t cchDestLength; status = RtlUnicodeStringValidateDestWorker(DestinationString, &pszDest, &cchDest, &cchDestLength, NTSTRSAFE_UNICODE_STRING_MAX_CCH, 0); 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)) { if (cchToAppend > NTSTRSAFE_UNICODE_STRING_MAX_CCH) { status = STATUS_INVALID_PARAMETER; } else { size_t cchCopied = 0; if (cchSrcLength < cchToAppend) { cchToAppend = cchSrcLength; } status = RtlWideCharArrayCopyWorker(pszDest + cchDestLength, cchDest - cchDestLength, &cchCopied, pszSrc, cchToAppend); // safe to multiply (cchDestLength + cchCopied) * sizeof(wchar_t) since (cchDestLength + cchCopied) < NTSTRSAFE_UNICODE_STRING_MAX_CCH and sizeof(wchar_t) is 2 DestinationString->Length = (USHORT)((cchDestLength + cchCopied) * sizeof(wchar_t)); } } } return status; } #endif // !NTSTRSAFE_NO_CCH_FUNCTIONS #ifndef NTSTRSAFE_NO_CB_FUNCTIONS /*++ NTSTATUS RtlUnicodeStringCbCatN( __inout PUNICODE_STRING DestinationString, __in PCUNICODE_STRING SourceString, __in size_t cbToAppend ); Routine Description: This routine is a safer version of the C built-in function 'strncat' for PUNICODE_STRINGs. This function returns an NTSTATUS value, and not a pointer. It returns STATUS_SUCCESS if all of SourceString or the first cbToAppend bytes were appended to the destination string, otherwise it will return a failure code. In failure cases as much of SourceString will be appended to DestinationString as possible. Arguments: DestinationString - pointer to the counted unicode destination string SourceString - pointer to the counted unicode source string cbToAppend - maximum number of bytes to append Notes: Behavior is undefined if source and destination strings overlap. DestinationString and SourceString should not be NULL. See RtlUnicodeStringCbCatNEx if you require the handling of NULL values. Return Value: STATUS_SUCCESS - if all of SourceString or the first cbToAppend bytes were concatenated to pszDest 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 operation failed due to insufficient space. When this error occurs, the destination buffer is modified to contain a truncated version of the ideal result. 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 RtlUnicodeStringCbCatN( __inout PUNICODE_STRING DestinationString, __in PCUNICODE_STRING SourceString, __in size_t cbToAppend) { NTSTATUS status; wchar_t* pszDest; size_t cchDest; size_t cchDestLength; status = RtlUnicodeStringValidateDestWorker(DestinationString, &pszDest, &cchDest, &cchDestLength, NTSTRSAFE_UNICODE_STRING_MAX_CCH, 0); 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)) { size_t cchToAppend = cbToAppend / sizeof(wchar_t); if (cchToAppend > NTSTRSAFE_UNICODE_STRING_MAX_CCH) { status = STATUS_INVALID_PARAMETER; } else { size_t cchCopied = 0; if (cchSrcLength < cchToAppend) { cchToAppend = cchSrcLength; } status = RtlWideCharArrayCopyWorker(pszDest + cchDestLength, cchDest - cchDestLength, &cchCopied, pszSrc, cchToAppend); // safe to multiply (cchDestLength + cchCopied) * sizeof(wchar_t) since (cchDestLength + cchCopied) < NTSTRSAFE_UNICODE_STRING_MAX_CCH and sizeof(wchar_t) is 2 DestinationString->Length = (USHORT)((cchDestLength + cchCopied) * sizeof(wchar_t)); } } } return status; } #endif // !NTSTRSAFE_NO_CB_FUNCTIONS #ifndef NTSTRSAFE_NO_CCH_FUNCTIONS /*++ NTSTATUS RtlUnicodeStringCchCatStringNEx( __inout PUNICODE_STRING DestinationString OPTIONAL, __in LPCTSTR pszSrc OPTIONAL, __in size_t cchToAppend, __out_opt PUNICODE_STRING RemainingString OPTIONAL, __in DWORD dwFlags ); Routine Description: This routine is a safer version of the C built-in function 'strncat', with some additional parameters and for PUNICODE_STRINGs. In addition to the functionality provided by RtlUnicodeStringCchCatStringN, this routine also returns a PUNICODE_STRING which points to the end of the destination string. The flags parameter allows additional controls. Arguments: DestinationString - pointer to the counted unicode destination string pszSrc - source string cchToAppend - maximum number of characters to append RemainingString - if RemainingString is non-null, the function will format the pointer with the remaining buffer and number of bytes left in the destination string dwFlags - controls some details of the string copy: STRSAFE_FILL_BEHIND if the function succeeds, the low byte of dwFlags will be used to fill the uninitialize part of destination buffer STRSAFE_IGNORE_NULLS do not fault if DestinationString is null and treat NULL pszSrc like empty strings (L""). This flag is useful for emulating functions like lstrcpy STRSAFE_FILL_ON_FAILURE if the function fails, the low byte of dwFlags will be used to fill all of the destination buffer. This will overwrite any truncated string returned when the failure is STATUS_BUFFER_OVERFLOW STRSAFE_ZERO_LENGTH_ON_FAILURE if the function fails, the destination Length will be set to zero. This will overwrite any truncated string returned when the failure is STATUS_BUFFER_OVERFLOW. STRSAFE_NO_TRUNCATION if the function returns STATUS_BUFFER_OVERFLOW, pszDest will not contain a truncated string, it will remain unchanged. Notes: Behavior is undefined if source and destination strings overlap. DestinationString and pszSrc should not be NULL unless the STRSAFE_IGNORE_NULLS flag is specified. If STRSAFE_IGNORE_NULLS is passed, both DestinationString and pszSrc may be NULL. An error may still be returned even though NULLS are ignored due to insufficient space. Return Value: STATUS_SUCCESS - if all of pszSrc or the first cchToAppend characters were concatenated to DestinationString 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 operation failed due to insufficient space. When this error occurs, the destination buffer is modified to contain a truncated version of the ideal result. 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 RtlUnicodeStringCchCatStringNEx( __inout PUNICODE_STRING DestinationString, __in NTSTRSAFE_PCWSTR pszSrc, __in size_t cchToAppend, __out_opt PUNICODE_STRING RemainingString, __in DWORD dwFlags) { NTSTATUS status; wchar_t* pszDest; size_t cchDest; size_t cchDestLength; status = RtlUnicodeStringValidateDestWorker(DestinationString, &pszDest, &cchDest, &cchDestLength, NTSTRSAFE_UNICODE_STRING_MAX_CCH, dwFlags); if (NT_SUCCESS(status)) { wchar_t* pszDestEnd = pszDest + cchDestLength; size_t cchRemaining = cchDest - cchDestLength; size_t cchNewDestLength = cchDestLength; status = RtlStringExValidateSrcW(&pszSrc, &cchToAppend, NTSTRSAFE_UNICODE_STRING_MAX_CCH, dwFlags); if (NT_SUCCESS(status)) { if (dwFlags & (~STRSAFE_UNICODE_STRING_VALID_FLAGS)) { status = STATUS_INVALID_PARAMETER; } else if (cchRemaining == 0) { // only fail if there was actually src data to append if ((cchToAppend != 0) && (*pszSrc != L'\0')) { if (pszDest == NULL) { status = STATUS_INVALID_PARAMETER; } else { status = STATUS_BUFFER_OVERFLOW; } } } else { size_t cchCopied = 0; status = RtlWideCharArrayCopyStringWorker(pszDestEnd, cchRemaining, &cchCopied, pszSrc, cchToAppend); pszDestEnd = pszDestEnd + cchCopied; cchRemaining = cchRemaining - cchCopied; cchNewDestLength = cchDestLength + cchCopied; if (NT_SUCCESS(status) && (dwFlags & STRSAFE_FILL_BEHIND) && (cchRemaining != 0)) { // handle the STRSAFE_FILL_BEHIND flag RtlUnicodeStringExHandleFill(pszDestEnd, cchRemaining, dwFlags); } } } if (!NT_SUCCESS(status) && (dwFlags & (STRSAFE_NO_TRUNCATION | STRSAFE_FILL_ON_FAILURE | STRSAFE_ZERO_LENGTH_ON_FAILURE)) && (cchDest != 0)) { // handle the STRSAFE_NO_TRUNCATION, STRSAFE_FILL_ON_FAILURE, and STRSAFE_ZERO_LENGTH_ON_FAILURE flags RtlUnicodeStringExHandleOtherFlags(pszDest, cchDest, cchDestLength, &cchNewDestLength, &pszDestEnd, &cchRemaining, dwFlags); } if (DestinationString) { // safe to multiply cchNewDestLength * sizeof(wchar_t) since cchDest < NTSTRSAFE_UNICODE_STRING_MAX_CCH and sizeof(wchar_t) is 2 DestinationString->Length = (USHORT)(cchNewDestLength * sizeof(wchar_t)); } if (NT_SUCCESS(status) || (status == STATUS_BUFFER_OVERFLOW)) { if (RemainingString) { RemainingString->Length = 0; // safe to multiply cchRemaining * sizeof(wchar_t) since cchRemaining < NTSTRSAFE_UNICODE_STRING_MAX_CCH and sizeof(wchar_t) is 2 RemainingString->MaximumLength = (USHORT)(cchRemaining * sizeof(wchar_t)); RemainingString->Buffer = pszDestEnd; } } } return status; } #endif // !NTSTRSAFE_NO_CCH_FUNCTIONS #ifndef NTSTRSAFE_NO_CB_FUNCTIONS /*++ NTSTATUS RtlUnicodeStringCbCatStringNEx( __inout PUNICODE_STRING DestinationString OPTIONAL, __in LPCTSTR pszSrc OPTIONAL, __in size_t cbToAppend, __out_opt PUNICODE_STRING RemainingString OPTIONAL, __in DWORD dwFlags ); Routine Description: This routine is a safer version of the C built-in function 'strncat', with some additional parameters and for PUNICODE_STRINGs. In addition to the functionality provided by RtlUnicodeStringCbCatStringN, this routine also returns a PUNICODE_STRING which points to the end of the destination string. The flags parameter allows additional controls. Arguments: DestinationString - pointer to the counted unicode destination string pszSrc - source string cbToAppend - maximum number of bytes to append RemainingString - if RemainingString is non-null, the function will format the pointer with the remaining buffer and number of bytes left in the destination string dwFlags - controls some details of the string copy: STRSAFE_FILL_BEHIND if the function succeeds, the low byte of dwFlags will be used to fill the uninitialize part of destination buffer STRSAFE_IGNORE_NULLS do not fault if DestinationString is null and treat NULL pszSrc like empty strings (L""). This flag is useful for emulating functions like lstrcpy STRSAFE_FILL_ON_FAILURE if the function fails, the low byte of dwFlags will be used to fill all of the destination buffer. This will overwrite any truncated string returned when the failure is STATUS_BUFFER_OVERFLOW STRSAFE_ZERO_LENGTH_ON_FAILURE if the function fails, the destination Length will be set to zero. This will overwrite any truncated string returned when the failure is STATUS_BUFFER_OVERFLOW. STRSAFE_NO_TRUNCATION if the function returns STATUS_BUFFER_OVERFLOW, pszDest will not contain a truncated string, it will remain unchanged. Notes: Behavior is undefined if source and destination strings overlap. DestinationString and pszSrc should not be NULL unless the STRSAFE_IGNORE_NULLS flag is specified. If STRSAFE_IGNORE_NULLS is passed, both DestinationString and pszSrc may be NULL. An error may still be returned even though NULLS are ignored due to insufficient space. Return Value: STATUS_SUCCESS - if all of pszSrc or the first cbToAppend bytes were concatenated to pszDest 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 operation failed due to insufficient space. When this error occurs, the destination buffer is modified to contain a truncated version of the ideal result. 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 RtlUnicodeStringCbCatStringNEx( __inout PUNICODE_STRING DestinationString, __in NTSTRSAFE_PCWSTR pszSrc, __in size_t cbToAppend, __out_opt PUNICODE_STRING RemainingString, __in DWORD dwFlags) { NTSTATUS status; wchar_t* pszDest; size_t cchDest; size_t cchDestLength; status = RtlUnicodeStringValidateDestWorker(DestinationString, &pszDest, &cchDest, &cchDestLength, NTSTRSAFE_UNICODE_STRING_MAX_CCH, dwFlags); if (NT_SUCCESS(status)) { wchar_t* pszDestEnd = pszDest + cchDestLength; size_t cchRemaining = cchDest - cchDestLength; size_t cchNewDestLength = cchDestLength; size_t cchToAppend = cbToAppend / sizeof(wchar_t); status = RtlStringExValidateSrcW(&pszSrc, &cchToAppend, NTSTRSAFE_UNICODE_STRING_MAX_CCH, dwFlags); if (NT_SUCCESS(status)) { if (dwFlags & (~STRSAFE_UNICODE_STRING_VALID_FLAGS)) { status = STATUS_INVALID_PARAMETER; } else if (cchRemaining == 0) { // only fail if there was actually src data to append if ((cchToAppend != 0) && (*pszSrc != L'\0')) { if (pszDest == NULL) { status = STATUS_INVALID_PARAMETER; } else { status = STATUS_BUFFER_OVERFLOW; } } } else { size_t cchCopied = 0; status = RtlWideCharArrayCopyStringWorker(pszDestEnd, cchRemaining, &cchCopied, pszSrc, cchToAppend); pszDestEnd = pszDestEnd + cchCopied; cchRemaining = cchRemaining - cchCopied; cchNewDestLength = cchDestLength + cchCopied; if (NT_SUCCESS(status) && (dwFlags & STRSAFE_FILL_BEHIND) && (cchRemaining != 0)) { // handle the STRSAFE_FILL_BEHIND flag RtlUnicodeStringExHandleFill(pszDestEnd, cchRemaining, dwFlags); } } } if (!NT_SUCCESS(status) && (dwFlags & (STRSAFE_NO_TRUNCATION | STRSAFE_FILL_ON_FAILURE | STRSAFE_ZERO_LENGTH_ON_FAILURE)) && (cchDest != 0)) { // handle the STRSAFE_NO_TRUNCATION, STRSAFE_FILL_ON_FAILURE, and STRSAFE_ZERO_LENGTH_ON_FAILURE flags RtlUnicodeStringExHandleOtherFlags(pszDest, cchDest, cchDestLength, &cchNewDestLength, &pszDestEnd, &cchRemaining, dwFlags); } if (DestinationString) { // safe to multiply cchNewDestLength * sizeof(wchar_t) since cchDest < NTSTRSAFE_UNICODE_STRING_MAX_CCH and sizeof(wchar_t) is 2 DestinationString->Length = (USHORT)(cchNewDestLength * sizeof(wchar_t)); } if (NT_SUCCESS(status) || (status == STATUS_BUFFER_OVERFLOW)) { if (RemainingString) { RemainingString->Length = 0; // safe to multiply cchRemaining * sizeof(wchar_t) since cchRemaining < NTSTRSAFE_UNICODE_STRING_MAX_CCH and sizeof(wchar_t) is 2 RemainingString->MaximumLength = (USHORT)(cchRemaining * sizeof(wchar_t)); RemainingString->Buffer = pszDestEnd; } } } return status; } #endif // !NTSTRSAFE_NO_CB_FUNCTIONS #ifndef NTSTRSAFE_NO_CCH_FUNCTIONS /*++ NTSTATUS RtlUnicodeStringCchCatNEx( __inout PUNICODE_STRING DestinationString OPTIONAL, __in PCUNICODE_STRING SourceString OPTIONAL, __in size_t cchToAppend, __out_opt PUNICODE_STRING RemainingString OPTIONAL, __in DWORD dwFlags ); Routine Description: This routine is a safer version of the C built-in function 'strncat', with some additional parameters and for PUNICODE_STRINGs. In addition to the functionality provided by RtlUnicodeStringCchCatN, this routine also returns a PUNICODE_STRING which points to the end of the destination string. The flags parameter allows additional controls. Arguments: DestinationString - pointer to the counted unicode destination string SourceString - pointer to the counted unicode source string cchToAppend - maximum number of characters to append RemainingString - if RemainingString is non-null, the function will format the pointer with the remaining buffer and number of bytes left in the destination string dwFlags - controls some details of the string copy: STRSAFE_FILL_BEHIND if the function succeeds, the low byte of dwFlags will be used to fill the uninitialize part of destination buffer STRSAFE_IGNORE_NULLS do not fault if DestinationString is null and treat NULL SourceString like empty strings (L""). This flag is useful for emulating functions like lstrcpy STRSAFE_FILL_ON_FAILURE if the function fails, the low byte of dwFlags will be used to fill all of the destination buffer. This will overwrite any truncated string returned when the failure is STATUS_BUFFER_OVERFLOW STRSAFE_ZERO_LENGTH_ON_FAILURE if the function fails, the destination Length will be set to zero. This will overwrite any truncated string returned when the failure is STATUS_BUFFER_OVERFLOW. STRSAFE_NO_TRUNCATION if the function returns STATUS_BUFFER_OVERFLOW, pszDest will not contain a truncated string, it will remain unchanged. Notes: Behavior is undefined if source and destination strings overlap. DestinationString and SourceString should not be NULL unless the STRSAFE_IGNORE_NULLS flag is specified. If STRSAFE_IGNORE_NULLS is passed, both DestinationString and SourceString may be NULL. An error may still be returned even though NULLS are ignored due to insufficient space. Return Value: STATUS_SUCCESS - if all of SourceString or the first cchToAppend characters were concatenated to DestinationString 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 operation failed due to insufficient space. When this error occurs, the destination buffer is modified to contain a truncated version of the ideal result. 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 RtlUnicodeStringCchCatNEx( __inout PUNICODE_STRING DestinationString, __in PCUNICODE_STRING SourceString, __in size_t cchToAppend, __out_opt PUNICODE_STRING RemainingString, __in DWORD dwFlags) { NTSTATUS status; wchar_t* pszDest; size_t cchDest; size_t cchDestLength; status = RtlUnicodeStringValidateDestWorker(DestinationString, &pszDest, &cchDest, &cchDestLength, NTSTRSAFE_UNICODE_STRING_MAX_CCH, dwFlags); if (NT_SUCCESS(status)) { wchar_t* pszSrc; size_t cchSrcLength; wchar_t* pszDestEnd = pszDest + cchDestLength; size_t cchRemaining = cchDest - cchDestLength; size_t cchNewDestLength = cchDestLength; status = RtlUnicodeStringValidateSrcWorker(SourceString, &pszSrc, &cchSrcLength, NTSTRSAFE_UNICODE_STRING_MAX_CCH, dwFlags); if (NT_SUCCESS(status)) { if (cchToAppend > NTSTRSAFE_UNICODE_STRING_MAX_CCH) { status = STATUS_INVALID_PARAMETER; } else { if (cchSrcLength < cchToAppend) { cchToAppend = cchSrcLength; } if (dwFlags & (~STRSAFE_UNICODE_STRING_VALID_FLAGS)) { status = STATUS_INVALID_PARAMETER; } else if (cchRemaining == 0) { // only fail if there was actually src data to append if (cchToAppend != 0) { if (pszDest == NULL) { status = STATUS_INVALID_PARAMETER; } else { status = STATUS_BUFFER_OVERFLOW; } } } else { size_t cchCopied = 0; status = RtlWideCharArrayCopyStringWorker(pszDestEnd, cchRemaining, &cchCopied, pszSrc, cchToAppend); pszDestEnd = pszDestEnd + cchCopied; cchRemaining = cchRemaining - cchCopied; cchNewDestLength = cchDestLength + cchCopied; if (NT_SUCCESS(status) && (dwFlags & STRSAFE_FILL_BEHIND) && (cchRemaining != 0)) { // handle the STRSAFE_FILL_BEHIND flag RtlUnicodeStringExHandleFill(pszDestEnd, cchRemaining, dwFlags); } } } } if (!NT_SUCCESS(status) && (dwFlags & (STRSAFE_NO_TRUNCATION | STRSAFE_FILL_ON_FAILURE | STRSAFE_ZERO_LENGTH_ON_FAILURE)) && (cchDest != 0)) { // handle the STRSAFE_NO_TRUNCATION, STRSAFE_FILL_ON_FAILURE, and STRSAFE_ZERO_LENGTH_ON_FAILURE flags RtlUnicodeStringExHandleOtherFlags(pszDest, cchDest, cchDestLength, &cchNewDestLength, &pszDestEnd, &cchRemaining, dwFlags); } if (DestinationString) { // safe to multiply cchNewDestLength * sizeof(wchar_t) since cchDest < NTSTRSAFE_UNICODE_STRING_MAX_CCH and sizeof(wchar_t) is 2 DestinationString->Length = (USHORT)(cchNewDestLength * sizeof(wchar_t)); } if (NT_SUCCESS(status) || (status == STATUS_BUFFER_OVERFLOW)) { if (RemainingString) { RemainingString->Length = 0; // safe to multiply cchRemaining * sizeof(wchar_t) since cchRemaining < NTSTRSAFE_UNICODE_STRING_MAX_CCH and sizeof(wchar_t) is 2 RemainingString->MaximumLength = (USHORT)(cchRemaining * sizeof(wchar_t)); RemainingString->Buffer = pszDestEnd; } } } return status; } #endif // !NTSTRSAFE_NO_CCH_FUNCTIONS #ifndef NTSTRSAFE_NO_CB_FUNCTIONS /*++ NTSTATUS RtlUnicodeStringCbCatNEx( __inout PUNICODE_STRING DestinationString OPTIONAL, __in PCUNICODE_STRING SourceString OPTIONAL, __in size_t cbToAppend, __out_opt PUNICODE_STRING RemainingString OPTIONAL, __in DWORD dwFlags ); Routine Description: This routine is a safer version of the C built-in function 'strncat', with some additional parameters and for PUNICODE_STRINGs. In addition to the functionality provided by RtlUnicodeStringCbCatN, this routine also returns a PUNICODE_STRING which points to the end of the destination string. The flags parameter allows additional controls. Arguments: DestinationString - pointer to the counted unicode destination string SourceString - pointer to the counted unicode source string cbToAppend - maximum number of bytes to append RemainingString - if RemainingString is non-null, the function will format the pointer with the remaining buffer and number of bytes left in the destination string dwFlags - controls some details of the string copy: STRSAFE_FILL_BEHIND if the function succeeds, the low byte of dwFlags will be used to fill the uninitialize part of destination buffer STRSAFE_IGNORE_NULLS do not fault if DestinationString is null and treat NULL SourceString like empty strings (L""). This flag is useful for emulating functions like lstrcpy STRSAFE_FILL_ON_FAILURE if the function fails, the low byte of dwFlags will be used to fill all of the destination buffer. This will overwrite any truncated string returned when the failure is STATUS_BUFFER_OVERFLOW STRSAFE_ZERO_LENGTH_ON_FAILURE if the function fails, the destination Length will be set to zero. This will overwrite any truncated string returned when the failure is STATUS_BUFFER_OVERFLOW. STRSAFE_NO_TRUNCATION if the function returns STATUS_BUFFER_OVERFLOW, pszDest will not contain a truncated string, it will remain unchanged. Notes: Behavior is undefined if source and destination strings overlap. DestinationString and SourceString should not be NULL unless the STRSAFE_IGNORE_NULLS flag is specified. If STRSAFE_IGNORE_NULLS is passed, both DestinationString and SourceString may be NULL. An error may still be returned even though NULLS are ignored due to insufficient space. Return Value: STATUS_SUCCESS - if all of SourceString or the first cbToAppend bytes were concatenated to DestinationString 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 operation failed due to insufficient space. When this error occurs, the destination buffer is modified to contain a truncated version of the ideal result. 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 RtlUnicodeStringCbCatNEx( __inout PUNICODE_STRING DestinationString, __in PCUNICODE_STRING SourceString, __in size_t cbToAppend, __out_opt PUNICODE_STRING RemainingString, __in DWORD dwFlags) { NTSTATUS status; wchar_t* pszDest; size_t cchDest; size_t cchDestLength; status = RtlUnicodeStringValidateDestWorker(DestinationString, &pszDest, &cchDest, &cchDestLength, NTSTRSAFE_UNICODE_STRING_MAX_CCH, dwFlags); if (NT_SUCCESS(status)) { wchar_t* pszSrc; size_t cchSrcLength; wchar_t* pszDestEnd = pszDest + cchDestLength; size_t cchRemaining = cchDest - cchDestLength; size_t cchNewDestLength = cchDestLength; status = RtlUnicodeStringValidateSrcWorker(SourceString, &pszSrc, &cchSrcLength, NTSTRSAFE_UNICODE_STRING_MAX_CCH, dwFlags); if (NT_SUCCESS(status)) { size_t cchToAppend = cbToAppend / sizeof(wchar_t); if (cchToAppend > NTSTRSAFE_UNICODE_STRING_MAX_CCH) { status = STATUS_INVALID_PARAMETER; } else { if (cchSrcLength < cchToAppend) { cchToAppend = cchSrcLength; } if (dwFlags & (~STRSAFE_UNICODE_STRING_VALID_FLAGS)) { status = STATUS_INVALID_PARAMETER; } else if (cchRemaining == 0) { // only fail if there was actually src data to append if (cchToAppend != 0) { if (pszDest == NULL) { status = STATUS_INVALID_PARAMETER; } else { status = STATUS_BUFFER_OVERFLOW; } } } else { size_t cchCopied = 0; status = RtlWideCharArrayCopyWorker(pszDestEnd, cchRemaining, &cchCopied, pszSrc, cchToAppend); pszDestEnd = pszDestEnd + cchCopied; cchRemaining = cchRemaining - cchCopied; cchNewDestLength = cchDestLength + cchCopied; if (NT_SUCCESS(status) && (dwFlags & STRSAFE_FILL_BEHIND) && (cchRemaining != 0)) { // handle the STRSAFE_FILL_BEHIND flag RtlUnicodeStringExHandleFill(pszDestEnd, cchRemaining, dwFlags); } } } } if (!NT_SUCCESS(status) && (dwFlags & (STRSAFE_NO_TRUNCATION | STRSAFE_FILL_ON_FAILURE | STRSAFE_ZERO_LENGTH_ON_FAILURE)) && (cchDest != 0)) { // handle the STRSAFE_NO_TRUNCATION, STRSAFE_FILL_ON_FAILURE, and STRSAFE_ZERO_LENGTH_ON_FAILURE flags RtlUnicodeStringExHandleOtherFlags(pszDest, cchDest, cchDestLength, &cchNewDestLength, &pszDestEnd, &cchRemaining, dwFlags); } if (DestinationString) { // safe to multiply cchNewDestLength * sizeof(wchar_t) since cchDest < NTSTRSAFE_UNICODE_STRING_MAX_CCH and sizeof(wchar_t) is 2 DestinationString->Length = (USHORT)(cchNewDestLength * sizeof(wchar_t)); } if (NT_SUCCESS(status) || (status == STATUS_BUFFER_OVERFLOW)) { if (RemainingString) { RemainingString->Length = 0; // safe to multiply cchRemaining * sizeof(wchar_t) since cchRemaining < NTSTRSAFE_UNICODE_STRING_MAX_CCH and sizeof(wchar_t) is 2 RemainingString->MaximumLength = (USHORT)(cchRemaining * sizeof(wchar_t)); RemainingString->Buffer = pszDestEnd; } } } return status; } #endif // !NTSTRSAFE_NO_CB_FUNCTIONS /*++ NTSTATUS RtlUnicodeStringVPrintf( __out PUNICODE_STRING DestinationString, __in __format_string PCWSTR pszFormat, __in va_list argList ); Routine Description: This routine is a safer version of the C built-in function 'vsprintf' for PUNICODE_STRINGs. This function returns an NTSTATUS value, and not a pointer. It returns STATUS_SUCCESS if the string was printed without truncation, otherwise it will return a failure code. In failure cases it will return a truncated version of the ideal result. Arguments: DestinationString - pointer to the counted unicode destination string pszFormat - format string which must be null terminated argList - va_list from the variable arguments according to the stdarg.h convention Notes: Behavior is undefined if destination, format strings or any arguments strings overlap. DestinationString and pszFormat should not be NULL. See RtlUnicodeStringVPrintfEx if you require the handling of NULL values. Return Value: STATUS_SUCCESS - if there was sufficient space in the dest buffer for the resultant string 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 print operation failed due to insufficient space. When this error occurs, the destination buffer is modified to contain a truncated version of the ideal result. 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 RtlUnicodeStringVPrintf( __out PUNICODE_STRING DestinationString, __in __format_string NTSTRSAFE_PCWSTR pszFormat, __in va_list argList) { NTSTATUS status; wchar_t* pszDest; size_t cchDest; status = RtlUnicodeStringValidateDestWorker(DestinationString, &pszDest, &cchDest, NULL, NTSTRSAFE_UNICODE_STRING_MAX_CCH, 0); if (NT_SUCCESS(status)) { size_t cchNewDestLength = 0; status = RtlWideCharArrayVPrintfWorker(pszDest, cchDest, &cchNewDestLength, pszFormat, argList); // safe to multiply cchNewDestLength * sizeof(wchar_t) since cchDest < NTSTRSAFE_UNICODE_STRING_MAX_CCH and sizeof(wchar_t) is 2 DestinationString->Length = (USHORT)(cchNewDestLength * sizeof(wchar_t)); } return status; } /*++ NTSTATUS RtlUnicodeStringVPrintfEx( __out PUNICODE_STRING DestinationString OPTIONAL, __out_opt PUNICODE_STRING RemainingString OPTIONAL, __in DWORD dwFlags, __in __format_string PCWSTR pszFormat OPTIONAL, __in va_list argList ); Routine Description: This routine is a safer version of the C built-in function 'vsprintf' with some additional parameters for PUNICODE_STRING. In addition to the functionality provided by RtlUnicodeStringVPrintf, this routine also returns a PUNICODE_STRING which points to the end of the destination string. The flags parameter allows additional controls. Arguments: DestinationString - pointer to the counted unicode destination string RemainingString - if RemainingString is non-null, the function will format the pointer with the remaining buffer and number of bytes left in the destination string dwFlags - controls some details of the string copy: STRSAFE_FILL_BEHIND if the function succeeds, the low byte of dwFlags will be used to fill the uninitialize part of destination buffer STRSAFE_IGNORE_NULLS do not fault if DestinationString is null and treat NULL pszFormat like empty strings (L""). STRSAFE_FILL_ON_FAILURE if the function fails, the low byte of dwFlags will be used to fill all of the destination buffer. This will overwrite any truncated string returned when the failure is STATUS_BUFFER_OVERFLOW STRSAFE_NO_TRUNCATION / STRSAFE_ZERO_LENGTH_ON_FAILURE if the function fails, the destination Length will be set to zero. This will overwrite any truncated string returned when the failure is STATUS_BUFFER_OVERFLOW. pszFormat - format string which must be null terminated argList - va_list from the variable arguments according to the stdarg.h convention Notes: Behavior is undefined if destination, format strings or any arguments strings overlap. DestinationString and pszFormat should not be NULL unless the STRSAFE_IGNORE_NULLS flag is specified. If STRSAFE_IGNORE_NULLS is passed, both DestinationString and pszFormat may be NULL. An error may still be returned even though NULLS are ignored due to insufficient space. Return Value: STATUS_SUCCESS - if there was sufficient space in the dest buffer for the resultant string 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 print operation failed due to insufficient space. When this error occurs, the destination buffer is modified to contain a truncated version of the ideal result. 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 RtlUnicodeStringVPrintfEx( __out PUNICODE_STRING DestinationString, __out_opt PUNICODE_STRING RemainingString, __in DWORD dwFlags, __in __format_string NTSTRSAFE_PCWSTR pszFormat, __in va_list argList) { NTSTATUS status; wchar_t* pszDest; size_t cchDest; status = RtlUnicodeStringValidateDestWorker(DestinationString, &pszDest, &cchDest, NULL, NTSTRSAFE_UNICODE_STRING_MAX_CCH, dwFlags); if (NT_SUCCESS(status)) { wchar_t* pszDestEnd = pszDest; size_t cchRemaining = cchDest; size_t cchNewDestLength = 0; status = RtlStringExValidateSrcW(&pszFormat, NULL, NTSTRSAFE_UNICODE_STRING_MAX_CCH, dwFlags); if (NT_SUCCESS(status)) { if (dwFlags & (~STRSAFE_UNICODE_STRING_VALID_FLAGS)) { status = STATUS_INVALID_PARAMETER; } else if (cchDest == 0) { // only fail if there was actually a non-empty format string if (*pszFormat != L'\0') { if (pszDest == NULL) { status = STATUS_INVALID_PARAMETER; } else { status = STATUS_BUFFER_OVERFLOW; } } } else { status = RtlWideCharArrayVPrintfWorker(pszDest, cchDest, &cchNewDestLength, pszFormat, argList); pszDestEnd = pszDest + cchNewDestLength; cchRemaining = cchDest - cchNewDestLength; if (NT_SUCCESS(status) && (dwFlags & STRSAFE_FILL_BEHIND) && (cchRemaining != 0)) { // handle the STRSAFE_FILL_BEHIND flag RtlUnicodeStringExHandleFill(pszDestEnd, cchRemaining, dwFlags); } } } if (!NT_SUCCESS(status) && (dwFlags & (STRSAFE_NO_TRUNCATION | STRSAFE_FILL_ON_FAILURE | STRSAFE_ZERO_LENGTH_ON_FAILURE)) && (cchDest != 0)) { // handle the STRSAFE_NO_TRUNCATION, STRSAFE_FILL_ON_FAILURE, and STRSAFE_ZERO_LENGTH_ON_FAILURE flags RtlUnicodeStringExHandleOtherFlags(pszDest, cchDest, 0, &cchNewDestLength, &pszDestEnd, &cchRemaining, dwFlags); } if (DestinationString) { // safe to multiply cchNewDestLength * sizeof(wchar_t) since cchDest < NTSTRSAFE_UNICODE_STRING_MAX_CCH and sizeof(wchar_t) is 2 DestinationString->Length = (USHORT)(cchNewDestLength * sizeof(wchar_t)); } if (NT_SUCCESS(status) || (status == STATUS_BUFFER_OVERFLOW)) { if (RemainingString) { RemainingString->Length = 0; // safe to multiply cchRemaining * sizeof(wchar_t) since cchRemaining < NTSTRSAFE_UNICODE_STRING_MAX_CCH and sizeof(wchar_t) is 2 RemainingString->MaximumLength = (USHORT)(cchRemaining * sizeof(wchar_t)); RemainingString->Buffer = pszDestEnd; } } } return status; } #ifndef _M_CEE_PURE /*++ NTSTATUS RtlUnicodeStringPrintf( __out PUNICODE_STRING DestinationString, __in __format_string PCWSTR pszFormat, ... ); Routine Description: This routine is a safer version of the C built-in function 'sprintf' for PUNICODE_STRINGs. This function returns an NTSTATUS value, and not a pointer. It returns STATUS_SUCCESS if the string was printed without truncation, otherwise it will return a failure code. In failure cases it will return a truncated version of the ideal result. Arguments: DestinationString - pointer to the counted unicode destination string pszFormat - format string which must be null terminated ... - additional parameters to be formatted according to the format string Notes: Behavior is undefined if destination, format strings or any arguments strings overlap. DestinationString and pszFormat should not be NULL. See RtlUnicodeStringPrintfEx if you require the handling of NULL values. Return Value: STATUS_SUCCESS - if there was sufficient space in the dest buffer for the resultant string 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 print operation failed due to insufficient space. When this error occurs, the destination buffer is modified to contain a truncated version of the ideal result. 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 RtlUnicodeStringPrintf( __out PUNICODE_STRING DestinationString, __in __format_string NTSTRSAFE_PCWSTR pszFormat, ...) { NTSTATUS status; wchar_t* pszDest; size_t cchDest; status = RtlUnicodeStringValidateDestWorker(DestinationString, &pszDest, &cchDest, NULL, NTSTRSAFE_UNICODE_STRING_MAX_CCH, 0); if (NT_SUCCESS(status)) { va_list argList; size_t cchNewDestLength = 0; va_start(argList, pszFormat); status = RtlWideCharArrayVPrintfWorker(pszDest, cchDest, &cchNewDestLength, pszFormat, argList); va_end(argList); // safe to multiply cchNewDestLength * sizeof(wchar_t) since cchDest < NTSTRSAFE_UNICODE_STRING_MAX_CCH and sizeof(wchar_t) is 2 DestinationString->Length = (USHORT)(cchNewDestLength * sizeof(wchar_t)); } return status; } /*++ NTSTATUS RtlUnicodeStringPrintfEx( __out PUNICODE_STRING DestinationString OPTIONAL, __out_opt PUNICODE_STRING RemainingString OPTIONAL, __in DWORD dwFlags, __in __format_string PCWSTR pszFormat OPTIONAL, ... ); Routine Description: This routine is a safer version of the C built-in function 'sprintf' with some additional parameters for PUNICODE_STRINGs. In addition to the functionality provided by RtlUnicodeStringPrintf, this routine also returns a PUNICODE_STRING which points to the end of the destination string. The flags parameter allows additional controls. Arguments: DestinationString - pointer to the counted unicode destination string RemainingString - if RemainingString is non-null, the function will format the pointer with the remaining buffer and number of bytes left in the destination string dwFlags - controls some details of the string copy: STRSAFE_FILL_BEHIND if the function succeeds, the low byte of dwFlags will be used to fill the uninitialize part of destination buffer STRSAFE_IGNORE_NULLS do not fault if DestinationString is null and treat NULL pszFormat like empty strings (L""). STRSAFE_FILL_ON_FAILURE if the function fails, the low byte of dwFlags will be used to fill all of the destination buffer. This will overwrite any truncated string returned when the failure is STATUS_BUFFER_OVERFLOW STRSAFE_NO_TRUNCATION / STRSAFE_ZERO_LENGTH_ON_FAILURE if the function fails, the destination Length will be set to zero. This will overwrite any truncated string returned when the failure is STATUS_BUFFER_OVERFLOW. pszFormat - format string which must be null terminated ... - additional parameters to be formatted according to the format string Notes: Behavior is undefined if destination, format strings or any arguments strings overlap. DestinationString and pszFormat should not be NULL unless the STRSAFE_IGNORE_NULLS flag is specified. If STRSAFE_IGNORE_NULLS is passed, both DestinationString and pszFormat may be NULL. An error may still be returned even though NULLS are ignored due to insufficient space. Return Value: STATUS_SUCCESS - if there was sufficient space in the dest buffer for the resultant string 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 print operation failed due to insufficient space. When this error occurs, the destination buffer is modified to contain a truncated version of the ideal result. 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 RtlUnicodeStringPrintfEx( __out PUNICODE_STRING DestinationString, __out_opt PUNICODE_STRING RemainingString, __in DWORD dwFlags, __in __format_string NTSTRSAFE_PCWSTR pszFormat, ...) { NTSTATUS status; wchar_t* pszDest; size_t cchDest; status = RtlUnicodeStringValidateDestWorker(DestinationString, &pszDest, &cchDest, NULL, NTSTRSAFE_UNICODE_STRING_MAX_CCH, dwFlags); if (NT_SUCCESS(status)) { wchar_t* pszDestEnd = pszDest; size_t cchRemaining = cchDest; size_t cchNewDestLength = 0; status = RtlStringExValidateSrcW(&pszFormat, NULL, NTSTRSAFE_UNICODE_STRING_MAX_CCH, dwFlags); if (NT_SUCCESS(status)) { if (dwFlags & (~STRSAFE_UNICODE_STRING_VALID_FLAGS)) { status = STATUS_INVALID_PARAMETER; } else if (cchDest == 0) { // only fail if there was actually a non-empty format string if (*pszFormat != L'\0') { if (pszDest == NULL) { status = STATUS_INVALID_PARAMETER; } else { status = STATUS_BUFFER_OVERFLOW; } } } else { va_list argList; va_start(argList, pszFormat); status = RtlWideCharArrayVPrintfWorker(pszDest, cchDest, &cchNewDestLength, pszFormat, argList); va_end(argList); pszDestEnd = pszDest + cchNewDestLength; cchRemaining = cchDest - cchNewDestLength; if (NT_SUCCESS(status) && (dwFlags & STRSAFE_FILL_BEHIND) && (cchRemaining != 0)) { // handle the STRSAFE_FILL_BEHIND flag RtlUnicodeStringExHandleFill(pszDestEnd, cchRemaining, dwFlags); } } } if (!NT_SUCCESS(status) && (dwFlags & (STRSAFE_NO_TRUNCATION | STRSAFE_FILL_ON_FAILURE | STRSAFE_ZERO_LENGTH_ON_FAILURE)) && (cchDest != 0)) { // handle the STRSAFE_NO_TRUNCATION, STRSAFE_FILL_ON_FAILURE, and STRSAFE_ZERO_LENGTH_ON_FAILURE flags RtlUnicodeStringExHandleOtherFlags(pszDest, cchDest, 0, &cchNewDestLength, &pszDestEnd, &cchRemaining, dwFlags); } if (DestinationString) { // safe to multiply cchNewDestLength * sizeof(wchar_t) since cchDest < NTSTRSAFE_UNICODE_STRING_MAX_CCH and sizeof(wchar_t) is 2 DestinationString->Length = (USHORT)(cchNewDestLength * sizeof(wchar_t)); } if (NT_SUCCESS(status) || (status == STATUS_BUFFER_OVERFLOW)) { if (RemainingString) { RemainingString->Length = 0; // safe to multiply cchRemaining * sizeof(wchar_t) since cchRemaining < NTSTRSAFE_UNICODE_STRING_MAX_CCH and sizeof(wchar_t) is 2 RemainingString->MaximumLength = (USHORT)(cchRemaining * sizeof(wchar_t)); RemainingString->Buffer = pszDestEnd; } } } return status; } #endif // !_M_CEE_PURE #endif // !NTSTRSAFE_NO_UNICODE_STRING_FUNCTIONS #endif // !NTSTRSAFE_LIB_IMPL // Below here are the worker functions that actually do the work #if defined(NTSTRSAFE_LIB_IMPL) || !defined(NTSTRSAFE_LIB) NTSTRSAFEWORKERDDI RtlStringLengthWorkerA( __in STRSAFE_PCNZCH psz, __in __in_range(<=, NTSTRSAFE_MAX_CCH) size_t cchMax, __out_opt __deref_out_range(<, cchMax) size_t* pcchLength) { NTSTATUS status = STATUS_SUCCESS; size_t cchOriginalMax = cchMax; while (cchMax && (*psz != '\0')) { psz++; cchMax--; } if (cchMax == 0) { // the string is longer than cchMax status = STATUS_INVALID_PARAMETER; } if (pcchLength) { if (NT_SUCCESS(status)) { *pcchLength = cchOriginalMax - cchMax; } else { *pcchLength = 0; } } return status; } NTSTRSAFEWORKERDDI RtlStringLengthWorkerW( __in STRSAFE_PCNZWCH psz, __in __in_range(<=, NTSTRSAFE_MAX_CCH) size_t cchMax, __out_opt __deref_out_range(<, cchMax) size_t* pcchLength) { NTSTATUS status = STATUS_SUCCESS; size_t cchOriginalMax = cchMax; while (cchMax && (*psz != L'\0')) { psz++; cchMax--; } if (cchMax == 0) { // the string is longer than cchMax status = STATUS_INVALID_PARAMETER; } if (pcchLength) { if (NT_SUCCESS(status)) { *pcchLength = cchOriginalMax - cchMax; } else { *pcchLength = 0; } } return status; } #ifdef ALIGNMENT_MACHINE NTSTRSAFEWORKERDDI RtlUnalignedStringLengthWorkerW( __in STRSAFE_PCUNZWCH psz, __in __in_range(<=, NTSTRSAFE_MAX_CCH) size_t cchMax, __out_opt __deref_out_range(<, cchMax) size_t* pcchLength) { NTSTATUS status = STATUS_SUCCESS; size_t cchOriginalMax = cchMax; while (cchMax && (*psz != L'\0')) { psz++; cchMax--; } if (cchMax == 0) { // the string is longer than cchMax status = STATUS_INVALID_PARAMETER; } if (pcchLength) { if (NT_SUCCESS(status)) { *pcchLength = cchOriginalMax - cchMax; } else { *pcchLength = 0; } } return status; } #endif // ALIGNMENT_MACHINE // Intentionally allow null deref when STRSAFE_IGNORE_NULLS is not present. #pragma warning(push) #pragma warning(disable : __WARNING_DEREF_NULL_PTR) #pragma warning(disable : __WARNING_INVALID_PARAM_VALUE_1) #pragma warning(disable : __WARNING_RETURNING_BAD_RESULT) NTSTRSAFEWORKERDDI RtlStringExValidateSrcA( __deref_in_opt_out NTSTRSAFE_PCSTR* ppszSrc, __inout_opt __deref_out_range(<, cchMax) size_t* pcchToRead, __in const size_t cchMax, __in DWORD dwFlags) { NTSTATUS status = STATUS_SUCCESS; if (pcchToRead && (*pcchToRead >= cchMax)) { status = STATUS_INVALID_PARAMETER; } else if ((dwFlags & STRSAFE_IGNORE_NULLS) && (*ppszSrc == NULL)) { *ppszSrc = ""; if (pcchToRead) { *pcchToRead = 0; } } return status; } NTSTRSAFEWORKERDDI RtlStringExValidateSrcW( __deref_in_opt_out NTSTRSAFE_PCWSTR* ppszSrc, __inout_opt __deref_out_range(<, cchMax) size_t* pcchToRead, __in const size_t cchMax, __in DWORD dwFlags) { NTSTATUS status = STATUS_SUCCESS; if (pcchToRead && (*pcchToRead >= cchMax)) { status = STATUS_INVALID_PARAMETER; } else if ((dwFlags & STRSAFE_IGNORE_NULLS) && (*ppszSrc == NULL)) { *ppszSrc = L""; if (pcchToRead) { *pcchToRead = 0; } } return status; } #pragma warning(pop) // allow null deref #pragma warning(push) #pragma warning(disable : 4100) // Unused parameter (pszDest) NTSTRSAFEWORKERDDI RtlStringValidateDestA( __in_ecount_opt(cchDest) STRSAFE_PCNZCH pszDest, __in size_t cchDest, __in const size_t cchMax) { NTSTATUS status = STATUS_SUCCESS; if ((cchDest == 0) || (cchDest > cchMax)) { status = STATUS_INVALID_PARAMETER; } return status; } #pragma warning(pop) // Intentionally allow null deref when STRSAFE_IGNORE_NULLS is not present. #pragma warning(push) #pragma warning(disable : __WARNING_DEREF_NULL_PTR) #pragma warning(disable : __WARNING_INVALID_PARAM_VALUE_1) NTSTRSAFEWORKERDDI RtlStringValidateDestAndLengthA( __in_ecount_opt(cchDest) NTSTRSAFE_PCSTR pszDest, __in size_t cchDest, __out __deref_out_range(<, cchDest) size_t* pcchDestLength, __in const size_t cchMax) { NTSTATUS status; status = RtlStringValidateDestA(pszDest, cchDest, cchMax); if (NT_SUCCESS(status)) { status = RtlStringLengthWorkerA(pszDest, cchDest, pcchDestLength); } else { *pcchDestLength = 0; } return status; } // End intentionally allow null deref. #pragma warning(pop) #pragma warning(push) #pragma warning(disable : 4100) // Unused parameter (pszDest) NTSTRSAFEWORKERDDI RtlStringValidateDestW( __in_ecount_opt(cchDest) STRSAFE_PCNZWCH pszDest, __in size_t cchDest, __in const size_t cchMax) { NTSTATUS status = STATUS_SUCCESS; if ((cchDest == 0) || (cchDest > cchMax)) { status = STATUS_INVALID_PARAMETER; } return status; } #pragma warning(pop) // Intentionally allow null deref when STRSAFE_IGNORE_NULLS is not present. #pragma warning(push) #pragma warning(disable : __WARNING_DEREF_NULL_PTR) #pragma warning(disable : __WARNING_INVALID_PARAM_VALUE_1) NTSTRSAFEWORKERDDI RtlStringValidateDestAndLengthW( __in_ecount_opt(cchDest) NTSTRSAFE_PCWSTR pszDest, __in size_t cchDest, __out __deref_out_range(<, cchDest) size_t* pcchDestLength, __in const size_t cchMax) { NTSTATUS status; status = RtlStringValidateDestW(pszDest, cchDest, cchMax); if (NT_SUCCESS(status)) { status = RtlStringLengthWorkerW(pszDest, cchDest, pcchDestLength); } else { *pcchDestLength = 0; } return status; } // End intentionally allow null deref. #pragma warning(pop) NTSTRSAFEWORKERDDI RtlStringExValidateDestA( __in_ecount_opt(cchDest) STRSAFE_PCNZCH pszDest, __in size_t cchDest, __in const size_t cchMax, __in DWORD dwFlags) { NTSTATUS status = STATUS_SUCCESS; if (dwFlags & STRSAFE_IGNORE_NULLS) { if (((pszDest == NULL) && (cchDest != 0)) || (cchDest > cchMax)) { status = STATUS_INVALID_PARAMETER; } } else { status = RtlStringValidateDestA(pszDest, cchDest, cchMax); } return status; } // Intentionally allow null deref when STRSAFE_IGNORE_NULLS is not present. #pragma warning(push) #pragma warning(disable : __WARNING_DEREF_NULL_PTR) #pragma warning(disable : __WARNING_INVALID_PARAM_VALUE_1) NTSTRSAFEWORKERDDI RtlStringExValidateDestAndLengthA( __in_ecount_opt(cchDest) NTSTRSAFE_PCSTR pszDest, __in size_t cchDest, __out __deref_out_range(<, cchDest) size_t* pcchDestLength, __in const size_t cchMax, __in DWORD dwFlags) { NTSTATUS status; if (dwFlags & STRSAFE_IGNORE_NULLS) { status = RtlStringExValidateDestA(pszDest, cchDest, cchMax, dwFlags); if (!NT_SUCCESS(status) || (cchDest == 0)) { *pcchDestLength = 0; } else { status = RtlStringLengthWorkerA(pszDest, cchDest, pcchDestLength); } } else { status = RtlStringValidateDestAndLengthA(pszDest, cchDest, pcchDestLength, cchMax); } return status; } // End intentionally allow null deref. #pragma warning(pop) NTSTRSAFEWORKERDDI RtlStringExValidateDestW( __in_ecount_opt(cchDest) STRSAFE_PCNZWCH pszDest, __in size_t cchDest, __in const size_t cchMax, __in DWORD dwFlags) { NTSTATUS status = STATUS_SUCCESS; if (dwFlags & STRSAFE_IGNORE_NULLS) { if (((pszDest == NULL) && (cchDest != 0)) || (cchDest > cchMax)) { status = STATUS_INVALID_PARAMETER; } } else { status = RtlStringValidateDestW(pszDest, cchDest, cchMax); } return status; } // Intentionally allow null deref when STRSAFE_IGNORE_NULLS is not present. #pragma warning(push) #pragma warning(disable : __WARNING_DEREF_NULL_PTR) #pragma warning(disable : __WARNING_INVALID_PARAM_VALUE_1) NTSTRSAFEWORKERDDI RtlStringExValidateDestAndLengthW( __in_ecount_opt(cchDest) NTSTRSAFE_PCWSTR pszDest, __in size_t cchDest, __out __deref_out_range(<, cchDest) size_t* pcchDestLength, __in const size_t cchMax, __in DWORD dwFlags) { NTSTATUS status; if (dwFlags & STRSAFE_IGNORE_NULLS) { status = RtlStringExValidateDestW(pszDest, cchDest, cchMax, dwFlags); if (!NT_SUCCESS(status) || (cchDest == 0)) { *pcchDestLength = 0; } else { status = RtlStringLengthWorkerW(pszDest, cchDest, pcchDestLength); } } else { status = RtlStringValidateDestAndLengthW(pszDest, cchDest, pcchDestLength, cchMax); } return status; } // End intentionally allow null deref. #pragma warning(pop) NTSTRSAFEWORKERDDI RtlStringCopyWorkerA( __out_ecount(cchDest) NTSTRSAFE_PSTR pszDest, __in __in_range(1, NTSTRSAFE_MAX_CCH) size_t cchDest, __out_opt __deref_out_range(<=, (cchToCopy < cchDest) ? cchToCopy : cchDest - 1) size_t* pcchNewDestLength, __in_xcount(cchToCopy) STRSAFE_PCNZCH pszSrc, __in __in_range(<, NTSTRSAFE_MAX_CCH) size_t cchToCopy) { NTSTATUS status = STATUS_SUCCESS; size_t cchNewDestLength = 0; // ASSERT(cchDest != 0); while (cchDest && cchToCopy && (*pszSrc != '\0')) { *pszDest++ = *pszSrc++; cchDest--; cchToCopy--; cchNewDestLength++; } if (cchDest == 0) { // we are going to truncate pszDest pszDest--; cchNewDestLength--; status = STATUS_BUFFER_OVERFLOW; } *pszDest = '\0'; if (pcchNewDestLength) { *pcchNewDestLength = cchNewDestLength; } return status; } NTSTRSAFEWORKERDDI RtlStringCopyWorkerW( __out_ecount(cchDest) NTSTRSAFE_PWSTR pszDest, __in __in_range(1, NTSTRSAFE_MAX_CCH) size_t cchDest, __out_opt __deref_out_range(<=, (cchToCopy < cchDest) ? cchToCopy : cchDest - 1) size_t* pcchNewDestLength, __in_xcount(cchToCopy) STRSAFE_PCNZWCH pszSrc, __in __in_range(<, NTSTRSAFE_MAX_CCH) size_t cchToCopy) { NTSTATUS status = STATUS_SUCCESS; size_t cchNewDestLength = 0; // ASSERT(cchDest != 0); while (cchDest && cchToCopy && (*pszSrc != L'\0')) { *pszDest++ = *pszSrc++; cchDest--; cchToCopy--; cchNewDestLength++; } if (cchDest == 0) { // we are going to truncate pszDest pszDest--; cchNewDestLength--; status = STATUS_BUFFER_OVERFLOW; } *pszDest = L'\0'; if (pcchNewDestLength) { *pcchNewDestLength = cchNewDestLength; } return status; } NTSTRSAFEWORKERDDI RtlStringVPrintfWorkerA( __out_ecount(cchDest) NTSTRSAFE_PSTR pszDest, __in __in_range(1, NTSTRSAFE_MAX_CCH) size_t cchDest, __out_opt __deref_out_range(<=, cchDest - 1) size_t* pcchNewDestLength, __in __format_string NTSTRSAFE_PCSTR pszFormat, __in va_list argList) { NTSTATUS status = STATUS_SUCCESS; int iRet; size_t cchMax; size_t cchNewDestLength = 0; // leave the last space for the null terminator cchMax = cchDest - 1; #if (NTSTRSAFE_USE_SECURE_CRT == 1) && !defined(NTSTRSAFE_LIB_IMPL) iRet = _vsnprintf_s(pszDest, cchDest, cchMax, pszFormat, argList); #else #pragma warning(push) #pragma warning(disable: __WARNING_BANNED_API_USAGE)// "STRSAFE not included" iRet = _vsnprintf(pszDest, cchMax, pszFormat, argList); #pragma warning(pop) #endif // ASSERT((iRet < 0) || (((size_t)iRet) <= cchMax)); if ((iRet < 0) || (((size_t)iRet) > cchMax)) { // need to null terminate the string pszDest += cchMax; *pszDest = '\0'; cchNewDestLength = cchMax; // we have truncated pszDest status = STATUS_BUFFER_OVERFLOW; } else if (((size_t)iRet) == cchMax) { // need to null terminate the string pszDest += cchMax; *pszDest = '\0'; cchNewDestLength = cchMax; } else { cchNewDestLength = (size_t)iRet; } if (pcchNewDestLength) { *pcchNewDestLength = cchNewDestLength; } return status; } NTSTRSAFEWORKERDDI RtlStringVPrintfWorkerW( __out_ecount(cchDest) NTSTRSAFE_PWSTR pszDest, __in __in_range(1, NTSTRSAFE_MAX_CCH) size_t cchDest, __out_opt __deref_out_range(<=, cchDest - 1) size_t* pcchNewDestLength, __in __format_string NTSTRSAFE_PCWSTR pszFormat, __in va_list argList) { NTSTATUS status = STATUS_SUCCESS; int iRet; size_t cchMax; size_t cchNewDestLength = 0; // leave the last space for the null terminator cchMax = cchDest - 1; #if (NTSTRSAFE_USE_SECURE_CRT == 1) && !defined(NTSTRSAFE_LIB_IMPL) iRet = _vsnwprintf_s(pszDest, cchDest, cchMax, pszFormat, argList); #else #pragma warning(push) #pragma warning(disable: __WARNING_BANNED_API_USAGE)// "STRSAFE not included" iRet = _vsnwprintf(pszDest, cchMax, pszFormat, argList); #pragma warning(pop) #endif // ASSERT((iRet < 0) || (((size_t)iRet) <= cchMax)); if ((iRet < 0) || (((size_t)iRet) > cchMax)) { // need to null terminate the string pszDest += cchMax; *pszDest = L'\0'; cchNewDestLength = cchMax; // we have truncated pszDest status = STATUS_BUFFER_OVERFLOW; } else if (((size_t)iRet) == cchMax) { // need to null terminate the string pszDest += cchMax; *pszDest = L'\0'; cchNewDestLength = cchMax; } else { cchNewDestLength = (size_t)iRet; } if (pcchNewDestLength) { *pcchNewDestLength = cchNewDestLength; } return status; } NTSTRSAFEWORKERDDI RtlStringExHandleFillBehindNullA( __inout_bcount(cbRemaining) NTSTRSAFE_PSTR pszDestEnd, __in size_t cbRemaining, __in DWORD dwFlags) { if (cbRemaining > sizeof(char)) { memset(pszDestEnd + 1, STRSAFE_GET_FILL_PATTERN(dwFlags), cbRemaining - sizeof(char)); } return STATUS_SUCCESS; } NTSTRSAFEWORKERDDI RtlStringExHandleFillBehindNullW( __inout_bcount(cbRemaining) NTSTRSAFE_PWSTR pszDestEnd, __in size_t cbRemaining, __in DWORD dwFlags) { if (cbRemaining > sizeof(wchar_t)) { memset(pszDestEnd + 1, STRSAFE_GET_FILL_PATTERN(dwFlags), cbRemaining - sizeof(wchar_t)); } return STATUS_SUCCESS; } NTSTRSAFEWORKERDDI RtlStringExHandleOtherFlagsA( __inout_bcount(cbDest) NTSTRSAFE_PSTR pszDest, __in __in_range(sizeof(char), NTSTRSAFE_MAX_CCH * sizeof(char)) size_t cbDest, __in __in_range(<, cbDest / sizeof(char)) size_t cchOriginalDestLength, __deref_inout_ecount(*pcchRemaining) NTSTRSAFE_PSTR* ppszDestEnd, __out __deref_out_range(<=, cbDest / sizeof(char)) size_t* pcchRemaining, __in DWORD dwFlags) { size_t cchDest = cbDest / sizeof(char); if ((cchDest > 0) && (dwFlags & STRSAFE_NO_TRUNCATION)) { char* pszOriginalDestEnd; pszOriginalDestEnd = pszDest + cchOriginalDestLength; *ppszDestEnd = pszOriginalDestEnd; *pcchRemaining = cchDest - cchOriginalDestLength; // null terminate the end of the original string *pszOriginalDestEnd = '\0'; } if (dwFlags & STRSAFE_FILL_ON_FAILURE) { memset(pszDest, STRSAFE_GET_FILL_PATTERN(dwFlags), cbDest); if (STRSAFE_GET_FILL_PATTERN(dwFlags) == 0) { *ppszDestEnd = pszDest; *pcchRemaining = cchDest; } else if (cchDest > 0) { char* pszDestEnd; pszDestEnd = pszDest + cchDest - 1; *ppszDestEnd = pszDestEnd; *pcchRemaining = 1; // null terminate the end of the string *pszDestEnd = L'\0'; } } if ((cchDest > 0) && (dwFlags & STRSAFE_NULL_ON_FAILURE)) { *ppszDestEnd = pszDest; *pcchRemaining = cchDest; // null terminate the beginning of the string *pszDest = '\0'; } return STATUS_SUCCESS; } NTSTRSAFEWORKERDDI RtlStringExHandleOtherFlagsW( __inout_bcount(cbDest) NTSTRSAFE_PWSTR pszDest, __in __in_range(sizeof(wchar_t), NTSTRSAFE_MAX_CCH * sizeof(wchar_t)) size_t cbDest, __in __in_range(<, cbDest / sizeof(wchar_t)) size_t cchOriginalDestLength, __deref_inout_ecount(*pcchRemaining) NTSTRSAFE_PWSTR* ppszDestEnd, __out __deref_out_range(<=, cbDest / sizeof(wchar_t)) size_t* pcchRemaining, __in DWORD dwFlags) { size_t cchDest = cbDest / sizeof(wchar_t); if ((cchDest > 0) && (dwFlags & STRSAFE_NO_TRUNCATION)) { wchar_t* pszOriginalDestEnd; pszOriginalDestEnd = pszDest + cchOriginalDestLength; *ppszDestEnd = pszOriginalDestEnd; *pcchRemaining = cchDest - cchOriginalDestLength; // null terminate the end of the original string *pszOriginalDestEnd = L'\0'; } if (dwFlags & STRSAFE_FILL_ON_FAILURE) { memset(pszDest, STRSAFE_GET_FILL_PATTERN(dwFlags), cbDest); if (STRSAFE_GET_FILL_PATTERN(dwFlags) == 0) { *ppszDestEnd = pszDest; *pcchRemaining = cchDest; } else if (cchDest > 0) { wchar_t* pszDestEnd; pszDestEnd = pszDest + cchDest - 1; *ppszDestEnd = pszDestEnd; *pcchRemaining = 1; // null terminate the end of the string *pszDestEnd = L'\0'; } } if ((cchDest > 0) && (dwFlags & STRSAFE_NULL_ON_FAILURE)) { *ppszDestEnd = pszDest; *pcchRemaining = cchDest; // null terminate the beginning of the string *pszDest = L'\0'; } return STATUS_SUCCESS; } #ifndef NTSTRSAFE_NO_UNICODE_STRING_FUNCTIONS NTSTRSAFEWORKERDDI RtlUnicodeStringInitWorker( __out PUNICODE_STRING DestinationString, __in_opt NTSTRSAFE_PCWSTR pszSrc, __in const size_t cchMax, __in DWORD dwFlags) { NTSTATUS status = STATUS_SUCCESS; if (DestinationString || !(dwFlags & STRSAFE_IGNORE_NULLS)) { DestinationString->Length = 0; DestinationString->MaximumLength = 0; DestinationString->Buffer = NULL; } if (pszSrc) { size_t cchSrcLength; status = RtlStringLengthWorkerW(pszSrc, cchMax, &cchSrcLength); if (NT_SUCCESS(status)) { if (DestinationString) { size_t cbLength; // safe to multiply cchSrcLength * sizeof(wchar_t) since cchSrcLength < NTSTRSAFE_UNICODE_STRING_MAX_CCH and sizeof(wchar_t) is 2 cbLength = cchSrcLength * sizeof(wchar_t); DestinationString->Length = (USHORT)cbLength; // safe to add cbLength + sizeof(wchar_t) since cchSrcLength < NTSTRSAFE_UNICODE_STRING_MAX_CCH DestinationString->MaximumLength = (USHORT)(cbLength + sizeof(wchar_t)); DestinationString->Buffer = (PWSTR)pszSrc; } else { status = STATUS_INVALID_PARAMETER; } } } return status; } // Intentionally allow null deref in error cases. #pragma warning(push) #pragma warning(disable : __WARNING_DEREF_NULL_PTR) #pragma warning(disable : __WARNING_INVALID_PARAM_VALUE_1) #pragma warning(disable : __WARNING_RETURNING_BAD_RESULT) NTSTRSAFEWORKERDDI RtlUnicodeStringValidateWorker( __in_opt PCUNICODE_STRING SourceString, __in const size_t cchMax, __in DWORD dwFlags) { NTSTATUS status = STATUS_SUCCESS; if (SourceString || !(dwFlags & STRSAFE_IGNORE_NULLS)) { if (((SourceString->Length % sizeof(wchar_t)) != 0) || ((SourceString->MaximumLength % sizeof(wchar_t)) != 0) || (SourceString->Length > SourceString->MaximumLength) || (SourceString->MaximumLength > (cchMax * sizeof(wchar_t)))) { status = STATUS_INVALID_PARAMETER; } else if ((SourceString->Buffer == NULL) && ((SourceString->Length != 0) || (SourceString->MaximumLength != 0))) { status = STATUS_INVALID_PARAMETER; } } return status; } NTSTRSAFEWORKERDDI RtlUnicodeStringValidateSrcWorker( __in PCUNICODE_STRING SourceString, __deref_out_ecount(*pcchSrcLength) wchar_t** ppszSrc, __out size_t* pcchSrcLength, __in const size_t cchMax, __in DWORD dwFlags) { NTSTATUS status; *ppszSrc = NULL; *pcchSrcLength = 0; status = RtlUnicodeStringValidateWorker(SourceString, cchMax, dwFlags); if (NT_SUCCESS(status)) { if (SourceString) { *ppszSrc = SourceString->Buffer; *pcchSrcLength = SourceString->Length / sizeof(wchar_t); } if ((*ppszSrc == NULL) && (dwFlags & STRSAFE_IGNORE_NULLS)) { *ppszSrc = L""; } } return status; } // End intentionally allow null deref. #pragma warning(pop) NTSTRSAFEWORKERDDI RtlUnicodeStringValidateDestWorker( __in PCUNICODE_STRING DestinationString, __deref_out_ecount(*pcchDest) wchar_t** ppszDest, __out size_t* pcchDest, __out_opt size_t* pcchDestLength, __in const size_t cchMax, __in DWORD dwFlags) { NTSTATUS status; *ppszDest = NULL; *pcchDest = 0; if (pcchDestLength) { *pcchDestLength = 0; } status = RtlUnicodeStringValidateWorker(DestinationString, cchMax, dwFlags); if (NT_SUCCESS(status) && DestinationString) { *ppszDest = DestinationString->Buffer; *pcchDest = DestinationString->MaximumLength / sizeof(wchar_t); if (pcchDestLength) { *pcchDestLength = DestinationString->Length / sizeof(wchar_t); } } return status; } NTSTRSAFEWORKERDDI RtlStringCopyWideCharArrayWorker( __out_ecount(cchDest) NTSTRSAFE_PWSTR pszDest, __in size_t cchDest, __out_opt size_t* pcchNewDestLength, __in_ecount(cchSrcLength) const wchar_t* pszSrc, __in size_t cchSrcLength) { NTSTATUS status = STATUS_SUCCESS; size_t cchNewDestLength = 0; // ASSERT(cchDest != 0); while (cchDest && cchSrcLength) { *pszDest++ = *pszSrc++; cchDest--; cchSrcLength--; cchNewDestLength++; } if (cchDest == 0) { // we are going to truncate pszDest pszDest--; cchNewDestLength--; status = STATUS_BUFFER_OVERFLOW; } *pszDest = L'\0'; if (pcchNewDestLength) { *pcchNewDestLength = cchNewDestLength; } return status; } NTSTRSAFEWORKERDDI RtlWideCharArrayCopyStringWorker( __out_ecount(cchDest) wchar_t* pszDest, __in size_t cchDest, __out size_t* pcchNewDestLength, __in NTSTRSAFE_PCWSTR pszSrc, __in size_t cchToCopy) { NTSTATUS status = STATUS_SUCCESS; size_t cchNewDestLength = 0; while (cchDest && cchToCopy && (*pszSrc != L'\0')) { *pszDest++ = *pszSrc++; cchDest--; cchToCopy--; cchNewDestLength++; } if ((cchDest == 0) && (cchToCopy != 0) && (*pszSrc != L'\0')) { // we are going to truncate pszDest status = STATUS_BUFFER_OVERFLOW; } *pcchNewDestLength = cchNewDestLength; return status; } NTSTRSAFEWORKERDDI RtlWideCharArrayCopyWorker( __out_ecount(cchDest) wchar_t* pszDest, __in size_t cchDest, __out size_t* pcchNewDestLength, __in_ecount(cchSrcLength) const wchar_t* pszSrc, __in size_t cchSrcLength) { NTSTATUS status = STATUS_SUCCESS; size_t cchNewDestLength = 0; while (cchDest && cchSrcLength) { *pszDest++ = *pszSrc++; cchDest--; cchSrcLength--; cchNewDestLength++; } if ((cchDest == 0) && (cchSrcLength != 0)) { // we are going to truncate pszDest status = STATUS_BUFFER_OVERFLOW; } *pcchNewDestLength = cchNewDestLength; return status; } NTSTRSAFEWORKERDDI RtlWideCharArrayVPrintfWorker( __out_ecount(cchDest) wchar_t* pszDest, __in size_t cchDest, __out size_t* pcchNewDestLength, __in __format_string NTSTRSAFE_PCWSTR pszFormat, __in va_list argList) { NTSTATUS status = STATUS_SUCCESS; int iRet; #pragma warning(push) #pragma warning(disable: __WARNING_BANNED_API_USAGE)// "STRSAFE not included" iRet = _vsnwprintf(pszDest, cchDest, pszFormat, argList); #pragma warning(pop) // ASSERT((iRet < 0) || (((size_t)iRet) <= cchMax)); if ((iRet < 0) || (((size_t)iRet) > cchDest)) { *pcchNewDestLength = cchDest; // we have truncated pszDest status = STATUS_BUFFER_OVERFLOW; } else { *pcchNewDestLength = (size_t)iRet; } return status; } NTSTRSAFEWORKERDDI RtlUnicodeStringExHandleFill( __out_ecount(cchRemaining) wchar_t* pszDestEnd, __in size_t cchRemaining, __in DWORD dwFlags) { size_t cbRemaining; // safe to multiply cchRemaining * sizeof(wchar_t) since cchRemaining < NTSTRSAFE_UNICODE_STRING_MAX_CCH and sizeof(wchar_t) is 2 cbRemaining = cchRemaining * sizeof(wchar_t); memset(pszDestEnd, STRSAFE_GET_FILL_PATTERN(dwFlags), cbRemaining); return STATUS_SUCCESS; } NTSTRSAFEWORKERDDI RtlUnicodeStringExHandleOtherFlags( __inout_ecount(cchDest) wchar_t* pszDest, __in size_t cchDest, __in size_t cchOriginalDestLength, __out size_t* pcchNewDestLength, __deref_out_ecount(*pcchRemaining) wchar_t** ppszDestEnd, __out size_t* pcchRemaining, __in DWORD dwFlags) { if (dwFlags & STRSAFE_NO_TRUNCATION) { *ppszDestEnd = pszDest + cchOriginalDestLength; *pcchRemaining = cchDest - cchOriginalDestLength; *pcchNewDestLength = cchOriginalDestLength; } if (dwFlags & STRSAFE_FILL_ON_FAILURE) { size_t cbDest; // safe to multiply cchDest * sizeof(wchar_t) since cchDest < NTSTRSAFE_UNICODE_STRING_MAX_CCH and sizeof(wchar_t) is 2 cbDest = cchDest * sizeof(wchar_t); memset(pszDest, STRSAFE_GET_FILL_PATTERN(dwFlags), cbDest); *ppszDestEnd = pszDest; *pcchRemaining = cchDest; *pcchNewDestLength = 0; } if (dwFlags & STRSAFE_ZERO_LENGTH_ON_FAILURE) { *ppszDestEnd = pszDest; *pcchRemaining = cchDest; *pcchNewDestLength = 0; } return STATUS_SUCCESS; } #endif // !NTSTRSAFE_NO_UNICODE_STRING_FUNCTIONS #endif // defined(NTSTRSAFE_LIB_IMPL) || !defined(NTSTRSAFE_LIB) // Do not call these functions, they are worker functions for internal use within this file #ifdef DEPRECATE_SUPPORTED #pragma deprecated(RtlStringLengthWorkerA) #pragma deprecated(RtlStringLengthWorkerW) #pragma deprecated(RtlUnalignedStringLengthWorkerW) #pragma deprecated(RtlStringExValidateSrcA) #pragma deprecated(RtlStringExValidateSrcW) #pragma deprecated(RtlStringValidateDestA) #pragma deprecated(RtlStringValidateDestAndLengthA) #pragma deprecated(RtlStringValidateDestW) #pragma deprecated(RtlStringValidateDestAndLengthW) #pragma deprecated(RtlStringExValidateDestA) #pragma deprecated(RtlStringExValidateDestAndLengthA) #pragma deprecated(RtlStringExValidateDestW) #pragma deprecated(RtlStringExValidateDestAndLengthW) #pragma deprecated(RtlStringCopyWorkerA) #pragma deprecated(RtlStringCopyWorkerW) #pragma deprecated(RtlStringVPrintfWorkerA) #pragma deprecated(RtlStringVPrintfWorkerW) #pragma deprecated(RtlStringExHandleFillBehindNullA) #pragma deprecated(RtlStringExHandleFillBehindNullW) #pragma deprecated(RtlStringExHandleOtherFlagsA) #pragma deprecated(RtlStringExHandleOtherFlagsW) #pragma deprecated(RtlUnicodeStringInitWorker) #pragma deprecated(RtlUnicodeStringValidateWorker) #pragma deprecated(RtlUnicodeStringValidateSrcWorker) #pragma deprecated(RtlUnicodeStringValidateDestWorker) #pragma deprecated(RtlStringCopyWideCharArrayWorker) #pragma deprecated(RtlWideCharArrayCopyStringWorker) #pragma deprecated(RtlWideCharArrayCopyWorker) #pragma deprecated(RtlWideCharArrayVPrintfWorker) #pragma deprecated(RtlUnicodeStringExHandleFill) #pragma deprecated(RtlUnicodeStringExHandleOtherFlags) #else #define RtlStringLengthWorkerA RtlStringLengthWorkerA_instead_use_StringCchLengthA_or_StringCbLengthA #define RtlStringLengthWorkerW RtlStringLengthWorkerW_instead_use_StringCchLengthW_or_StringCbLengthW #define RtlUnalignedStringLengthWorkerW RtlUnalignedStringLengthWorkerW_instead_use_UnalignedStringCchLengthW #define RtlStringExValidateSrcA RtlStringExValidateSrcA_do_not_call_this_function #define RtlStringExValidateSrcW RtlStringExValidateSrcW_do_not_call_this_function #define RtlStringValidateDestA RtlStringValidateDestA_do_not_call_this_function #define RtlStringValidateDestAndLengthA RtlStringValidateDestAndLengthA_do_not_call_this_function #define RtlStringValidateDestW RtlStringValidateDestW_do_not_call_this_function #define RtlStringValidateDestAndLengthW RtlStringValidateDestAndLengthW_do_not_call_this_function #define RtlStringExValidateDestA RtlStringExValidateDestA_do_not_call_this_function #define RtlStringExValidateDestAndLengthA RtlStringExValidateDestAndLengthA_do_not_call_this_function #define RtlStringExValidateDestW RtlStringExValidateDestW_do_not_call_this_function #define RtlStringExValidateDestAndLengthW RtlStringExValidateDestAndLengthW_do_not_call_this_function #define RtlStringCopyWorkerA RtlStringCopyWorkerA_instead_use_StringCchCopyA_or_StringCbCopyA #define RtlStringCopyWorkerW RtlStringCopyWorkerW_instead_use_StringCchCopyW_or_StringCbCopyW #define RtlStringVPrintfWorkerA RtlStringVPrintfWorkerA_instead_use_StringCchVPrintfA_or_StringCbVPrintfA #define RtlStringVPrintfWorkerW RtlStringVPrintfWorkerW_instead_use_StringCchVPrintfW_or_StringCbVPrintfW #define RtlStringExHandleFillBehindNullA RtlStringExHandleFillBehindNullA_do_not_call_this_function #define RtlStringExHandleFillBehindNullW RtlStringExHandleFillBehindNullW_do_not_call_this_function #define RtlStringExHandleOtherFlagsA RtlStringExHandleOtherFlagsA_do_not_call_this_function #define RtlStringExHandleOtherFlagsW RtlStringExHandleOtherFlagsW_do_not_call_this_function #define RtlUnicodeStringInitWorker RtlUnicodeStringInitWorker_instead_use_RtlUnicodeStringInit_or_RtlUnicodeStringInitEx #define RtlUnicodeStringValidateWorker RtlUnicodeStringValidateWorker_instead_use_RtlUnicodeStringValidate_or_RtlUnicodeStringValidateEx #define RtlUnicodeStringValidateSrcWorker RtlUnicodeStringValidateSrcWorker_do_not_call_this_function #define RtlUnicodeStringValidateDestWorker RtlUnicodeStringValidateDestWorker_do_not_call_this_function #define RtlStringCopyWideCharArrayWorker RtlStringCopyWideCharArrayWorker_instead_use_RtlStringCchCopyUnicodeString_or_RtlStringCbCopyUnicodeString #define RtlWideCharArrayCopyStringWorker RtlWideCharArrayCopyStringWorker_instead_use_RtlUnicodeStringCopyString_or_RtlUnicodeStringCopyStringEx #define RtlWideCharArrayCopyWorker RtlWideCharArrayCopyWorker_instead_use_RtlUnicodeStringCopy_or_RtlUnicodeStringCopyEx #define RtlWideCharArrayVPrintfWorker RtlWideCharArrayVPrintfWorker_instead_use_RtlUnicodeStringVPrintf_or_RtlUnicodeStringPrintf #define RtlUnicodeStringExHandleFill RtlUnicodeStringExHandleFill_do_not_call_this_function #define RtlUnicodeStringExHandleOtherFlags RtlUnicodeStringExHandleOtherFlags_do_not_call_this_function #endif // !DEPRECATE_SUPPORTED #ifndef NTSTRSAFE_NO_DEPRECATE // Deprecate all of the unsafe functions to generate compiletime errors. If you do not want // this then you can #define NTSTRSAFE_NO_DEPRECATE before including this file #ifdef DEPRECATE_SUPPORTED #pragma deprecated(strcpy) #pragma deprecated(wcscpy) #pragma deprecated(strcat) #pragma deprecated(wcscat) #pragma deprecated(sprintf) #pragma deprecated(swprintf) #pragma deprecated(vsprintf) #pragma deprecated(vswprintf) #pragma deprecated(_snprintf) #pragma deprecated(_snwprintf) #pragma deprecated(_vsnprintf) #pragma deprecated(_vsnwprintf) #else // DEPRECATE_SUPPORTED #undef strcpy #define strcpy strcpy_instead_use_StringCchCopyA_or_StringCbCopyA; #undef wcscpy #define wcscpy wcscpy_instead_use_StringCchCopyW_or_StringCbCopyW; #undef strcat #define strcat strcat_instead_use_StringCchCatA_or_StringCbCatA; #undef wcscat #define wcscat wcscat_instead_use_StringCchCatW_or_StringCbCatW; #undef sprintf #define sprintf sprintf_instead_use_StringCchPrintfA_or_StringCbPrintfA; #undef swprintf #define swprintf swprintf_instead_use_StringCchPrintfW_or_StringCbPrintfW; #undef vsprintf #define vsprintf vsprintf_instead_use_StringCchVPrintfA_or_StringCbVPrintfA; #undef vswprintf #define vswprintf vswprintf_instead_use_StringCchVPrintfW_or_StringCbVPrintfW; #undef _snprintf #define _snprintf _snprintf_instead_use_StringCchPrintfA_or_StringCbPrintfA; #undef _snwprintf #define _snwprintf _snwprintf_instead_use_StringCchPrintfW_or_StringCbPrintfW; #undef _vsnprintf #define _vsnprintf _vsnprintf_instead_use_StringCchVPrintfA_or_StringCbVPrintfA; #undef _vsnwprintf #define _vsnwprintf _vsnwprintf_instead_use_StringCchVPrintfW_or_StringCbVPrintfW; #endif // DEPRECATE_SUPPORTED #endif // !NTSTRSAFE_NO_DEPRECATE #pragma warning(pop) #endif // _NTSTRSAFE_H_INCLUDED_