回调函数说明

1. 概述

WebGLHost C++ SDK 使用回调函数机制来通知宿主应用异步事件和操作结果。所有回调函数类型定义在 IAppletManagerV3.h 头文件中。

2. 回调函数类型

2.1 LaunchCallback - 游戏启动回调

游戏启动操作完成时调用，通知宿主应用启动结果。

类型定义

typedef void (*LaunchCallback)(
    const char* app_id,
    int result_code,
    const char* error_desc
);

参数说明

参数	类型	说明
app_id	const char*	游戏 ID
result_code	int	结果码（0 表示成功，非 0 表示失败）
error_desc	const char*	错误描述字符串（成功时为空或 nullptr）

调用时机

• 游戏启动成功后
• 游戏启动失败时
• 游戏资源加载完成后

代码示例

void OnGameLaunched(const char* app_id, int result_code, const char* error_desc) {
    std::cout << "=== Game Launch Callback ===" << std::endl;
    std::cout << "App ID: " << app_id << std::endl;
    std::cout << "Result Code: " << result_code << std::endl;
    
    if (result_code == WMPF_ERRCODE_SUCCESS) {
        std::cout << "✓ Game launched successfully!" << std::endl;
        // Continue with game interaction
    } else {
        std::cerr << "✗ Game launch failed!" << std::endl;
        if (error_desc && strlen(error_desc) > 0) {
            std::cerr << "Error: " << error_desc << std::endl;
        }
        // Handle error (e.g., show error message to user)
    }
}

// Usage
appletMgr->LaunchApplet(appId, launchConfig, strlen(launchConfig), OnGameLaunched);

---

2.2 JsApiHandler - JsApi 调用处理器

处理游戏中发起的 JsApi 调用请求。

类型定义

typedef bool (*JsApiHandler)(
    const char* app_id,
    const char* api_name,
    const char* data,
    size_t data_size,
    int task_id
);

参数说明

参数	类型	说明
app_id	const char*	发起调用的游戏 ID
api_name	const char*	API 名称
data	const char*	API 请求数据（JSON 格式）
data_size	size_t	数据大小（字节）
task_id	int	任务 ID，用于发送响应

返回值

• true: API 调用处理成功
• false: API 调用处理失败

调用时机

• 游戏调用 JsApi 时
• 需要宿主实现的功能时

常见 JsApi

API 名称	说明	请求数据
TJLoginHost	Unity Connect 身份验证	{"accessToken": "..."}
loadRewardAd	加载激励广告	{"adUnitId": "..."}
showRewardAd	显示激励广告	{}

代码示例

bool OnJsApiCall(
    const char* app_id,
    const char* api_name,
    const char* data,
    size_t data_size,
    int task_id
) {
    std::cout << "[JsApi] " << api_name << " from " << app_id << std::endl;
    
    std::string requestData(data, data_size);
    
    // Handle TJLoginHost - Unity Connect authentication
    if (strcmp(api_name, "TJLoginHost") == 0) {
        // Extract accessToken from request data
        // Perform authentication with Unity Connect API
        // ...
        
        // Send success response
        const char* response = R"({"success":true,"result":{"code":"auth_code_here"}})";
        g_appletMgr->SendJsApiOrEventResponse(task_id, response, strlen(response));
        return true;
    }
    
    // API not handled
    std::cout << "[JsApi] Unknown API: " << api_name << std::endl;
    const char* response = R"({"success":false,"errorCode":"NOT_HANDLED","error":"API not implemented"})";
    g_appletMgr->SendJsApiOrEventResponse(task_id, response, strlen(response));
    return false;
}

// Register handler
appletMgr->SetJsApiHandler(OnJsApiCall);

完整示例

完整的 JsApi 处理器实现请参考 Demo 项目 中的 demo_handlers.cpp 文件。

---

2.3 EventHandler - 游戏事件处理器

处理游戏发出的事件通知。

类型定义

typedef bool (*EventHandler)(
    const char* event_name,
    const char* data,
    size_t data_size,
    int task_id
);

参数说明

参数	类型	说明
event_name	const char*	事件名称
data	const char*	事件数据（JSON 格式）
data_size	size_t	数据大小（字节）
task_id	int	任务 ID（如需响应）

返回值

• true: 事件处理成功
• false: 事件处理失败

常见事件

• game_exited: 游戏退出通知

代码示例

bool OnGameEvent(
    const char* event_name,
    const char* data,
    size_t data_size,
    int task_id
) {
    std::cout << "=== Game Event ===" << std::endl;
    std::cout << "Event: " << event_name << std::endl;
    
    if (data && data_size > 0) {
        std::string eventData(data, data_size);
        std::cout << "Data: " << eventData << std::endl;
    }
    
    // Handle game exit event
    if (strcmp(event_name, "game_exited") == 0) {
        std::cout << "Game exited" << std::endl;
        // Perform cleanup, exit application, etc.
        return true;
    }
    
    return true;
}

// Register handler
appletMgr->SetAppletEventHandler(OnGameEvent);

---

3. 线程安全

重要: 所有回调函数可能在不同的线程中执行，需要注意线程安全。

• 使用 std::mutex 保护共享数据
• 考虑使用事件队列将回调数据传递到主线程处理
• 避免在回调中执行耗时操作

---

4. 最佳实践

4.1 快速返回

// Good: Quick processing
bool OnJsApiCall(...) {
    // Quick validation
    if (!ValidateRequest(data)) {
        SendError(task_id);
        return false;
    }
    
    // Queue for async processing
    QueueApiRequest(api_name, data, task_id);
    return true;
}

// Bad: Blocking operation
bool OnJsApiCall(...) {
    // DON'T DO THIS - blocks SDK thread
    DownloadLargeFile();  // Slow!
    ProcessHeavyComputation();  // Slow!
    return true;
}

4.2 错误处理

bool OnJsApiCall(...) {
    try {
        ProcessApi(api_name, data);
        return true;
    } catch (const std::exception& e) {
        std::cerr << "API error: " << e.what() << std::endl;
        SendError(task_id, e.what());
        return false;
    }
}

4.3 内存管理

bool OnJsApiCall(const char* app_id, const char* api_name, 
                const char* data, size_t data_size, int task_id) {
    // Good: Copy data if needed beyond callback scope
    std::string dataCopy(data, data_size);
    
    // Bad: Storing pointer (data may become invalid)
    // const char* storedData = data;  // DON'T DO THIS
    
    // Process with copied data
    ProcessAsync(dataCopy, task_id);
    return true;
}

---

5. 注意事项

1. 线程安全: 回调可能在不同线程执行，使用适当的同步机制
2. 快速返回: 不要在回调中执行耗时操作
3. 数据生命周期: 不要在回调外使用传入的指针参数
4. 异常处理: 捕获所有异常，不要让异常传播到 SDK
5. 响应及时: JsApi 和事件处理后应及时响应

---

6. 相关文档

• SDK 初始化
• IAppletManagerV3 接口
• ICoreServiceHandler 接口
• 错误码说明