C语言 Windows API: MultiByteToWideChar与WideCharToMultiByte详解

一、函数简单介绍

这两个函数是由Windows提供的转换函数，不具有通用性。若需要跨平台或更简单的转换，可考虑C标准库中的 mbstowcs() 和 wcstombs()，但需注意其局限性。

涉及头文件：

#include <windows.h>
#include <wchar.h>

1. MultiByteToWideChar()

功能： 将多字节字符串映射为宽字符（Unicode）字符串。输入字符串不必是多字节字符组。

原型：

int MultiByteToWideChar(
    UINT CodePage,
    DWORD dwFlags,
    LPCSTR lpMultiByteStr,
    int cchMultiByte,
    LPWSTR lpWideCharStr,
    int cchWideChar
);

关键参数说明：

• CodePage： 指定源多字节字符串的字符集。常用值包括 CP_ACP（ANSI）、CP_UTF8（UTF-8）、CP_OEMCP（OEM）。注：CP_MACCP、CP_SYMBOL、CP_THREAD_ACP 在此场景下通常不支持或慎用。
• dwFlags： 行为控制标记。通常设为0。常用选项包括 MB_PRECOMPOSED（默认预作字符）、MB_COMPOSITE（组合字符）、MB_ERR_INVALID_CHARS（遇无效字符报错）。一般开发中取值为0即可。
• lpMultiByteStr / cchMultiByte： 源字符串指针及其长度。长度为 -1 表示自动计算到空结束符；为 0 则函数失败。
• lpWideCharStr / cchWideChar： 目标缓冲区指针及其容量（单位是个数，非字节数）。

返回值与错误处理：

• 成功且缓冲足够时，返回实际写入的宽字符数。
• 若 cchWideChar 为0（仅查询），返回所需缓冲大小。
• 失败时返回0，此时应调用 GetLastError() 获取错误码，如 ERROR_INSUFFICIENT_BUFFER（缓冲不足）、ERROR_NO_UNICODE_TRANSLATION（无法转换）等。

2. WideCharToMultiByte()

功能： 将宽字符（Unicode）字符串映射为多字节字符串。

原型：

int WideCharToMultiByte(
    UINT CodePage,
    DWORD dwFlags,
    LPCWSTR lpWideCharStr,
    int cchWideChar,
    LPSTR lpMultiByteStr,
    int cchMultiByte,
    LPCSTR lpDefaultChar,
    LPBOOL pfUsedDefaultChar
);

额外参数：

相比上一函数，多了 lpDefaultChar 和 pfUsedDefaultChar。用于处理无法在目标代码页中表示的字符。通常设为NULL和FALSE。若设为NULL且存在不可转字符，系统可能使用默认问号替代，这在生成文件名时极为危险（通配符风险）。

二、使用方法：安全转换三步走

无论是哪种方向转换，正确的操作顺序都是先查询尺寸，再分配内存，最后执行转换。直接硬编码大小极易导致缓冲区溢出或乱码。

第1步：将多字节转为宽字符串

1. 计算需求： 设置目标指针为NULL，大小为0，调用函数获取所需的 wchar_t 数量。
2. 分配内存： 根据上一步返回值分配堆内存，并使用 wmemset 清零。
3. 执行转换： 传入有效指针和新分配的大小，再次调用函数。
4. 释放资源： 使用完毕后调用 delete[] 释放内存。

// 注意：需在项目中使用 C++ 编译器以支持 std::cout/std::endl
void main() {
    char sBuf[50] = {0};
    strcpy(sBuf, "Hello中文测试");

    // 1. 获取需要的 wchar_t 个数
    // VC++ 默认 ANSI 环境，故取 CP_ACP；若源文件是 UTF-8 请改用 CP_UTF8
    int dBufSize = MultiByteToWideChar(CP_ACP, 0, sBuf, -1, NULL, 0);

    if (dBufSize == 0) {
        // 处理获取尺寸失败的情况
        return;
    }

    // 2. 分配内存（含结尾的空终止符）
    wchar_t *dBuf = new wchar_t[dBufSize];
    wmemset(dBuf, 0, dBufSize);

    // 3. 执行转换
    int nRet = MultiByteToWideChar(CP_ACP, 0, sBuf, -1, dBuf, dBufSize);

    if (nRet > 0) {
        // 转换成功，可以使用 dBuf
        wprintf(L"Converted String: %s\n", dBuf);
    } else {
        // 转换失败，可根据 GetLastError() 调试
        printf("Conversion failed\n");
    }

    // 4. 释放内存
    delete[] dBuf;
}

第2步：从宽字符串转为窄字节字符串

1. 计算需求： 同样先查询目标缓冲区的字节大小。
2. 分配内存： 分配 char 数组。
3. 执行转换： 传入正确的目标代码页（如 CP_OEMCP 或 CP_ACP）。

// 宽字符转窄字符示例
void WideToNarrowTest() {
    wchar_t sBuf[50] = {0};
    wcscpy(sBuf, L"Hello Unicode测试");

    // 1. 查询所需的 char 字节大小
    // 目标代码页设为 CP_OEMCP 或 CP_ACP
    int dBufSize = WideCharToMultiByte(CP_OEMCP, 0, sBuf, -1, NULL, 0, NULL, FALSE);

    if (dBufSize == 0) return;

    // 2. 分配内存
    char *dBuf = new char[dBufSize];
    memset(dBuf, 0, dBufSize);

    // 3. 执行转换
    int nRet = WideCharToMultiByte(CP_OEMCP, 0, sBuf, -1, dBuf, dBufSize, NULL, FALSE);

    if (nRet > 0) {
        printf("After Convert: %s\n", dBuf);
    } else {
        printf("Conversion failed\n");
    }

    // 4. 释放内存
    delete[] dBuf;
}

三、常见问题与排错

1. 出现乱码或转换失败

这是最常见的陷阱。请检查以下三点：

• 源编码匹配： 确保 CodePage 参数与你实际的源码/文件编码一致。例如，如果源代码保存为 UTF-8，必须使用 CP_UTF8，而不是默认的 CP_ACP。
• 两次调用一致性： 第一次查询尺寸和第二次真正转换时，输入的 cchMultiByte（源字符串长度或-1）必须保持一致。若在第一次查询后修改了源字符串，会导致后续转换数据越界或错误。
• 模拟器问题： 在某些定制系统（如旧版 WinCE）SDK 模拟器下，若系统默认语言未设置为中文，可能会导致宽字符显示为乱码。这属于系统定制层面问题，需在 Platform Builder 中设置 Locale Default Language 为中文并重新编译。

2. 为什么应该尽量使用宽字符?

Windows NT/2000/XP/7/... 内核完全基于 Unicode 构建。调用 ANSI API 时，系统内部会进行一次额外的 Unicode ↔ ANSI 转换，消耗性能。直接使用宽字符函数可提升效率并消除编码兼容性问题。

3. 跨编码开发的宏定义技巧

若要编写同时支持 ANSI 和 Unicode 的代码，可使用 MFC 或 Windows SDK 定义的通用宏：

#ifdef UNICODE
#define TEXT(x) L##x
#else
#define TEXT(x) x
#endif

配合 TCHAR、_tcscpy 等通用类型，通过定义 UNICODE 和 _UNICODE 宏来控制编译版本。