SHUnicodeToAnsi

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

Declaration

int
SHUnicodeToAnsi (
    LPCWSTR pwszSrc,
    LPSTR pszDst,
    int cchBuf);

Parameters

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 ANSI 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.

The conversion is done by the standard API function WideCharToMultiByte, 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 SHUnicodeToAnsi function is exported from SHLWAPI as ordinal 217 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.