ThunderClientLibraries is a collection of lightweight, process-boundary client libraries that enable out-of-process components — such as media pipelines, browser runtimes, and application runtimes — to consume services hosted inside the WPEFramework (Thunder) plugin host. Each library exposes a stable C or C++ API to access the functionality provided by the corresponding Thunder service.

ThunderClientLibraries provides a stable abstraction for any component — whether a standalone application, an out-of-process runtime, or a plugin library — that needs to access services hosted inside the WPEFramework (Thunder) plugin host without a direct dependency on Thunder internals. The libraries are independent of one another; a component links only the libraries it needs.

Typical consumers include media pipeline processes requiring DRM session creation through OpenCDM, web runtimes needing display or device capability metadata, Bluetooth audio pipelines streaming audio to or from a paired device, and plugin libraries that need access to Thunder-hosted functionality without a direct dependency on Thunder internals.

Key Features & Responsibilities:

• OpenCDM (OCDM) Client: Provides the Open Content Decryption Module interface to media pipelines and browser runtimes, enabling DRM system selection, license session creation, and encrypted content decryption across a process boundary.
• SecurityAgent Client: Exposes a GetToken() function that allows out-of-process callers to obtain a signed authentication token from the SecurityAgent plugin, required for authorizing JSON-RPC calls to Thunder plugins.
• DeviceInfo Client: Provides structured access to device hardware capabilities including supported video outputs, HDCP versions, audio outputs, audio codec capabilities, and screen resolutions, via the Exchange::IDeviceInfo family of interfaces.
• DisplayInfo Client: Delivers display connection properties such as HDR mode, HDCP protection level, EDID data (color formats, color depths, audio formats, aspect ratios, supported refresh rates), and resolution to processes that need to adapt media rendering to the connected display.
• PlayerInfo Client: Exposes current player capabilities including supported audio and video codecs, playback resolution, and Dolby sound mode configuration, and delivers Dolby audio mode-change notifications to registered callers.
• CompositorClient: Provides a C++ graphics and input abstraction layer (Thunder::Compositor::IDisplay, Thunder::Compositor::IDisplay::ISurface, Thunder::Compositor::IDisplay::IKeyboard, Thunder::Compositor::IDisplay::IPointer, Thunder::Compositor::IDisplay::IWheel, Thunder::Compositor::IDisplay::ITouchPanel) that allows out-of-process renderers to create surfaces and receive input events through the compositor without being tightly coupled to a specific display server.
• Cryptography Client: Bridges callers to the Svalbard cryptographic vault service, exposing hash, cipher, Diffie-Hellman key exchange, random number generation, and persistent key storage operations through Exchange::ICryptography and related interfaces.
• ProvisionProxy Client: Provides GetDeviceId() and GetDRMId() functions to retrieve the unique device identifier and DRM credentials from the Provisioning service, connecting over Exchange::IProvisioning.
• BluetoothAudioSink Client: Delivers a C API through which an audio pipeline process can configure an active Bluetooth audio sink, acquire/relinquish the sink, submit audio frames over a shared memory buffer, and track connection state changes.
• BluetoothAudioSource Client: Delivers a C API through which an audio pipeline process can receive audio frames from a connected Bluetooth audio source via a shared memory buffer, and register callbacks for source state changes and audio stream events.

Internal Modules

Component Interactions

Interaction Matrix

Events Published

IPC Flow Patterns

Primary Request / Response Flow:

```mermaid
sequenceDiagram
    participant App as Apps
    participant Lib as ThunderClientLibrary
    participant Thunder as WPEFramework Plugin

    App->>Lib: C API call (e.g. deviceinfo_hdcp())
    Note over Lib: Validate state, acquire lock if needed
    Lib->>Thunder: COM-RPC method call via Exchange interface
    Thunder-->>Lib: Return value / status code
    Note over Lib: Map Exchange types to public C API types
    Lib-->>App: Status + output parameter filled
```

Event Notification Flow:

```mermaid
sequenceDiagram
    participant Thunder as WPEFramework Plugin
    participant Lib as ThunderClientLibrary
    participant App1 as Subscriber 1
    participant App2 as Subscriber 2

    Thunder->>Lib: COM-RPC notification callback\n(e.g. IConnectionProperties::INotification::Updated)
    Note over Lib: Acquire lock, iterate registered callbacks
    Lib->>App1: registered_callback(user_data)
    Lib->>App2: registered_callback(user_data)
```

Implementation Details

Major HAL APIs Integration

ThunderClientLibraries operates above the HAL boundary. Each library calls into the corresponding Thunder Exchange interface, which is served by a Thunder plugin that abstracts platform-specific HAL details. The table below lists the primary Exchange interfaces and entry-point methods consumed by each client library.

Key Implementation Logic

• State / Lifecycle Management: Libraries using RPC::SmartInterfaceType override the Operational(bool) virtual method. When Operational(true) is called, the library acquires interface pointers (e.g., _displayConnection, _playerInterface, _dolbyInterface) by calling BaseClass::Interface() and queries any sub-interfaces. When Operational(false) is called, all cached pointers are released. This is implemented in DisplayInfo.cpp, PlayerInfo.cpp, BluetoothAudioSink.cpp, and BluetoothAudioSource.cpp.

• Event Processing: Notification sinks are registered with the remote plugin interface immediately after the interface pointer is acquired. Incoming COM-RPC notification calls arrive on the RPC engine thread and are dispatched synchronously to all caller-registered callbacks by iterating the callback map under a Core::CriticalSection lock.

• Error Handling Strategy: COM-RPC errors and Thunder Core::ERROR_* codes are mapped to library-specific status enums (e.g., deviceinfo_status_t, displayinfo_status_t, playerinfo_status_t) and returned to callers. SecurityAgent and ProvisionProxy use negative integer return values to signal failure, where the absolute value indicates either the error code or the buffer length required. OpenCDM uses the OpenCDMError enum.

• Logging & Diagnostics: Libraries emit trace output through Thunder's tracing macros (e.g. TRACE_L1, TRACE_GLOBAL), routing through the Thunder tracing subsystem of the consuming process.