MultiByteToWideChar() Codepages CP_ACP/CP_OEMCP

 Last reviewed: January 15, 1998
Article ID: Q108450
3.10 3.50 WINDOWS NT kbprg

The information in this article applies to:

  • Microsoft Win32 Software Development Kit (SDK) for Windows NT versions 3.1 and 3.5

SUMMARY

MultiByteToWideChar() maps a character string to a wide-character string. The declaration of this application programming interface (API) is as follows: 

   int MultiByteToWideChar(uCodePage, dwFlags, lpMultiByteStr,
      cchMultiByte, lpWideCharStr, cchWideChar)

   UINT uCodePage;         /* codepage                        */
   DWORD dwFlags;          /* character-type options           */
   LPCSTR lpMultiByteStr;  /* address of string to map         */
   int cchMultiByte;       /* number of characters in string   */
   LPWSTR lpWideCharStr;   /* address of wide-character buffer */
   int cchWideChar;        /* size of wide-character buffer    */
The first parameter, uCodePage, specifies the codepage to be used when performing the conversion. This discussion applies to the first parameter of WideCharToMultiByte() as well. The codepage can be any valid codepage number. It is a good idea to check this number with IsValidCodepage(), even though MultiByteToWideChar() returns an error if an invalid codepage is used. The codepage may also be one of the following values: 

   CP_ACP       ANSI codepage
   CP_OEMCP     OEM (original equipment manufacturer) codepage
CP_ACP instructs the API to use the currently set default Windows ANSI codepage. CP_OEMCP instructs the API to use the currently set default OEM codepage.

If Win32 ANSI APIs are used to get filenames from a Windows NT system, use CP_ACP when converting the string. Windows NT retrieves the name from the physical device and translates the OEM name into Unicode. The Unicode name is translated into ANSI if an ANSI API is called, then it can be translated back into Unicode with MultiByteToWideChar().

If filenames are being retrieved from a file that is OEM encoded, use CP_OEMCP instead.

MORE INFORMATION

When an application calls an ANSI function, the FAT/HPFS file systems will call AnsiToOem(); however, if an ANSI character does not exist in an OEM codepage, the filename will not be representable. In these cases, SetFileApisToOEM() should be called to prevent this problem by setting a group of the Win32 APIs to use the OEM codepage instead of the ANSI codepage.

Additional reference words: 3.10 3.50
KBCategory: kbprg
KBSubcategory: KBIntlDev

THE INFORMATION PROVIDED IN THE MICROSOFT KNOWLEDGE BASE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. MICROSOFT DISCLAIMS ALL WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING THE WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL MICROSOFT CORPORATION OR ITS SUPPLIERS BE LIABLE FOR ANY DAMAGES WHATSOEVER INCLUDING DIRECT, INDIRECT, INCIDENTAL, CONSEQUENTIAL, LOSS OF BUSINESS PROFITS OR SPECIAL DAMAGES, EVEN IF MICROSOFT CORPORATION OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. SOME STATES DO NOT ALLOW THE EXCLUSION OR LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES SO THE FOREGOING LIMITATION MAY NOT APPLY.

Last reviewed: January 15, 1998
© 1998 Microsoft Corporation. All rights reserved. Terms of Use.