Native Runtime

Dynamic Library Entry

A Native plugin should export plugin_invoke and a free function. When it needs host data, it receives the Host API through plugin_set_host_api and calls host_invoke.

#[repr(C)]
pub struct TingNativeHostApi {
    pub version: u32,
    pub host_invoke: Option<unsafe extern "C" fn(
        method: *const u8,
        params_json: *const u8,
        result_json: *mut *mut u8,
    ) -> i32>,
    pub host_free: Option<unsafe extern "C" fn(ptr: *mut u8)>,
}

#[no_mangle]
pub unsafe extern "C" fn plugin_set_host_api(api: *const TingNativeHostApi) -> i32 {
    // Store the host API pointer after checking version.
    0
}

#[no_mangle]
pub unsafe extern "C" fn plugin_invoke(
    method: *const u8,
    params: *const u8,
    result_ptr: *mut *mut u8,
) -> i32 {
    // Decode method and JSON params, then dispatch by capability.invoke.
    0
}

Host API

host_invoke(method, params_json, result_json) returns a JSON string and uses the same method names as HostGateway. Calls depend on the current authenticated user context; public routes, initialization, and background paths without a user context may be rejected.

Capability Example

Native plugins commonly implement format_handler, such as format probing, playback URL generation, streaming decryption, or system media library calls.

runtime: native
entry_point: libting_format.so
capabilities:
  - id: format.decrypt
    kind: format_handler
    invoke: handleFormat
    matches:
      extensions: [m4b, encrypted-audio]
permissions:
  - type: media_read
  - type: file_read

Platform Packages

Native plugins are usually built as separate .tr packages per platform, and the plugin store should return the matching download URL for each platform key.

Good Native Use Cases

• Format decoding, streaming decryption, and audio tag reading or writing.
• Calling FFmpeg, FFprobe, or system-native libraries.
• Tool capabilities that need platform binaries or high-performance I/O.