Windows Safe String Function

HRESULT StringCbCatN(LPTSTR pszDest, size_t cbDest, LPCTSTR pszSrc, size_t cbMaxAppend);

HRESULT StringCbCatNA(LPSTR pszDest, size_t cbDest, LPCSTR pszSrc, size_t cbMaxAppend);

HRESULT StringCbCatNW(LPWSTR pszDest, size_t cbDest, LPCWSTR pszSrc, size_t cbMaxAppend);

HRESULT StringCbCatNEx(LPTSTR pszDest, size_t cbDest, LPCTSTR pszSrc, size_t cbMaxAppend, LPTSTR *ppszDestEnd, size_t *pcbRemaining, DWORD dwFlags);

HRESULT StringCbCatNExA(LPSTR pszDest, size_t cbDest, LPCSTR pszSrc, size_t cbMaxAppend, LPSTR *ppszDestEnd, size_t *pcbRemaining, DWORD dwFlags);

HRESULT StringCbCatNExW(LPWSTR pszDest, size_t cbDest, LPCWSTR pszSrc, size_t cbMaxAppend, LPWSTR *ppszDestEnd, size_t *pcbRemaining, DWORD dwFlags);

Internationalization (I18n) Function Overview

The StringCbCatN function is a replacement for locale-sensitive string concatenation functions. It concatenates up to cbMaxAppend bytes of pszStr to the end of pszDest, using the byte size of the buffer stored in cbDest to ensure that the destination string buffer is not overrun. In the event of an error, a negative HRESULT value is returned, indicating the error.

StringCbCatNEx adds advanced functionality: It returns a pointer to the end of the destination string as well as the number of bytes left unused in that string, and uses dwFlags for additional control.

The narrow versions of these functions, StringCbCatNA and StringCbCatNExA, pass in single-byte or multibyte strings and lengths that refer to the number of bytes.

The wide versions of these functions, StringCbCatNW and StringCbCatNExW, pass in wide-character strings, but, like the narrow versions, lengths that refer to the number of bytes.

I18n Issues

Use the appropriate version of the function as required for internationalization support, and ensure that cbDest is set to the byte size of the destination string buffer. See Locale-Sensitive Length Functions for a discussion on multibyte and wide character sizes.

Recommended Replacements*

When possible, use the Generic version of the function, rather than the narrow or wide versions, and let the Windows #define UNICODE switch determine which version of the function will be called. These are shown as the first choices in the following table:

Microsoft Windows MBCS	StringCbCatN/StringCbCatNEx or StringCbCatNA/StringCbCatNExA
Microsoft Windows Unicode	StringCbCatN/StringCbCatNEx or StringCbCatNW/StringCbCatNExW
Microsoft Windows Generic	StringCbCatN/StringCbCatNEx

Windows Safe String Functions