rustduck-sys 1.1.0

Raw Rust FFI bindings to the C ABI used by TSDuck's Python API
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
//! Raw declarations for TSDuck's exported application ABI.
//!
//! TSDuck is implemented in C++. Its complete C++ class API does not have a
//! stable C ABI. The `tspy*` layer is the official C-compatible high-level ABI
//! used by TSDuck's Python module.
//!
//! # Safety
//!
//! These declarations are an unsafe ABI escape hatch. Callers are responsible
//! for native ownership, nullability, buffer lifetime, thread affinity,
//! callback containment, error interpretation, and matching every allocation
//! with its TSDuck delete operation. Prefer `rustduck` or `rustduck-core`'s safe API.
//!
//! # Deprecated callback contracts
//!
//! [`LogCallback`](crate::raw::LogCallback) and
//! [`PluginCallback`](crate::raw::PluginCallback) retain their original
//! declarations for source compatibility, but those declarations do not match
//! TSDuck's callback ABI. Calling the corresponding legacy constructors can
//! cause undefined behavior. Use [`LogCallbackUtf16`](crate::raw::LogCallbackUtf16),
//! [`PluginCallbackUtf16`](crate::raw::PluginCallbackUtf16), and the `Utf16`
//! constructors instead. The deprecated declarations retain this risk.

use std::mem::MaybeUninit;
use std::os::raw::{c_long, c_void};

include!(concat!(env!("OUT_DIR"), "/tsduck_version.rs"));

/// Rust representation of TSDuck's 16-bit `UChar` code unit.
pub type UChar = u16;

/// Callback with the ABI expected by synchronous and asynchronous TSDuck reports.
///
/// `message` borrows `message_bytes` bytes of native-endian UTF-16 for the
/// duration of the call. TSDuck 3.44 ignores the return value; return a null
/// pointer. Contain panics before returning to native code.
pub type LogCallbackUtf16 =
    unsafe extern "C" fn(severity: i32, message: *const UChar, message_bytes: usize) -> *mut c_void;

/// Plugin callback with the ABI expected by TSDuck's Python-compatible handler.
///
/// `plugin_name` borrows `plugin_name_bytes` bytes of native-endian UTF-16 for
/// the duration of the call. `data` remains a byte buffer with its own explicit
/// lengths. Return `false` to report callback failure and contain all panics.
pub type PluginCallbackUtf16 = unsafe extern "C" fn(
    event_code: u32,
    plugin_name: *const UChar,
    plugin_name_bytes: usize,
    plugin_index: usize,
    plugin_count: usize,
    bitrate: usize,
    plugin_packets: usize,
    total_packets: usize,
    data: *const u8,
    data_size: usize,
    data_max_size: usize,
    data_read_only: bool,
    event_data: *mut c_void,
) -> bool;

/// Legacy callback declaration with an incompatible return type and message pointer.
///
/// This declaration does not match TSDuck's `void* (*)(int, const UChar*,
/// size_t)` callback ABI. Using it can cause undefined behavior. Use
/// [`LogCallbackUtf16`] instead.
#[deprecated(
    since = "1.1.0",
    note = "incompatible with TSDuck's callback ABI and can cause undefined behavior; use LogCallbackUtf16"
)]
pub type LogCallback = unsafe extern "C" fn(severity: i32, message: *const u8, size: usize);

/// Legacy plugin callback declaration with an incompatible plugin-name pointer.
///
/// This declaration does not match TSDuck's `const UChar*` plugin-name ABI. Use
/// [`PluginCallbackUtf16`] instead.
#[deprecated(
    since = "1.1.0",
    note = "incompatible with TSDuck's plugin-name ABI; use PluginCallbackUtf16"
)]
pub type PluginCallback = unsafe extern "C" fn(
    event_code: u32,
    plugin_name: *const u8,
    plugin_name_size: usize,
    plugin_index: usize,
    plugin_count: usize,
    bitrate: usize,
    plugin_packets: usize,
    total_packets: usize,
    data: *const u8,
    data_size: usize,
    data_max_size: usize,
    data_read_only: bool,
    event_data: *mut c_void,
) -> bool;

