SHUnicodeToAnsiCP

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

Declaration

int
SHUnicodeToAnsiCP (
    UINT CodePage,
    LPCWSTR pwszSrc,
    LPSTR pszDst,
    int cchBuf);

Parameters

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

The pwszSrc argument provides the address of a null-terminated Unicode string.

The pszDst argument provides the address of a buffer that is to receive the multi-byte string.

The cchBuf argument provides the size of the buffer, in bytes.

Return Value

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

Behaviour

If pwszSrc is NULL, the function converts a null string. If pszDst is NULL or cchBuf 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 WideCharToMultiByte, but for code pages 1200, 50000, 65000 and 65001, the conversion is done by the MLANG function ConvertINetUnicodeToMultiByte. 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 SHUnicodeToAnsiCP function is exported from SHLWAPI as ordinal 218 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 SHUnicodeToAnsi 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.