错误码说明

1. 概述

WebGLHost C++ SDK 的错误码定义在 IBrowsingService.h 头文件中。

2. 错误码定义

// Error codes
#define WMPF_ERRCODE_SUCCESS           0
#define WMPF_ERRCODE_FAIL             -1
#define WMPF_ERRCODE_INVALID_PARAM    -2
#define WMPF_ERRCODE_NOT_INITIALIZED  -3
#define WMPF_ERRCODE_ALREADY_INITIALIZED -4

3. 错误码详解

3.1 WMPF_ERRCODE_SUCCESS (0)

说明: 操作成功完成

返回场景:

• InitializeBrowsingCore 初始化成功
• QueryInterface 查询接口成功
• 游戏启动成功（通过 LaunchCallback）

代码示例:

int result = service->InitializeBrowsingCore(config, "", &handler);

if (result == WMPF_ERRCODE_SUCCESS) {
    std::cout << "Initialization successful!" << std::endl;
}

---

3.2 WMPF_ERRCODE_FAIL (-1)

说明: 通用失败错误

可能原因:

• 运行时启动失败
• 运行时文件不存在或损坏
• 系统资源不足
• 网络请求失败

返回场景:

• InitializeBrowsingCore 初始化失败
• QueryInterface 查询不存在的接口
• 游戏启动失败（运行时错误）

代码示例:

int result = service->InitializeBrowsingCore(config, "", &handler);

if (result == WMPF_ERRCODE_FAIL) {
    std::cerr << "Initialization failed!" << std::endl;
    std::cerr << "Possible causes:" << std::endl;
    std::cerr << "  - Runtime not found" << std::endl;
    std::cerr << "  - Invalid configuration" << std::endl;
}

排查步骤:

1. 检查运行时路径是否正确
2. 确认运行时文件存在且可执行
3. 检查系统日志和 SDK 日志
4. 验证网络连接（如需远程资源）

---

3.3 WMPF_ERRCODE_INVALID_PARAM (-2)

说明: 参数无效

可能原因:

• 传入的 config JSON 格式错误
• 必填参数缺失（如 sdkKey、sdkSecret）
• 参数值不合法
• 传入 nullptr 而期望有效指针

返回场景:

• InitializeBrowsingCore 配置参数错误
• QueryInterface 传入无效的类型名称或 nullptr 输出指针

代码示例:

// Bad: Invalid JSON format
const char* badConfig = "{sdkKey: no-quotes}";  // Missing quotes

int result = service->InitializeBrowsingCore(badConfig, "", nullptr);

if (result == WMPF_ERRCODE_INVALID_PARAM) {
    std::cerr << "Invalid parameters!" << std::endl;
    std::cerr << "Check your configuration JSON format" << std::endl;
}

正确的配置格式:

// Good: Valid JSON
const char* goodConfig = R"({
    "sdkKey": "your-sdk-key",
    "sdkSecret": "your-sdk-secret",
    "debug": true
})";

int result = service->InitializeBrowsingCore(goodConfig, "", nullptr);

---

3.4 WMPF_ERRCODE_NOT_INITIALIZED (-3)

说明: SDK 未初始化

可能原因:

• 在调用 InitializeBrowsingCore 之前尝试使用 SDK 功能
• 在调用 UninitializeBrowsingCore 之后继续使用 SDK

返回场景:

• 未初始化就调用 SDK 方法
• 已反初始化后继续调用

代码示例:

IBrowsingService* service = GetBrowsingService();

// Bad: Query interface before initialization
IAppletManagerV3* appletMgr = nullptr;
int result = service->QueryInterface("IAppletManagerV3", (void**)&appletMgr);

if (result == WMPF_ERRCODE_NOT_INITIALIZED) {
    std::cerr << "SDK not initialized!" << std::endl;
    std::cerr << "Call InitializeBrowsingCore first" << std::endl;
}

// Good: Initialize first
service->InitializeBrowsingCore(config, "", nullptr);
result = service->QueryInterface("IAppletManagerV3", (void**)&appletMgr);

---

3.5 WMPF_ERRCODE_ALREADY_INITIALIZED (-4)

说明: SDK 已经初始化

可能原因:

• 重复调用 InitializeBrowsingCore
• 未调用 UninitializeBrowsingCore 就尝试重新初始化

返回场景:

• 对已初始化的服务再次调用 InitializeBrowsingCore

代码示例:

IBrowsingService* service = GetBrowsingService();

// First initialization
int result = service->InitializeBrowsingCore(config, "", nullptr);
std::cout << "First init: " << result << std::endl;

// Try to initialize again
result = service->InitializeBrowsingCore(config, "", nullptr);

if (result == WMPF_ERRCODE_ALREADY_INITIALIZED) {
    std::cout << "Already initialized, no need to initialize again" << std::endl;
    // This is not necessarily an error - continue using the SDK
}

处理建议:

• 这不是严重错误，可以继续使用已初始化的服务
• 如果需要重新初始化，先调用 UninitializeBrowsingCore

---

4. 错误处理最佳实践

4.1 使用 switch 语句

int result = service->InitializeBrowsingCore(config, "", &handler);

switch (result) {
    case WMPF_ERRCODE_SUCCESS:
        std::cout << "✓ Initialization successful" << std::endl;
        break;
        
    case WMPF_ERRCODE_FAIL:
        std::cerr << "✗ Initialization failed - check runtime and logs" << std::endl;
        return 1;
        
    case WMPF_ERRCODE_INVALID_PARAM:
        std::cerr << "✗ Invalid parameters - check config JSON" << std::endl;
        return 1;
        
    case WMPF_ERRCODE_NOT_INITIALIZED:
        std::cerr << "✗ Not initialized (shouldn't happen here)" << std::endl;
        return 1;
        
    case WMPF_ERRCODE_ALREADY_INITIALIZED:
        std::cout << "⚠ Already initialized - continuing..." << std::endl;
        break;
        
    default:
        std::cerr << "✗ Unknown error code: " << result << std::endl;
        return 1;
}