/// Target-specific layout measurements for the repository-owned `tspy` mirror.
///
/// The native probe is compiled with the same TSDuck headers as the bridge.
/// This layout contains mirror measurements. Callback integration tests execute
/// the corrected declarations against the installed TSDuck library.
#[repr(C)]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct TspyAbiLayout {
    /// Major version from the TSDuck headers seen by the native compiler.
    pub tsduck_header_version_major: u32,
    /// Minor version from the TSDuck headers seen by the native compiler.
    pub tsduck_header_version_minor: u32,
    /// `sizeof(tspyTSProcessorArgs)`.
    pub ts_processor_args_size: usize,
    /// `alignof(tspyTSProcessorArgs)`.
    pub ts_processor_args_align: usize,
    /// Field offsets in declaration order.
    pub ts_processor_args_offsets: [usize; 16],
    /// `sizeof(tspyInputSwitcherArgs)`.
    pub input_switcher_args_size: usize,
    /// `alignof(tspyInputSwitcherArgs)`.
    pub input_switcher_args_align: usize,
    /// Field offsets in declaration order.
    pub input_switcher_args_offsets: [usize; 23],
    /// `sizeof(uint32_t)`.
    pub uint32_size: usize,
    /// `alignof(uint32_t)`.
    pub uint32_align: usize,
    /// `sizeof(size_t)`.
    pub size_t_size: usize,
    /// `alignof(size_t)`.
    pub size_t_align: usize,
    /// `sizeof(bool)`.
    pub bool_size: usize,
    /// `alignof(bool)`.
    pub bool_align: usize,
    /// `sizeof(long)`.
    pub long_size: usize,
    /// `alignof(long)`.
    pub long_align: usize,
}

/// Returns the native layout of the repository-owned raw ABI mirror.
#[must_use]
pub fn tspy_abi_layout() -> TspyAbiLayout {
    let mut layout = MaybeUninit::<TspyAbiLayout>::uninit();

    // SAFETY: `layout` is non-null aligned writable storage for the complete
    // result. The native probe initializes every field and does not retain it.
    unsafe {
        rustduck_tspy_query_abi_layout(layout.as_mut_ptr());
        layout.assume_init()
    }
}

/// Arguments passed to `tspyStartTSProcessor`.
#[repr(C)]
#[derive(Clone, Copy)]
pub struct TSProcessorArgs {
    pub ignore_joint_termination: c_long,
    pub buffer_size: c_long,
    pub max_flushed_packets: c_long,
    pub max_input_packets: c_long,
    pub max_output_packets: c_long,
    pub initial_input_packets: c_long,
    pub add_input_stuffing_0: c_long,
    pub add_input_stuffing_1: c_long,
    pub add_start_stuffing: c_long,
    pub add_stop_stuffing: c_long,
    pub bitrate: c_long,
    pub bitrate_adjust_interval: c_long,
    pub receive_timeout: c_long,
    pub log_plugin_index: c_long,
    pub plugins: *mut u8,
    pub plugins_size: usize,
}

/// Arguments passed to `tspyStartInputSwitcher`.
#[repr(C)]
#[derive(Clone, Copy)]
pub struct InputSwitcherArgs {
    pub fast_switch: c_long,
    pub delayed_switch: c_long,
    pub terminate: c_long,
    pub reuse_port: c_long,
    pub first_input: c_long,
    pub primary_input: c_long,
    pub cycle_count: c_long,
    pub buffered_packets: c_long,
    pub max_input_packets: c_long,
    pub max_output_packets: c_long,
    pub sock_buffer: c_long,
    pub remote_server_port: c_long,
    pub receive_timeout: c_long,
    pub plugins: *mut u8,
    pub plugins_size: usize,
    pub event_command: *mut u8,
    pub event_command_size: usize,
    pub event_udp_addr: *mut u8,
    pub event_udp_addr_size: usize,
    pub event_udp_port: c_long,
    pub local_addr: *mut u8,
    pub local_addr_size: usize,
    pub event_ttl: c_long,
}

