SHAnsiToUnicode

This function converts as much as possible of an ANSI string to a Unicode string.

Declaration

int
SHAnsiToUnicode (
    LPCSTR pszSrc,
    LPWSTR pwszDst,
    int cwchBuf);

Parameters

The pszSrc argument provides the address of a null-terminated ANSI 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.

The conversion is done by the standard API function MultiByteToWideChar, using the ANSI code page. 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 SHAnsiToUnicode function is exported from SHLWAPI as ordinal 215 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 function did get documented later in 2004. This article now conforms to Microsoft’s nomenclature.