Windows Safe String Function

HRESULT StringCbLength(LPTSTR psz, size_t cbMax, size_t *pcb);

HRESULT StringCbLengthA(LPSTR psz, size_t cbMax, size_t *pcb);

HRESULT StringCbLengthW(LPWSTR psz, size_t cbMax, size_t *pcb);

Internationalization (I18n) Function Overview

The StringCbLength function is a replacement for locale-sensitive string length functions. It calculates the byte length of the string stored in psz, and stores the result in pcb, ensuring that the byte size of the string is not larger than cbMax. In the event of an error, a negative HRESULT value is returned, indicating the error.

The narrow version of the function, StringCbLengthA, passes in a single-byte or multibyte string and lengths that refer to the number of bytes.

The wide version of the function, StringCbLengthW, passes in a wide-character string, but, like the narrow version, 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 cbMax is set to the byte size of the 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. This is shown as the first choice in the following table:

Microsoft Windows MBCS	StringCbLength or StringCbLengthA
Microsoft Windows Unicode	StringCbLength or StringCbLengthW
Microsoft Windows Generic	StringCbLength

Windows Safe String Functions