MultiByteToWideChar

MultiByteToWideChar is a Windows API function that converts a multibyte character string, defined in a specific code page, to a wide-character string (UTF-16 on Windows). It is part of the Windows API and is declared in Windows.h with linking to Kernel32.lib.

The function takes these main parameters: CodePage specifies the code page used for the conversion (for example, CP_UTF8 for UTF-8, CP_ACP for the system ANSI code page). dwFlags can modify behavior with various optional flags. lpMultiByteStr points to the source multibyte string, and cbMultiByte indicates the number of bytes to process (or -1 to process until the null terminator). lpWideCharStr is the destination buffer for the resulting wide characters, and cchWideChar specifies the size of that buffer in wide characters. If cbMultiByte is -1, the function processes the entire string including the terminating null, and the resulting wide string is null-terminated.

Return value and error handling: The function returns the number of wide characters written, not including the null terminator, or zero on failure. On failure, GetLastError provides extended error information. If the output buffer is too small, the function fails with ERROR_INSUFFICIENT_BUFFER. A common pattern is to call the function first with cchWideChar set to 0 to obtain the required buffer size, then allocate a buffer of that size and call again.

Usage notes: MultiByteToWideChar is used to convert strings from various encodings (such as UTF-8 or a locale-specific ANSI code page) to UTF-16 for use with Windows APIs that expect wide strings. It is commonly paired with WideCharToMultiByte for the reverse conversion.