struct RedactedPointer<T>(*const T);

impl<T> RedactedPointer<T> {
    fn new(pointer: *mut T) -> Self {
        Self(pointer)
    }
}

impl<T> std::fmt::Debug for RedactedPointer<T> {
    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        formatter.write_str(if self.0.is_null() { "null" } else { "non-null" })
    }
}

impl std::fmt::Debug for TSProcessorArgs {
    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        formatter
            .debug_struct("TSProcessorArgs")
            .field("ignore_joint_termination", &self.ignore_joint_termination)
            .field("buffer_size", &self.buffer_size)
            .field("max_flushed_packets", &self.max_flushed_packets)
            .field("max_input_packets", &self.max_input_packets)
            .field("max_output_packets", &self.max_output_packets)
            .field("initial_input_packets", &self.initial_input_packets)
            .field("add_input_stuffing_0", &self.add_input_stuffing_0)
            .field("add_input_stuffing_1", &self.add_input_stuffing_1)
            .field("add_start_stuffing", &self.add_start_stuffing)
            .field("add_stop_stuffing", &self.add_stop_stuffing)
            .field("bitrate", &self.bitrate)
            .field("bitrate_adjust_interval", &self.bitrate_adjust_interval)
            .field("receive_timeout", &self.receive_timeout)
            .field("log_plugin_index", &self.log_plugin_index)
            .field("plugins", &RedactedPointer::new(self.plugins))
            .field("plugins_size", &self.plugins_size)
            .finish()
    }
}

impl std::fmt::Debug for InputSwitcherArgs {
    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        formatter
            .debug_struct("InputSwitcherArgs")
            .field("fast_switch", &self.fast_switch)
            .field("delayed_switch", &self.delayed_switch)
            .field("terminate", &self.terminate)
            .field("reuse_port", &self.reuse_port)
            .field("first_input", &self.first_input)
            .field("primary_input", &self.primary_input)
            .field("cycle_count", &self.cycle_count)
            .field("buffered_packets", &self.buffered_packets)
            .field("max_input_packets", &self.max_input_packets)
            .field("max_output_packets", &self.max_output_packets)
            .field("sock_buffer", &self.sock_buffer)
            .field("remote_server_port", &self.remote_server_port)
            .field("receive_timeout", &self.receive_timeout)
            .field("plugins", &RedactedPointer::new(self.plugins))
            .field("plugins_size", &self.plugins_size)
            .field("event_command", &RedactedPointer::new(self.event_command))
            .field("event_command_size", &self.event_command_size)
            .field("event_udp_addr", &RedactedPointer::new(self.event_udp_addr))
            .field("event_udp_addr_size", &self.event_udp_addr_size)
            .field("event_udp_port", &self.event_udp_port)
            .field("local_addr", &RedactedPointer::new(self.local_addr))
            .field("local_addr_size", &self.local_addr_size)
            .field("event_ttl", &self.event_ttl)
            .finish()
    }
}

