IBrowsingService Interface

1. Overview

IBrowsingService is the main entry point interface for the WebGLHost C++ SDK. It provides methods for initializing the browsing core, querying sub-interfaces, and executing common commands.

During initialization, it automatically starts the runtime process (Windows: webglhost-runtime.exe, macOS: webglhost-runtime.app).

2. Interface Definition

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. Method Details

3.1 InitializeBrowsingCore

Initializes the browsing core service and starts the runtime process.

Function Signature

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

Parameter Description

• config (const char*): JSON format configuration string

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

• runtime_path (const char*): Path to runtime executable (pass empty string for auto-detection)

  • If empty, the DLL will look for the runtime relative to its own location
  • Windows: runtime/webglhost-runtime.exe
  • macOS: runtime/webglhost-runtime.app

• handler (ICoreServiceHandler*): Lifecycle event callback handler (can pass nullptr)

Return Value

• WMPF_ERRCODE_SUCCESS (0): Initialization successful
• WMPF_ERRCODE_FAIL (-1): Initialization failed (runtime startup failed, connection failed, etc.)
• WMPF_ERRCODE_INVALID_PARAM (-2): Invalid parameter
• WMPF_ERRCODE_ALREADY_INITIALIZED (-4): Already initialized

Code Example

// 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

Uninitializes the browsing core service, terminates the runtime process, and cleans up resources.

Function Signature

void UninitializeBrowsingCore()

Code Example

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

---

3.3 CallCommonCommand

Calls a common command (for extensions and custom commands).

Function Signature

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

Parameter Description

• command_name (const char*): Command name
• callback_id (int32_t): Callback ID
• data (const char*): Command data
• data_size (unsigned int): Data size

Return Value

• true: Command sent successfully
• false: Command failed (not connected)

Code Example

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. Factory Function

4.1 GetBrowsingService

Gets a new instance of IBrowsingService.

Function Signature

extern "C" WEBGLHOST_API IBrowsingService* GetBrowsingService();

Return Value

Returns an IBrowsingService interface pointer.

Code Example

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. Query Sub-Interfaces

Use the QueryInterface method inherited from WIUnknown to get other interfaces:

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 Available Interfaces

• IAppletManagerV3: Mini-game (applet) management interface

---

6. Reference Counting

IBrowsingService inherits from WIUnknown and uses COM-style reference counting:

// AddRef - increase reference count
ULONG refs = service->AddRef();

// Release - decrease reference count
// Object is automatically destroyed when reference count reaches 0
ULONG refs = service->Release();

Note: In most cases, you don't need to manually manage reference counting. Only use it when sharing interface pointers.

Complete Example

For complete usage examples, please refer to the Quick Integration Guide or the Demo Project.

---

7. Error Handling Best Practices

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. Important Notes

1. Singleton Usage: It's recommended to initialize only once during the application lifecycle
2. Thread Safety: SDK methods are not thread-safe; call them from the same thread
3. Resource Cleanup: Always call UninitializeBrowsingCore and Release before exiting
4. Event Handler Lifecycle: The passed ICoreServiceHandler must remain valid throughout the SDK lifecycle
5. Runtime Dependencies: Ensure the runtime executable and its dependencies are accessible

---

9. Related Documentation

• SDK Initialization
• IAppletManagerV3 Interface
• ICoreServiceHandler Interface
• Error Codes