ICoreServiceHandler 接口

1. 概述

ICoreServiceHandler 是核心服务事件处理器接口，用于接收浏览核心服务的生命周期事件和通用事件回调。

2. 接口定义

interface ICoreServiceHandler : public WIUnknown {
    // Called when context is initialized
    virtual void OnContextInitialized() = 0;
    
    // Called when service is disconnected
    virtual void OnServiceDisconnected() = 0;
    
    // Called when common event happens
    virtual bool OnCommonEventHappened(
        const char* event_name,
        int32_t callback_id,
        const char* data,
        const unsigned int data_size
    ) = 0;
};

3. 方法详解

3.1 OnContextInitialized

当浏览核心上下文初始化完成时调用。这表示运行时已启动并准备就绪。

函数签名

virtual void OnContextInitialized() = 0;

调用时机

• 在 InitializeBrowsingCore 成功后
• 运行时准备就绪

代码示例

class MyServiceHandler : public WIUnknownImpl {
public:
    void OnContextInitialized() override {
        std::cout << "✓ Context initialized successfully" << std::endl;
        std::cout << "Runtime server is ready" << std::endl;
        
        // Can now safely query sub-interfaces and launch games
    }
};

---

3.2 OnServiceDisconnected

当与运行时的连接断开时调用。

函数签名

virtual void OnServiceDisconnected() = 0;

调用时机

• 运行时意外退出
• 调用 UninitializeBrowsingCore 时

代码示例

class MyServiceHandler : public WIUnknownImpl {
public:
    void OnServiceDisconnected() override {
        std::cerr << "✗ Service disconnected" << std::endl;
        std::cerr << "Runtime connection lost" << std::endl;
        
        // Handle disconnection (e.g., notify user, attempt reconnect, cleanup)
        // Note: Do NOT call SDK methods here as service is disconnected
    }
};

---

3.3 OnCommonEventHappened

当通用事件发生时调用。用于处理自定义事件和扩展功能。

函数签名

virtual bool OnCommonEventHappened(
    const char* event_name,
    int32_t callback_id,
    const char* data,
    const unsigned int data_size
) = 0;

参数说明

• event_name (const char*): 事件名称
• callback_id (int32_t): 回调 ID（用于响应）
• data (const char*): 事件数据（通常为 JSON 格式）
• data_size (unsigned int): 数据大小（字节）

返回值

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

代码示例

class MyServiceHandler : public WIUnknownImpl {
public:
    bool OnCommonEventHappened(
        const char* event_name,
        int32_t callback_id,
        const char* data,
        const unsigned int data_size
    ) override {
        std::cout << "[Common Event] " << event_name << std::endl;
        std::cout << "[Callback ID] " << callback_id << std::endl;
        
        if (data && data_size > 0) {
            std::string eventData(data, data_size);
            std::cout << "[Event Data] " << eventData << std::endl;
        }
        
        // Handle specific events
        if (strcmp(event_name, "customEvent") == 0) {
            // Process custom event
            return true;
        }
        
        // Default: event handled
        return true;
    }
};

---

4. 实现示例

4.1 基本实现

使用 WIUnknownImpl 基类简化实现：

#include "ICoreServiceHandler.h"
#include <iostream>

class MyServiceHandler : public WIUnknownImpl {
public:
    void OnContextInitialized() override {
        std::cout << "[Handler] Context initialized" << std::endl;
    }
    
    void OnServiceDisconnected() override {
        std::cout << "[Handler] Service disconnected" << std::endl;
    }
    
    bool OnCommonEventHappened(
        const char* event_name,
        int32_t callback_id,
        const char* data,
        const unsigned int data_size
    ) override {
        std::cout << "[Handler] Event: " << event_name << std::endl;
        return true;
    }
};

高级实现

更复杂的事件处理器实现（如带日志和状态管理）请参考 Demo 项目 中的 demo.cpp 文件。

---

5. 生命周期

典型的事件调用顺序：

1. Application calls InitializeBrowsingCore()
   ↓
2. SDK starts runtime process
   ↓
3. OnContextInitialized() called
   ↓
5. Application can now use SDK features
   ↓
6. [Application runs normally]
   ↓
7. Application calls UninitializeBrowsingCore()
   OR runtime crashes
   ↓
8. OnServiceDisconnected() called
   ↓
9. Cleanup complete

---

6. 线程安全

重要: 事件处理器的方法可能在不同的线程中被调用：

• OnContextInitialized: 可能在 SDK 内部工作线程中调用
• OnServiceDisconnected: 可能在 SDK 内部线程中调用
• OnCommonEventHappened: 可能在消息处理线程中调用

如需线程安全，请使用 std::mutex 保护共享数据。

---

7. 最佳实践

7.1 使用 WIUnknownImpl 基类

// Good: Extends WIUnknownImpl
class MyHandler : public WIUnknownImpl {
    // Implement only what you need
};

// Bad: Implements WIUnknown directly
class MyHandler : public WIUnknown {
    // Must implement QueryInterface, AddRef, Release manually
};

7.2 保持处理器轻量

void OnContextInitialized() override {
    // Good: Quick notification
    std::cout << "Ready!" << std::endl;
    readyFlag_ = true;
}

// Bad: Heavy processing blocks the SDK
void OnContextInitialized() override {
    LoadLargeFiles();  // DON'T DO THIS
    InitializeDatabase();  // DON'T DO THIS
}

7.3 处理器生命周期

int main() {
    // Good: Stack-allocated handler with appropriate lifetime
    MyServiceHandler handler;
    
    IBrowsingService* service = GetBrowsingService();
    service->InitializeBrowsingCore(config, "", &handler);
    
    // handler remains valid until end of scope
    // ...
    
    service->UninitializeBrowsingCore();
    // handler destroyed after service cleanup
}

7.4 错误处理

bool OnCommonEventHappened(
    const char* event_name,
    int32_t callback_id,
    const char* data,
    const unsigned int data_size
) override {
    try {
        // Process event
        ProcessEvent(event_name, data, data_size);
        return true;
    } catch (const std::exception& e) {
        std::cerr << "Event processing error: " << e.what() << std::endl;
        return false;  // Indicate failure
    }
}

---

8. 故障排查

8.1 问题: OnContextInitialized 未被调用

可能原因:

1. 初始化失败（检查 InitializeBrowsingCore 返回值）
2. 运行时路径错误
3. 传入了 nullptr 而不是处理器对象

解决方案:

// Check initialization result
int result = service->InitializeBrowsingCore(config, "", &handler);
if (result != WMPF_ERRCODE_SUCCESS) {
    std::cerr << "Init failed: " << result << std::endl;
}

8.2 问题: OnServiceDisconnected 被意外调用

可能原因:

1. 运行时崩溃
2. 运行时被外部终止

解决方案:

• 检查运行时日志
• 确保运行时文件完整
• 检查系统资源（内存等）

---

9. 注意事项

1. 生命周期: 处理器对象必须在整个 SDK 生命周期内保持有效
2. 线程安全: 回调可能在不同线程执行，需要适当的同步机制
3. 快速返回: 不要在回调中执行耗时操作
4. 不要调用 SDK 方法: 在 OnServiceDisconnected 中不要调用 SDK 方法
5. 异常处理: 捕获所有异常，不要让异常传播到 SDK

---

10. 相关文档

• SDK 初始化
• IBrowsingService 接口
• 错误码说明
• 回调函数说明