SDK 初始化

获取 SDK

从 PC SDK 下载页面 下载最新的 C++ SDK 包。

1. 概述

WebGLHost C++ SDK 提供了标准的 C++ 接口，用于在 Windows 和 macOS 桌面应用中集成和管理 WebGL 游戏小程序。

2. 加载 SDK

2.1 Windows 平台

使用 LoadLibraryA 动态加载 DLL 文件：

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

// Load the DLL
HMODULE hDll = LoadLibraryA("host\\webglhost_export.dll");
if (!hDll) {
    std::cerr << "Failed to load DLL: " << GetLastError() << std::endl;
    return 1;
}

// Get factory function
typedef IBrowsingService* (*GetBrowsingServiceFunc)();
GetBrowsingServiceFunc GetBrowsingService = 
    (GetBrowsingServiceFunc)GetProcAddress(hDll, "GetBrowsingService");

if (!GetBrowsingService) {
    std::cerr << "Failed to get GetBrowsingService function" << std::endl;
    FreeLibrary(hDll);
    return 1;
}

2.2 macOS 平台

使用 dlopen 动态加载 dylib 文件：

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

// Load the dylib
void* hDll = dlopen("host/libwebglhost_export.dylib", RTLD_LAZY);
if (!hDll) {
    std::cerr << "Failed to load dylib: " << dlerror() << std::endl;
    return 1;
}

// Get factory function
typedef IBrowsingService* (*GetBrowsingServiceFunc)();
GetBrowsingServiceFunc GetBrowsingService = 
    (GetBrowsingServiceFunc)dlsym(hDll, "GetBrowsingService");

if (!GetBrowsingService) {
    std::cerr << "Failed to get GetBrowsingService function: " << dlerror() << std::endl;
    dlclose(hDll);
    return 1;
}

3. 获取服务实例

3.1 GetBrowsingService

获取 IBrowsingService 服务实例。

函数签名

extern "C" WEBGLHOST_API IBrowsingService* GetBrowsingService();

返回值

返回 IBrowsingService* - 浏览服务接口指针

代码示例

// Get service instance
IBrowsingService* service = GetBrowsingService();
if (!service) {
    std::cerr << "Failed to get service instance" << std::endl;
    return 1;
}

std::cout << "Service instance created successfully" << std::endl;

4. 初始化浏览核心

4.1 InitializeBrowsingCore

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

函数签名

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

参数说明

参数	类型	必填	说明
config	const char*	是	JSON 格式的配置字符串
runtime_path	const char*	否	运行时可执行文件路径，传空字符串表示自动检测
handler	ICoreServiceHandler*	否	事件处理器，可以传 nullptr

配置参数 (config JSON)

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

字段	类型	必填	说明
sdkKey	String	是	SDK 密钥
sdkSecret	String	是	SDK 密钥
debug	Boolean	否	是否开启调试模式
logLevel	String	否	日志级别: "debug", "info", "warn", "error"

返回值

值	常量	说明
0	WMPF_ERRCODE_SUCCESS	初始化成功
-1	WMPF_ERRCODE_FAIL	初始化失败（运行时启动失败、连接失败等）
-2	WMPF_ERRCODE_INVALID_PARAM	参数无效
-4	WMPF_ERRCODE_ALREADY_INITIALIZED	已经初始化

代码示例

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

// Configuration
const char* SDK_KEY = "your-sdk-key";
const char* SDK_SECRET = "your-sdk-secret";

// Event handler implementation
class MyServiceHandler : public WIUnknownImpl {
public:
    void OnContextInitialized() override {
        std::cout << "Context initialized" << 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;
    }
};

int main() {
    // Load library and get service (see above)
    IBrowsingService* service = GetBrowsingService();
    
    // Build config JSON
    char config[1024];
    snprintf(config, sizeof(config), R"({
        "sdkKey": "%s",
        "sdkSecret": "%s",
        "debug": true,
        "logLevel": "debug"
    })", SDK_KEY, SDK_SECRET);
    
    // Create event handler
    MyServiceHandler handler;
    
    // Initialize
    // runtime_path: empty string for auto-detection
    // Windows: will look for "runtime\\webglhost-runtime.exe"
    // macOS: will look for "runtime/webglhost-runtime.app"
    int result = service->InitializeBrowsingCore(config, "", &handler);
    
    if (result == WMPF_ERRCODE_SUCCESS) {
        std::cout << "SDK initialized successfully!" << std::endl;
    } else {
        std::cerr << "SDK initialization failed: " << result << std::endl;
        return 1;
    }
    
    return 0;
}

运行时路径说明

• Windows: 如果传入空字符串，SDK 会在 DLL 所在目录的 runtime/webglhost-runtime.exe 查找运行时
• macOS: 如果传入空字符串，SDK 会在 dylib 所在目录的 runtime/webglhost-runtime.app 查找运行时
• 也可以传入绝对路径或相对路径指定运行时位置

5. 反初始化

5.1 UninitializeBrowsingCore

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

函数签名

void UninitializeBrowsingCore();

代码示例

// Cleanup before exit
service->UninitializeBrowsingCore();
service->Release();

// Unload library
#ifdef _WIN32
    FreeLibrary(hDll);
#else
    dlclose(hDll);
#endif

std::cout << "SDK uninitialized successfully" << std::endl;

完整示例

完整的初始化示例请参考 快速集成指南 或 Demo 项目。

6. 错误处理

建议始终检查返回值并处理错误：

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: general error" << std::endl;
        break;
    case WMPF_ERRCODE_INVALID_PARAM:
        std::cerr << "Initialization failed: invalid parameters" << std::endl;
        break;
    case WMPF_ERRCODE_ALREADY_INITIALIZED:
        std::cerr << "Already initialized" << std::endl;
        break;
    default:
        std::cerr << "Unknown error: " << result << std::endl;
        break;
}

7. 注意事项

1. 线程安全: SDK 的方法不是线程安全的，请在主线程中调用
2. 资源管理: 使用完毕后务必调用 UninitializeBrowsingCore 和 Release
3. 事件处理器生命周期: 传入的 ICoreServiceHandler 对象必须在整个 SDK 生命周期内保持有效
4. 运行时依赖: 确保运行时可执行文件在指定路径可访问

8. 相关文档

• IBrowsingService 接口详解
• ICoreServiceHandler 事件处理
• 错误码说明
• 快速集成指南