unsafe extern "C" {
    fn rustduck_tspy_query_abi_layout(layout: *mut TspyAbiLayout);

    pub fn tspyVersionInteger() -> u32;
    pub fn tspyVersionString(buffer: *mut u8, size: *mut usize);

    pub fn tspyNullReport() -> *mut c_void;
    pub fn tspyStdErrReport() -> *mut c_void;
    pub fn tspyNewAsyncReport(
        severity: i32,
        sync_log: bool,
        timed_log: bool,
        log_msg_count: usize,
    ) -> *mut c_void;
    /// Legacy synchronous report constructor with an incompatible callback ABI.
    #[allow(deprecated)]
    #[deprecated(
        since = "1.1.0",
        note = "uses an incompatible callback ABI; use tspyNewPySyncReportUtf16"
    )]
    pub fn tspyNewPySyncReport(callback: LogCallback, severity: i32) -> *mut c_void;
    /// Creates a synchronous report using TSDuck's UTF-16 callback ABI.
    #[allow(clashing_extern_declarations)]
    #[link_name = "tspyNewPySyncReport"]
    pub fn tspyNewPySyncReportUtf16(callback: LogCallbackUtf16, severity: i32) -> *mut c_void;
    /// Legacy asynchronous report constructor with an incompatible callback ABI.
    #[allow(deprecated)]
    #[deprecated(
        since = "1.1.0",
        note = "uses an incompatible callback ABI; use tspyNewPyAsyncReportUtf16"
    )]
    pub fn tspyNewPyAsyncReport(
        callback: LogCallback,
        severity: i32,
        sync_log: bool,
        log_msg_count: usize,
    ) -> *mut c_void;
    /// Creates an asynchronous report using TSDuck's UTF-16 callback ABI.
    #[allow(clashing_extern_declarations)]
    #[link_name = "tspyNewPyAsyncReport"]
    pub fn tspyNewPyAsyncReportUtf16(
        callback: LogCallbackUtf16,
        severity: i32,
        sync_log: bool,
        log_msg_count: usize,
    ) -> *mut c_void;
    pub fn tspyDeleteReport(report: *mut c_void);
    pub fn tspyTerminateAsyncReport(report: *mut c_void);
    pub fn tspySetMaxSeverity(report: *mut c_void, severity: i32);
    pub fn tspyLogReport(report: *mut c_void, severity: i32, message: *const u8, size: usize);
    pub fn tspyReportHeader(severity: i32, buffer: *mut u8, size: *mut usize);

    pub fn tspyNewDuckContext(report: *mut c_void) -> *mut c_void;
    pub fn tspyDeleteDuckContext(duck: *mut c_void);
    pub fn tspyDuckContextSetDefaultCharset(
        duck: *mut c_void,
        name: *const u8,
        size: usize,
    ) -> bool;
    pub fn tspyDuckContextSetDefaultCASId(duck: *mut c_void, cas: u16);
    pub fn tspyDuckContextSetDefaultPDS(duck: *mut c_void, pds: u32);
    pub fn tspyDuckContextAddStandards(duck: *mut c_void, mask: u32);
    pub fn tspyDuckContextStandards(duck: *mut c_void) -> u32;
    pub fn tspyDuckContextResetStandards(duck: *mut c_void, mask: u32);
    pub fn tspyDuckContextSetTimeReferenceOffset(duck: *mut c_void, offset: i64);
    pub fn tspyDuckContextSetTimeReference(duck: *mut c_void, name: *const u8, size: usize)
    -> bool;

    /// Legacy plugin handler constructor with an incompatible plugin-name ABI.
    #[allow(deprecated)]
    #[deprecated(
        since = "1.1.0",
        note = "uses an incompatible plugin-name ABI; use tspyNewPyPluginEventHandlerUtf16"
    )]
    pub fn tspyNewPyPluginEventHandler(callback: PluginCallback) -> *mut c_void;
    /// Creates a plugin event handler using TSDuck's UTF-16 callback ABI.
    #[allow(clashing_extern_declarations)]
    #[link_name = "tspyNewPyPluginEventHandler"]
    pub fn tspyNewPyPluginEventHandlerUtf16(callback: PluginCallbackUtf16) -> *mut c_void;
    pub fn tspyDeletePyPluginEventHandler(handler: *mut c_void);
    pub fn tspyPyPluginEventHandlerUpdateData(
        event_data: *mut c_void,
        data: *mut c_void,
        size: usize,
    );

    pub fn tspyNewSectionFile(duck: *mut c_void) -> *mut c_void;
    pub fn tspyDeleteSectionFile(section_file: *mut c_void);
    pub fn tspySectionFileClear(section_file: *mut c_void);
    pub fn tspySectionFileBinarySize(section_file: *mut c_void) -> usize;
    pub fn tspySectionFileSectionsCount(section_file: *mut c_void) -> usize;
    pub fn tspySectionFileTablesCount(section_file: *mut c_void) -> usize;
    pub fn tspySectionFileSetCRCValidation(section_file: *mut c_void, mode: i32);
    pub fn tspySectionLoadBuffer(section_file: *mut c_void, buffer: *const u8, size: usize)
    -> bool;
    pub fn tspySectionSaveBuffer(section_file: *mut c_void, buffer: *mut u8, size: *mut usize);
    pub fn tspySectionFileLoadBinary(
        section_file: *mut c_void,
        name: *const u8,
        size: usize,
    ) -> bool;
    pub fn tspySectionFileSaveBinary(
        section_file: *mut c_void,
        name: *const u8,
        size: usize,
    ) -> bool;
    pub fn tspySectionFileLoadXML(section_file: *mut c_void, name: *const u8, size: usize) -> bool;
    pub fn tspySectionFileSaveXML(section_file: *mut c_void, name: *const u8, size: usize) -> bool;
    pub fn tspySectionFileSaveJSON(section_file: *mut c_void, name: *const u8, size: usize)
    -> bool;
    pub fn tspySectionFileToXML(
        section_file: *mut c_void,
        buffer: *mut u8,
        size: *mut usize,
    ) -> usize;
    pub fn tspySectionFileToJSON(
        section_file: *mut c_void,
        buffer: *mut u8,
        size: *mut usize,
    ) -> usize;
    pub fn tspySectionFileReorganizeEITs(
        section_file: *mut c_void,
        year: i32,
        month: i32,
        day: i32,
    );

    pub fn tspyNewSystemMonitor(
        report: *mut c_void,
        config: *const u8,
        config_size: usize,
    ) -> *mut c_void;
    pub fn tspyDeleteSystemMonitor(monitor: *mut c_void);
    pub fn tspyStartSystemMonitor(monitor: *mut c_void);
    pub fn tspyStopSystemMonitor(monitor: *mut c_void);
    pub fn tspyWaitSystemMonitor(monitor: *mut c_void);

    pub fn tspyPluginEventHandlerRegister(
        registry: *mut c_void,
        handler: *mut c_void,
        event_code: u32,
    );
    pub fn tspyPluginEventHandlerRegisterInput(registry: *mut c_void, handler: *mut c_void);
    pub fn tspyPluginEventHandlerRegisterOutput(registry: *mut c_void, handler: *mut c_void);

    pub fn tspyNewTSProcessor(report: *mut c_void) -> *mut c_void;
    pub fn tspyDeleteTSProcessor(processor: *mut c_void);
    pub fn tspyStartTSProcessor(processor: *mut c_void, args: *const TSProcessorArgs) -> bool;
    pub fn tspyAbortTSProcessor(processor: *mut c_void);
    pub fn tspyWaitTSProcessor(processor: *mut c_void);

    pub fn tspyNewInputSwitcher(report: *mut c_void) -> *mut c_void;
    pub fn tspyDeleteInputSwitcher(switcher: *mut c_void);
    pub fn tspyStartInputSwitcher(switcher: *mut c_void, args: *const InputSwitcherArgs) -> bool;
    pub fn tspyInputSwitcherSetInput(switcher: *mut c_void, index: usize);
    pub fn tspyInputSwitcherNextInput(switcher: *mut c_void);
    pub fn tspyInputSwitcherPreviousInput(switcher: *mut c_void);
    pub fn tspyInputSwitcherCurrentInput(switcher: *mut c_void) -> usize;
    pub fn tspyStopInputSwitcher(switcher: *mut c_void);
    pub fn tspyWaitInputSwitcher(switcher: *mut c_void);

}