WideCharToMultiByte

  int WideCharToMultiByte(CodePage, dwFlags, lpWideCharStr, cchWideChar, lpMultiByteStr, cchMultiByte, lpDefaultChar, lpUsedDefaultChar)    
  UINT CodePage;    
  DWORD dwFlags;    
  LPWSTR lpWideCharStr;    
  int cchWideChar;    
  LPSTR lpMultiByteStr;    
  int cchMultiByte;    
  LPSTR lpDefaultChar;    
  LPBOOL lpUsedDefaultChar;    

The WideCharToMultiByte function is used to map a wide character string to its multibyte character string counterpart.

Parameters

CodePage

Code page used to perform the conversion. If CodePage is CP_ACP, the ANSI code page is used. If CodePage is CP_OEMCP, the OEM code page is used.

dwFlags

There are two categories of flags here. The first category is for performance. By not setting these flags, the routine will not do any extraneous checks. The performance flags are:

Value Meaning

WC_DEFAULTCHECK  
  check for default char and set lpUsedDefaultChar
WC_COMPOSITECHECK  
  convert composite chars to precomposed

The second category of flags are used only if the WC_COMPOSITECHECK flags is set. These flags handle the case when there is no precomposed mapping for a base/nonspace character combination in the wide character string. The default is to generate separate characters (WC_SEPCHARS). The flags include:

Value Meaning

WC_DISCARDNS  
  discard non-spacing characters
WC_SEPCHARS  
  generate separate characters (default)
WC_DEFAULTCHAR  
  replace exceptions with default character

lpWideCharStr

Pointer to the wide character string to be converted. If cchWideChar is -1, the string is assumed to be null-terminated.

cchWideChar

Character count of string pointed to by lpWideCharStr.

lpMultiByteStr

Pointer to memory buffer which receives the translated multibyte character string.

cchMultiByte

The character count of the memory buffer pointed to by lpMultiByteStr . If cchMultiByte is 0, then the function returns the number of characters required to hold the translated string. lpMultiByteStr is not referenced in this case.

lpDefaultChar

Pointer to the multibyte character used if a wide character is not representable in CodePage . If lpDefaultChar is NULL, a system default value will be used. If the WC_DEFAULTCHECK flag is set, this parameter will be ignored.

lpUsedDefaultChar

Pointer to the boolean location to set indicating that a default character was used. It is set to TRUE if one or more wide characters in the source string are not representable in CodePage ; FALSE otherwise. If the WC_DEFAULTCHECK flag is set, this parameter will be ignored.

Return Value

Success: number of multi-byte characters returned

Failure: 0

This function sets GetLastError with the following errors: ERROR_INSUFFICIENT_BUFFER, ERROR_INVALID_PARAMETER.

Comments

The lpMultiByteStr and lpWideCharStr pointers may NOT be the same; in this case the error ERROR_INVALID_PARAMETER results.