跳到主要内容

IBrowsingService 接口

1. 概述​

IBrowsingService 是 WebGLHost C++ SDK 的主要入口点接口。它提供了初始化浏览核心、查询子接口和执行通用命令的方法。

初始化时，它会自动启动运行时进程（Windows: webglhost-runtime.exe，macOS: webglhost-runtime.app）。

2. 接口定义​

interface IBrowsingService : public WIUnknown {
    virtual int InitializeBrowsingCore(
        const char* config,
        const char* runtime_path,
        ICoreServiceHandler* handler
    ) = 0;
    
    virtual void UninitializeBrowsingCore() = 0;
    
    virtual bool CallCommonCommand(
        const char* command_name,
        int32_t callback_id,
        const char* data,
        const unsigned int data_size
    ) = 0;
};

3. 方法详解​

3.1 InitializeBrowsingCore​

初始化浏览核心服务，启动运行时进程。

函数签名

int InitializeBrowsingCore(
    const char* config,
    const char* runtime_path,
    ICoreServiceHandler* handler
)

参数说明

  • config (const char*): JSON 格式的配置字符串

    {
        "sdkKey": "your-sdk-key",
        "sdkSecret": "your-sdk-secret",
        "debug": true,
        "logLevel": "debug"
    }

  • runtime_path (const char*): 运行时可执行文件路径（传空字符串表示自动检测）

    • 如果为空，DLL 会在相对于自身位置查找运行时文件
    • Windows: runtime/webglhost-runtime.exe
    • macOS: runtime/webglhost-runtime.app

  • handler (ICoreServiceHandler*): 生命周期事件回调处理器（可以传 nullptr）

返回值

  • WMPF_ERRCODE_SUCCESS (0): 初始化成功
  • WMPF_ERRCODE_FAIL (-1): 初始化失败（运行时启动失败、连接失败等）
  • WMPF_ERRCODE_INVALID_PARAM (-2): 参数无效
  • WMPF_ERRCODE_ALREADY_INITIALIZED (-4): 已经初始化

代码示例

// Load DLL (Windows)
HMODULE hDll = LoadLibraryA("webglhost_export.dll");
typedef IBrowsingService* (*GetBrowsingServiceFunc)();
GetBrowsingServiceFunc GetBrowsingService = 
    (GetBrowsingServiceFunc)GetProcAddress(hDll, "GetBrowsingService");

IBrowsingService* service = GetBrowsingService();

// Build config
const char* config = R"({
    "sdkKey": "AKIDcv9N9wkDXKZ7gDoB2avKlu0N8tnS",
    "sdkSecret": "sp9ZsGlNLmTSX9o0sa29C5FwmxemUV8A",
    "debug": true
})";

// Initialize with event handler
class MyHandler : public WIUnknownImpl {
public:
    void OnContextInitialized() override {
        std::cout << "Context ready" << std::endl;
    }
    
    void OnServiceDisconnected() override {
        std::cout << "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 << "Event: " << event_name << std::endl;
        return true;
    }
};

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

if (result == WMPF_ERRCODE_SUCCESS) {
    std::cout << "Initialized successfully!" << std::endl;
} else {
    std::cerr << "Initialization failed: " << result << std::endl;
}

3.2 UninitializeBrowsingCore​

反初始化浏览核心服务，终止运行时进程并清理资源。

函数签名

void UninitializeBrowsingCore()

代码示例

// Cleanup before exit
service->UninitializeBrowsingCore();
std::cout << "Service uninitialized" << std::endl;

3.3 CallCommonCommand​

调用通用命令（用于扩展和自定义命令）。

函数签名

bool CallCommonCommand(
    const char* command_name,
    int32_t callback_id,
    const char* data,
    const unsigned int data_size
)

参数说明

  • command_name (const char*): 命令名称
  • callback_id (int32_t): 回调 ID
  • data (const char*): 命令数据
  • data_size (unsigned int): 数据大小

返回值

  • true: 命令发送成功
  • false: 命令失败（未连接）

代码示例

const char* data = R"({"param": "value"})";
bool success = service->CallCommonCommand(
    "customCommand",
    12345,
    data,
    strlen(data)
);

if (success) {
    std::cout << "Command sent successfully" << std::endl;
} else {
    std::cerr << "Command failed" << std::endl;
}

4. 工厂函数​

4.1 GetBrowsingService​

获取 IBrowsingService 的新实例。

函数签名

extern "C" WEBGLHOST_API IBrowsingService* GetBrowsingService();

返回值

返回 IBrowsingService 接口指针。

代码示例

Windows:

// Load DLL and get function
HMODULE hDll = LoadLibraryA("webglhost_export.dll");
typedef IBrowsingService* (*GetBrowsingServiceFunc)();
GetBrowsingServiceFunc GetBrowsingService = 
    (GetBrowsingServiceFunc)GetProcAddress(hDll, "GetBrowsingService");

// Create instance
IBrowsingService* service = GetBrowsingService();

macOS:

// Load dylib and get function
void* hDll = dlopen("libwebglhost_export.dylib", RTLD_LAZY);
typedef IBrowsingService* (*GetBrowsingServiceFunc)();
GetBrowsingServiceFunc GetBrowsingService = 
    (GetBrowsingServiceFunc)dlsym(hDll, "GetBrowsingService");

// Create instance
IBrowsingService* service = GetBrowsingService();

5. 查询子接口​

使用从 WIUnknown 继承的 QueryInterface 方法获取其他接口：

IAppletManagerV3* appletMgr = nullptr;
int result = service->QueryInterface("IAppletManagerV3", (void**)&appletMgr);

if (result == WMPF_ERRCODE_SUCCESS && appletMgr != nullptr) {
    // Use appletMgr
    std::cout << "Got IAppletManagerV3 interface" << std::endl;
} else {
    std::cerr << "Failed to query interface" << std::endl;
}

5.1 可用接口​

  • IAppletManagerV3: 小游戏（小程序）管理接口

6. 引用计数​

IBrowsingService 继承自 WIUnknown，使用 COM 风格的引用计数：

// AddRef - 增加引用计数
ULONG refs = service->AddRef();

// Release - 减少引用计数
// 当引用计数降为 0 时，对象会自动销毁
ULONG refs = service->Release();

注意: 在大多数情况下，不需要手动管理引用计数。只在需要共享接口指针时使用。

完整示例

完整的使用示例请参考 快速集成指南 或 Demo 项目。

7. 错误处理最佳实践​

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

switch (result) {
    case WMPF_ERRCODE_SUCCESS:
        std::cout << "Success" << std::endl;
        break;
        
    case WMPF_ERRCODE_FAIL:
        std::cerr << "General failure - check runtime path and permissions" << std::endl;
        break;
        
    case WMPF_ERRCODE_INVALID_PARAM:
        std::cerr << "Invalid parameters - check config JSON format" << std::endl;
        break;
        
    case WMPF_ERRCODE_ALREADY_INITIALIZED:
        std::cout << "Already initialized - no action needed" << std::endl;
        break;
        
    default:
        std::cerr << "Unknown error code: " << result << std::endl;
        break;
}

8. 注意事项​

  1. 单例使用: 建议在应用生命周期内只初始化一次
  2. 线程安全: SDK 方法不是线程安全的，请在同一线程中调用
  3. 资源清理: 退出前务必调用 UninitializeBrowsingCore 和 Release
  4. 事件处理器生命周期: 传入的 ICoreServiceHandler 必须在整个 SDK 生命周期内保持有效
  5. 运行时依赖: 确保运行时可执行文件及其依赖项可访问

9. 相关文档​