4.2 创建错误处理帮助函数

const char* GetErrorString(int errorCode) {
    switch (errorCode) {
        case WMPF_ERRCODE_SUCCESS:
            return "Success";
        case WMPF_ERRCODE_FAIL:
            return "General failure";
        case WMPF_ERRCODE_INVALID_PARAM:
            return "Invalid parameter";
        case WMPF_ERRCODE_NOT_INITIALIZED:
            return "Not initialized";
        case WMPF_ERRCODE_ALREADY_INITIALIZED:
            return "Already initialized";
        default:
            return "Unknown error";
    }
}

// Usage
int result = service->InitializeBrowsingCore(config, "", nullptr);
std::cout << "Result: " << GetErrorString(result) << std::endl;

4.3 日志记录

void LogError(const char* operation, int errorCode) {
    std::cerr << "[ERROR] " << operation << " failed with code " 
              << errorCode << " (" << GetErrorString(errorCode) << ")" 
              << std::endl;
}

// Usage
int result = service->InitializeBrowsingCore(config, "", nullptr);
if (result != WMPF_ERRCODE_SUCCESS) {
    LogError("InitializeBrowsingCore", result);
}

---

5. 游戏启动错误码

游戏启动通过 LaunchCallback 返回错误码：

void OnLaunchComplete(const char* app_id, int result_code, const char* error_desc) {
    if (result_code == WMPF_ERRCODE_SUCCESS) {
        std::cout << "✓ Game launched: " << app_id << std::endl;
    } else {
        std::cerr << "✗ Game launch failed" << std::endl;
        std::cerr << "  App ID: " << app_id << std::endl;
        std::cerr << "  Error code: " << result_code << std::endl;
        std::cerr << "  Description: " << (error_desc ? error_desc : "N/A") << std::endl;
        
        // Handle specific errors
        switch (result_code) {
            case WMPF_ERRCODE_FAIL:
                std::cerr << "  Possible causes:" << std::endl;
                std::cerr << "    - Invalid launch key" << std::endl;
                std::cerr << "    - Network error" << std::endl;
                std::cerr << "    - Game file download failed" << std::endl;
                break;
                
            case WMPF_ERRCODE_INVALID_PARAM:
                std::cerr << "  Check launch configuration JSON" << std::endl;
                break;
        }
    }
}

---

6. 完整错误处理示例

#include <iostream>
#include "IBrowsingService.h"
#include "IAppletManagerV3.h"

class ErrorHandler {
public:
    static const char* GetErrorString(int code) {
        switch (code) {
            case WMPF_ERRCODE_SUCCESS: return "Success";
            case WMPF_ERRCODE_FAIL: return "Failure";
            case WMPF_ERRCODE_INVALID_PARAM: return "Invalid parameter";
            case WMPF_ERRCODE_NOT_INITIALIZED: return "Not initialized";
            case WMPF_ERRCODE_ALREADY_INITIALIZED: return "Already initialized";
            default: return "Unknown";
        }
    }
    
    static void LogResult(const char* operation, int code) {
        if (code == WMPF_ERRCODE_SUCCESS) {
            std::cout << "[✓] " << operation << " succeeded" << std::endl;
        } else {
            std::cerr << "[✗] " << operation << " failed: " 
                      << GetErrorString(code) << " (" << code << ")" << std::endl;
        }
    }
    
    static bool HandleError(const char* operation, int code) {
        LogResult(operation, code);
        return (code == WMPF_ERRCODE_SUCCESS || 
                code == WMPF_ERRCODE_ALREADY_INITIALIZED);
    }
};

int main() {
    IBrowsingService* service = GetBrowsingService();
    
    // Initialize
    const char* config = R"({"sdkKey": "xxx", "sdkSecret": "yyy"})";
    int result = service->InitializeBrowsingCore(config, "", nullptr);
    
    if (!ErrorHandler::HandleError("Initialize", result)) {
        service->Release();
        return 1;
    }
    
    // Query interface
    IAppletManagerV3* appletMgr = nullptr;
    result = service->QueryInterface("IAppletManagerV3", (void**)&appletMgr);
    
    if (!ErrorHandler::HandleError("QueryInterface", result)) {
        service->UninitializeBrowsingCore();
        service->Release();
        return 1;
    }
    
    // Continue with application logic...
    
    // Cleanup
    appletMgr->Release();
    service->UninitializeBrowsingCore();
    service->Release();
    
    return 0;
}

---

7. 注意事项

1. 始终检查返回值: 不要假设操作成功
2. 错误日志: 记录错误详情以便排查
3. 用户友好: 向用户展示可理解的错误消息
4. 恢复策略: 为可恢复错误提供重试机制
5. 资源清理: 错误发生时正确释放资源

---

8. 故障排查流程

1. 获取错误码
   ↓
2. 查看错误描述（如有）
   ↓
3. 检查日志文件
   ↓
4. 验证配置参数
   ↓
5. 检查运行时文件
   ↓
6. 确认系统资源
   ↓
7. 尝试最小示例
   ↓
8. 联系技术支持

---

9. 相关文档

• SDK 初始化
• IBrowsingService 接口
• IAppletManagerV3 接口
• 回调函数说明