SHAnsiToUnicodeCP

This function converts as much as possible of a multi-byte string in a given code page to a Unicode string.

Declaration

int
SHAnsiToUnicodeCP (
    UINT CodePage,
    LPCSTR pszSrc,
    LPWSTR pwszDst,
    int cwchBuf);

Parameters

The CodePage argument provides the ID of the code page to use for the conversion.

The pszSrc argument provides the address of a null-terminated multi-byte string.

The pwszDst argument provides the address of a buffer that is to receive the Unicode string.

The cwchBuf argument provides the size of the buffer, in Unicode characters.

Return Value

The function returns the size of the output string, in Unicode characters, including the terminating null. The function returns zero for failure.

Behaviour

If pszSrc is NULL, the function converts a null string. If pwszDst is NULL or cwchBuf is zero, the function cannot produce output and therefore fails, returning zero.

For most code pages, the conversion is done by the standard API function MultiByteToWideChar, but for code pages 1200, 50000, 65000 and 65001, the conversion is done by the MLANG function ConvertINetMultiByteToUnicode. Either way, if the output buffer is too small for a complete conversion, the function attempts a complete conversion in a temporary buffer and copies as much of the result as will fit in the given output buffer (still with a terminating null).

Availability

The SHAnsiToUnicodeCP function is exported from SHLWAPI as ordinal 216 in version 5.00 and higher.

Though this function dates from as long ago as 1999, it was still not documented by Microsoft in the MSDN Library at least as late as the CD edition dated January 2004.

However, the similar function SHAnsiToUnicode got documented later in 2004. This article now conforms to Microsoft’s nomenclature, inasmuch as the two functions are likely to use the same names for the same things.