split crate into own repository

src/bitmap.rs

@@ -0,0 +1,296 @@
+//! C functions for interacting with [SPBitmap]s
+//!
+//! prefix `sp_bitmap_`
+
+use servicepoint::{DataRef, Grid};
+use std::ptr::NonNull;
+
+use crate::byte_slice::SPByteSlice;
+
+/// A grid of pixels.
+///
+/// # Examples
+///
+/// ```C
+/// Cp437Grid grid = sp_bitmap_new(8, 3);
+/// sp_bitmap_fill(grid, true);
+/// sp_bitmap_set(grid, 0, 0, false);
+/// sp_bitmap_free(grid);
+/// ```
+pub struct SPBitmap(pub(crate) servicepoint::Bitmap);
+
+/// Creates a new [SPBitmap] with the specified dimensions.
+///
+/// # Arguments
+///
+/// - `width`: size in pixels in x-direction
+/// - `height`: size in pixels in y-direction
+///
+/// returns: [SPBitmap] initialized to all pixels off. Will never return NULL.
+///
+/// # Panics
+///
+/// - when the width is not dividable by 8
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - the returned instance is freed in some way, either by using a consuming function or
+///   by explicitly calling `sp_bitmap_free`.
+#[no_mangle]
+pub unsafe extern "C" fn sp_bitmap_new(
+    width: usize,
+    height: usize,
+) -> NonNull<SPBitmap> {
+    let result = Box::new(SPBitmap(servicepoint::Bitmap::new(width, height)));
+    NonNull::from(Box::leak(result))
+}
+
+/// Creates a new [SPBitmap] with a size matching the screen.
+///
+/// returns: [SPBitmap] initialized to all pixels off. Will never return NULL.
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - the returned instance is freed in some way, either by using a consuming function or
+///   by explicitly calling [sp_bitmap_free].
+#[no_mangle]
+pub unsafe extern "C" fn sp_bitmap_new_screen_sized() -> NonNull<SPBitmap> {
+    let result = Box::new(SPBitmap(servicepoint::Bitmap::max_sized()));
+    NonNull::from(Box::leak(result))
+}
+
+/// Loads a [SPBitmap] with the specified dimensions from the provided data.
+///
+/// # Arguments
+///
+/// - `width`: size in pixels in x-direction
+/// - `height`: size in pixels in y-direction
+///
+/// returns: [SPBitmap] that contains a copy of the provided data. Will never return NULL.
+///
+/// # Panics
+///
+/// - when `data` is NULL
+/// - when the dimensions and data size do not match exactly.
+/// - when the width is not dividable by 8
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - `data` points to a valid memory location of at least `data_length` bytes in size.
+/// - the returned instance is freed in some way, either by using a consuming function or
+///   by explicitly calling `sp_bitmap_free`.
+#[no_mangle]
+pub unsafe extern "C" fn sp_bitmap_load(
+    width: usize,
+    height: usize,
+    data: *const u8,
+    data_length: usize,
+) -> NonNull<SPBitmap> {
+    assert!(!data.is_null());
+    let data = std::slice::from_raw_parts(data, data_length);
+    let result =
+        Box::new(SPBitmap(servicepoint::Bitmap::load(width, height, data)));
+    NonNull::from(Box::leak(result))
+}
+
+/// Clones a [SPBitmap].
+///
+/// Will never return NULL.
+///
+/// # Panics
+///
+/// - when `bitmap` is NULL
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - `bitmap` points to a valid [SPBitmap]
+/// - `bitmap` is not written to concurrently
+/// - the returned instance is freed in some way, either by using a consuming function or
+///   by explicitly calling `sp_bitmap_free`.
+#[no_mangle]
+pub unsafe extern "C" fn sp_bitmap_clone(
+    bitmap: *const SPBitmap,
+) -> NonNull<SPBitmap> {
+    assert!(!bitmap.is_null());
+    let result = Box::new(SPBitmap((*bitmap).0.clone()));
+    NonNull::from(Box::leak(result))
+}
+
+/// Deallocates a [SPBitmap].
+///
+/// # Panics
+///
+/// - when `bitmap` is NULL
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - `bitmap` points to a valid [SPBitmap]
+/// - `bitmap` is not used concurrently or after bitmap call
+/// - `bitmap` was not passed to another consuming function, e.g. to create a [SPCommand]
+///
+/// [SPCommand]: [crate::SPCommand]
+#[no_mangle]
+pub unsafe extern "C" fn sp_bitmap_free(bitmap: *mut SPBitmap) {
+    assert!(!bitmap.is_null());
+    _ = Box::from_raw(bitmap);
+}
+
+/// Gets the current value at the specified position in the [SPBitmap].
+///
+/// # Arguments
+///
+/// - `bitmap`: instance to read from
+/// - `x` and `y`: position of the cell to read
+///
+/// # Panics
+///
+/// - when `bitmap` is NULL
+/// - when accessing `x` or `y` out of bounds
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - `bitmap` points to a valid [SPBitmap]
+/// - `bitmap` is not written to concurrently
+#[no_mangle]
+pub unsafe extern "C" fn sp_bitmap_get(
+    bitmap: *const SPBitmap,
+    x: usize,
+    y: usize,
+) -> bool {
+    assert!(!bitmap.is_null());
+    (*bitmap).0.get(x, y)
+}
+
+/// Sets the value of the specified position in the [SPBitmap].
+///
+/// # Arguments
+///
+/// - `bitmap`: instance to write to
+/// - `x` and `y`: position of the cell
+/// - `value`: the value to write to the cell
+///
+/// returns: old value of the cell
+///
+/// # Panics
+///
+/// - when `bitmap` is NULL
+/// - when accessing `x` or `y` out of bounds
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - `bitmap` points to a valid [SPBitmap]
+/// - `bitmap` is not written to or read from concurrently
+#[no_mangle]
+pub unsafe extern "C" fn sp_bitmap_set(
+    bitmap: *mut SPBitmap,
+    x: usize,
+    y: usize,
+    value: bool,
+) {
+    assert!(!bitmap.is_null());
+    (*bitmap).0.set(x, y, value);
+}
+
+/// Sets the state of all pixels in the [SPBitmap].
+///
+/// # Arguments
+///
+/// - `bitmap`: instance to write to
+/// - `value`: the value to set all pixels to
+///
+/// # Panics
+///
+/// - when `bitmap` is NULL
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - `bitmap` points to a valid [SPBitmap]
+/// - `bitmap` is not written to or read from concurrently
+#[no_mangle]
+pub unsafe extern "C" fn sp_bitmap_fill(bitmap: *mut SPBitmap, value: bool) {
+    assert!(!bitmap.is_null());
+    (*bitmap).0.fill(value);
+}
+
+/// Gets the width in pixels of the [SPBitmap] instance.
+///
+/// # Arguments
+///
+/// - `bitmap`: instance to read from
+///
+/// # Panics
+///
+/// - when `bitmap` is NULL
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - `bitmap` points to a valid [SPBitmap]
+#[no_mangle]
+pub unsafe extern "C" fn sp_bitmap_width(bitmap: *const SPBitmap) -> usize {
+    assert!(!bitmap.is_null());
+    (*bitmap).0.width()
+}
+
+/// Gets the height in pixels of the [SPBitmap] instance.
+///
+/// # Arguments
+///
+/// - `bitmap`: instance to read from
+///
+/// # Panics
+///
+/// - when `bitmap` is NULL
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - `bitmap` points to a valid [SPBitmap]
+#[no_mangle]
+pub unsafe extern "C" fn sp_bitmap_height(bitmap: *const SPBitmap) -> usize {
+    assert!(!bitmap.is_null());
+    (*bitmap).0.height()
+}
+
+/// Gets an unsafe reference to the data of the [SPBitmap] instance.
+///
+/// # Panics
+///
+/// - when `bitmap` is NULL
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - `bitmap` points to a valid [SPBitmap]
+/// - the returned memory range is never accessed after the passed [SPBitmap] has been freed
+/// - the returned memory range is never accessed concurrently, either via the [SPBitmap] or directly
+#[no_mangle]
+pub unsafe extern "C" fn sp_bitmap_unsafe_data_ref(
+    bitmap: *mut SPBitmap,
+) -> SPByteSlice {
+    assert!(!bitmap.is_null());
+    let data = (*bitmap).0.data_ref_mut();
+    SPByteSlice {
+        start: NonNull::new(data.as_mut_ptr_range().start).unwrap(),
+        length: data.len(),
+    }
+}

src/bitvec.rs

@@ -0,0 +1,283 @@
+//! C functions for interacting with [SPBitVec]s
+//!
+//! prefix `sp_bitvec_`
+
+use crate::SPByteSlice;
+use std::ptr::NonNull;
+
+/// A vector of bits
+///
+/// # Examples
+/// ```C
+/// SPBitVec vec = sp_bitvec_new(8);
+/// sp_bitvec_set(vec, 5, true);
+/// sp_bitvec_free(vec);
+/// ```
+pub struct SPBitVec(servicepoint::BitVec);
+
+impl From<servicepoint::BitVec> for SPBitVec {
+    fn from(actual: servicepoint::BitVec) -> Self {
+        Self(actual)
+    }
+}
+
+impl From<SPBitVec> for servicepoint::BitVec {
+    fn from(value: SPBitVec) -> Self {
+        value.0
+    }
+}
+
+impl Clone for SPBitVec {
+    fn clone(&self) -> Self {
+        SPBitVec(self.0.clone())
+    }
+}
+
+/// Creates a new [SPBitVec] instance.
+///
+/// # Arguments
+///
+/// - `size`: size in bits.
+///
+/// returns: [SPBitVec] with all bits set to false. Will never return NULL.
+///
+/// # Panics
+///
+/// - when `size` is not divisible by 8.
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - the returned instance is freed in some way, either by using a consuming function or
+///   by explicitly calling `sp_bitvec_free`.
+#[no_mangle]
+pub unsafe extern "C" fn sp_bitvec_new(size: usize) -> NonNull<SPBitVec> {
+    let result = Box::new(SPBitVec(servicepoint::BitVec::repeat(false, size)));
+    NonNull::from(Box::leak(result))
+}
+
+/// Interpret the data as a series of bits and load then into a new [SPBitVec] instance.
+///
+/// returns: [SPBitVec] instance containing data. Will never return NULL.
+///
+/// # Panics
+///
+/// - when `data` is NULL
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - `data` points to a valid memory location of at least `data_length`
+///   bytes in size.
+/// - the returned instance is freed in some way, either by using a consuming function or
+///   by explicitly calling `sp_bitvec_free`.
+#[no_mangle]
+pub unsafe extern "C" fn sp_bitvec_load(
+    data: *const u8,
+    data_length: usize,
+) -> NonNull<SPBitVec> {
+    assert!(!data.is_null());
+    let data = std::slice::from_raw_parts(data, data_length);
+    let result = Box::new(SPBitVec(servicepoint::BitVec::from_slice(data)));
+    NonNull::from(Box::leak(result))
+}
+
+/// Clones a [SPBitVec].
+///
+/// returns: new [SPBitVec] instance. Will never return NULL.
+///
+/// # Panics
+///
+/// - when `bit_vec` is NULL
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - `bit_vec` points to a valid [SPBitVec]
+/// - `bit_vec` is not written to concurrently
+/// - the returned instance is freed in some way, either by using a consuming function or
+///   by explicitly calling `sp_bitvec_free`.
+#[no_mangle]
+pub unsafe extern "C" fn sp_bitvec_clone(
+    bit_vec: *const SPBitVec,
+) -> NonNull<SPBitVec> {
+    assert!(!bit_vec.is_null());
+    let result = Box::new((*bit_vec).clone());
+    NonNull::from(Box::leak(result))
+}
+
+/// Deallocates a [SPBitVec].
+///
+/// # Panics
+///
+/// - when `but_vec` is NULL
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - `bit_vec` points to a valid [SPBitVec]
+/// - `bit_vec` is not used concurrently or after this call
+/// - `bit_vec` was not passed to another consuming function, e.g. to create a [SPCommand]
+///
+/// [SPCommand]: [crate::SPCommand]
+#[no_mangle]
+pub unsafe extern "C" fn sp_bitvec_free(bit_vec: *mut SPBitVec) {
+    assert!(!bit_vec.is_null());
+    _ = Box::from_raw(bit_vec);
+}
+
+/// Gets the value of a bit from the [SPBitVec].
+///
+/// # Arguments
+///
+/// - `bit_vec`: instance to read from
+/// - `index`: the bit index to read
+///
+/// returns: value of the bit
+///
+/// # Panics
+///
+/// - when `bit_vec` is NULL
+/// - when accessing `index` out of bounds
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - `bit_vec` points to a valid [SPBitVec]
+/// - `bit_vec` is not written to concurrently
+#[no_mangle]
+pub unsafe extern "C" fn sp_bitvec_get(
+    bit_vec: *const SPBitVec,
+    index: usize,
+) -> bool {
+    assert!(!bit_vec.is_null());
+    *(*bit_vec).0.get(index).unwrap()
+}
+
+/// Sets the value of a bit in the [SPBitVec].
+///
+/// # Arguments
+///
+/// - `bit_vec`: instance to write to
+/// - `index`: the bit index to edit
+/// - `value`: the value to set the bit to
+///
+/// # Panics
+///
+/// - when `bit_vec` is NULL
+/// - when accessing `index` out of bounds
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - `bit_vec` points to a valid [SPBitVec]
+/// - `bit_vec` is not written to or read from concurrently
+#[no_mangle]
+pub unsafe extern "C" fn sp_bitvec_set(
+    bit_vec: *mut SPBitVec,
+    index: usize,
+    value: bool,
+) {
+    assert!(!bit_vec.is_null());
+    (*bit_vec).0.set(index, value)
+}
+
+/// Sets the value of all bits in the [SPBitVec].
+///
+/// # Arguments
+///
+/// - `bit_vec`: instance to write to
+/// - `value`: the value to set all bits to
+///
+/// # Panics
+///
+/// - when `bit_vec` is NULL
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - `bit_vec` points to a valid [SPBitVec]
+/// - `bit_vec` is not written to or read from concurrently
+#[no_mangle]
+pub unsafe extern "C" fn sp_bitvec_fill(bit_vec: *mut SPBitVec, value: bool) {
+    assert!(!bit_vec.is_null());
+    (*bit_vec).0.fill(value)
+}
+
+/// Gets the length of the [SPBitVec] in bits.
+///
+/// # Arguments
+///
+/// - `bit_vec`: instance to write to
+///
+/// # Panics
+///
+/// - when `bit_vec` is NULL
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - `bit_vec` points to a valid [SPBitVec]
+#[no_mangle]
+pub unsafe extern "C" fn sp_bitvec_len(bit_vec: *const SPBitVec) -> usize {
+    assert!(!bit_vec.is_null());
+    (*bit_vec).0.len()
+}
+
+/// Returns true if length is 0.
+///
+/// # Arguments
+///
+/// - `bit_vec`: instance to write to
+///
+/// # Panics
+///
+/// - when `bit_vec` is NULL
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - `bit_vec` points to a valid [SPBitVec]
+#[no_mangle]
+pub unsafe extern "C" fn sp_bitvec_is_empty(bit_vec: *const SPBitVec) -> bool {
+    assert!(!bit_vec.is_null());
+    (*bit_vec).0.is_empty()
+}
+
+/// Gets an unsafe reference to the data of the [SPBitVec] instance.
+///
+/// # Arguments
+///
+/// - `bit_vec`: instance to write to
+///
+/// # Panics
+///
+/// - when `bit_vec` is NULL
+///
+/// ## Safety
+///
+/// The caller has to make sure that:
+///
+/// - `bit_vec` points to a valid [SPBitVec]
+/// - the returned memory range is never accessed after the passed [SPBitVec] has been freed
+/// - the returned memory range is never accessed concurrently, either via the [SPBitVec] or directly
+#[no_mangle]
+pub unsafe extern "C" fn sp_bitvec_unsafe_data_ref(
+    bit_vec: *mut SPBitVec,
+) -> SPByteSlice {
+    assert!(!bit_vec.is_null());
+    let data = (*bit_vec).0.as_raw_mut_slice();
+    SPByteSlice {
+        start: NonNull::new(data.as_mut_ptr_range().start).unwrap(),
+        length: data.len(),
+    }
+}

src/brightness_grid.rs

@@ -0,0 +1,322 @@
+//! C functions for interacting with [SPBrightnessGrid]s
+//!
+//! prefix `sp_brightness_grid_`
+
+use crate::SPByteSlice;
+use servicepoint::{DataRef, Grid};
+use std::convert::Into;
+use std::intrinsics::transmute;
+use std::ptr::NonNull;
+
+/// see [servicepoint::Brightness::MIN]
+pub const SP_BRIGHTNESS_MIN: u8 = 0;
+/// see [servicepoint::Brightness::MAX]
+pub const SP_BRIGHTNESS_MAX: u8 = 11;
+/// Count of possible brightness values
+pub const SP_BRIGHTNESS_LEVELS: u8 = 12;
+
+/// A grid containing brightness values.
+///
+/// # Examples
+/// ```C
+/// SPConnection connection = sp_connection_open("127.0.0.1:2342");
+/// if (connection == NULL)
+///     return 1;
+///
+/// SPBrightnessGrid grid = sp_brightness_grid_new(2, 2);
+/// sp_brightness_grid_set(grid, 0, 0, 0);
+/// sp_brightness_grid_set(grid, 1, 1, 10);
+///
+/// SPCommand command = sp_command_char_brightness(grid);
+/// sp_connection_free(connection);
+/// ```
+#[derive(Clone)]
+pub struct SPBrightnessGrid(pub(crate) servicepoint::BrightnessGrid);
+
+/// Creates a new [SPBrightnessGrid] with the specified dimensions.
+///
+/// returns: [SPBrightnessGrid] initialized to 0. Will never return NULL.
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - the returned instance is freed in some way, either by using a consuming function or
+///   by explicitly calling `sp_brightness_grid_free`.
+#[no_mangle]
+pub unsafe extern "C" fn sp_brightness_grid_new(
+    width: usize,
+    height: usize,
+) -> NonNull<SPBrightnessGrid> {
+    let result = Box::new(SPBrightnessGrid(servicepoint::BrightnessGrid::new(
+        width, height,
+    )));
+    NonNull::from(Box::leak(result))
+}
+
+/// Loads a [SPBrightnessGrid] with the specified dimensions from the provided data.
+///
+/// returns: new [SPBrightnessGrid] instance. Will never return NULL.
+///
+/// # Panics
+///
+/// - when `data` is NULL
+/// - when the provided `data_length` does not match `height` and `width`
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - `data` points to a valid memory location of at least `data_length`
+///   bytes in size.
+/// - the returned instance is freed in some way, either by using a consuming function or
+///   by explicitly calling `sp_brightness_grid_free`.
+#[no_mangle]
+pub unsafe extern "C" fn sp_brightness_grid_load(
+    width: usize,
+    height: usize,
+    data: *const u8,
+    data_length: usize,
+) -> NonNull<SPBrightnessGrid> {
+    assert!(!data.is_null());
+    let data = std::slice::from_raw_parts(data, data_length);
+    let grid = servicepoint::ByteGrid::load(width, height, data);
+    let grid = servicepoint::BrightnessGrid::try_from(grid)
+        .expect("invalid brightness value");
+    let result = Box::new(SPBrightnessGrid(grid));
+    NonNull::from(Box::leak(result))
+}
+
+/// Clones a [SPBrightnessGrid].
+///
+/// # Arguments
+///
+/// - `brightness_grid`: instance to read from
+///
+/// returns: new [SPBrightnessGrid] instance. Will never return NULL.
+///
+/// # Panics
+///
+/// - when `brightness_grid` is NULL
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - `brightness_grid` points to a valid [SPBrightnessGrid]
+/// - `brightness_grid` is not written to concurrently
+/// - the returned instance is freed in some way, either by using a consuming function or
+///   by explicitly calling `sp_brightness_grid_free`.
+#[no_mangle]
+pub unsafe extern "C" fn sp_brightness_grid_clone(
+    brightness_grid: *const SPBrightnessGrid,
+) -> NonNull<SPBrightnessGrid> {
+    assert!(!brightness_grid.is_null());
+    let result = Box::new((*brightness_grid).clone());
+    NonNull::from(Box::leak(result))
+}
+
+/// Deallocates a [SPBrightnessGrid].
+///
+/// # Arguments
+///
+/// - `brightness_grid`: instance to read from
+///
+/// # Panics
+///
+/// - when `brightness_grid` is NULL
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - `brightness_grid` points to a valid [SPBrightnessGrid]
+/// - `brightness_grid` is not used concurrently or after this call
+/// - `brightness_grid` was not passed to another consuming function, e.g. to create a [SPCommand]
+///
+/// [SPCommand]: [crate::SPCommand]
+#[no_mangle]
+pub unsafe extern "C" fn sp_brightness_grid_free(
+    brightness_grid: *mut SPBrightnessGrid,
+) {
+    assert!(!brightness_grid.is_null());
+    _ = Box::from_raw(brightness_grid);
+}
+
+/// Gets the current value at the specified position.
+///
+/// # Arguments
+///
+/// - `brightness_grid`: instance to read from
+/// - `x` and `y`: position of the cell to read
+///
+/// returns: value at position
+///
+/// # Panics
+///
+/// - when `brightness_grid` is NULL
+/// - When accessing `x` or `y` out of bounds.
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - `brightness_grid` points to a valid [SPBrightnessGrid]
+/// - `brightness_grid` is not written to concurrently
+#[no_mangle]
+pub unsafe extern "C" fn sp_brightness_grid_get(
+    brightness_grid: *const SPBrightnessGrid,
+    x: usize,
+    y: usize,
+) -> u8 {
+    assert!(!brightness_grid.is_null());
+    (*brightness_grid).0.get(x, y).into()
+}
+
+/// Sets the value of the specified position in the [SPBrightnessGrid].
+///
+/// # Arguments
+///
+/// - `brightness_grid`: instance to write to
+/// - `x` and `y`: position of the cell
+/// - `value`: the value to write to the cell
+///
+/// returns: old value of the cell
+///
+/// # Panics
+///
+/// - when `brightness_grid` is NULL
+/// - When accessing `x` or `y` out of bounds.
+/// - When providing an invalid brightness value
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - `brightness_grid` points to a valid [SPBrightnessGrid]
+/// - `brightness_grid` is not written to or read from concurrently
+#[no_mangle]
+pub unsafe extern "C" fn sp_brightness_grid_set(
+    brightness_grid: *mut SPBrightnessGrid,
+    x: usize,
+    y: usize,
+    value: u8,
+) {
+    assert!(!brightness_grid.is_null());
+    let brightness = servicepoint::Brightness::try_from(value)
+        .expect("invalid brightness value");
+    (*brightness_grid).0.set(x, y, brightness);
+}
+
+/// Sets the value of all cells in the [SPBrightnessGrid].
+///
+/// # Arguments
+///
+/// - `brightness_grid`: instance to write to
+/// - `value`: the value to set all cells to
+///
+/// # Panics
+///
+/// - when `brightness_grid` is NULL
+/// - When providing an invalid brightness value
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - `brightness_grid` points to a valid [SPBrightnessGrid]
+/// - `brightness_grid` is not written to or read from concurrently
+#[no_mangle]
+pub unsafe extern "C" fn sp_brightness_grid_fill(
+    brightness_grid: *mut SPBrightnessGrid,
+    value: u8,
+) {
+    assert!(!brightness_grid.is_null());
+    let brightness = servicepoint::Brightness::try_from(value)
+        .expect("invalid brightness value");
+    (*brightness_grid).0.fill(brightness);
+}
+
+/// Gets the width of the [SPBrightnessGrid] instance.
+///
+/// # Arguments
+///
+/// - `brightness_grid`: instance to read from
+///
+/// returns: width
+///
+/// # Panics
+///
+/// - when `brightness_grid` is NULL
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - `brightness_grid` points to a valid [SPBrightnessGrid]
+#[no_mangle]
+pub unsafe extern "C" fn sp_brightness_grid_width(
+    brightness_grid: *const SPBrightnessGrid,
+) -> usize {
+    assert!(!brightness_grid.is_null());
+    (*brightness_grid).0.width()
+}
+
+/// Gets the height of the [SPBrightnessGrid] instance.
+///
+/// # Arguments
+///
+/// - `brightness_grid`: instance to read from
+///
+/// returns: height
+///
+/// # Panics
+///
+/// - when `brightness_grid` is NULL
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - `brightness_grid` points to a valid [SPBrightnessGrid]
+#[no_mangle]
+pub unsafe extern "C" fn sp_brightness_grid_height(
+    brightness_grid: *const SPBrightnessGrid,
+) -> usize {
+    assert!(!brightness_grid.is_null());
+    (*brightness_grid).0.height()
+}
+
+/// Gets an unsafe reference to the data of the [SPBrightnessGrid] instance.
+///
+/// # Arguments
+///
+/// - `brightness_grid`: instance to read from
+///
+/// returns: slice of bytes underlying the `brightness_grid`.
+///
+/// # Panics
+///
+/// - when `brightness_grid` is NULL
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - `brightness_grid` points to a valid [SPBrightnessGrid]
+/// - the returned memory range is never accessed after the passed [SPBrightnessGrid] has been freed
+/// - the returned memory range is never accessed concurrently, either via the [SPBrightnessGrid] or directly
+#[no_mangle]
+pub unsafe extern "C" fn sp_brightness_grid_unsafe_data_ref(
+    brightness_grid: *mut SPBrightnessGrid,
+) -> SPByteSlice {
+    assert!(!brightness_grid.is_null());
+    assert_eq!(core::mem::size_of::<servicepoint::Brightness>(), 1);
+    let data = (*brightness_grid).0.data_ref_mut();
+    // this assumes more about the memory layout than rust guarantees. yikes!
+    let data: &mut [u8] = transmute(data);
+    SPByteSlice {
+        start: NonNull::new(data.as_mut_ptr_range().start).unwrap(),
+        length: data.len(),
+    }
+}

src/byte_slice.rs

@@ -0,0 +1,24 @@
+//! FFI slice helper
+
+use std::ptr::NonNull;
+
+#[repr(C)]
+/// Represents a span of memory (`&mut [u8]` ) as a struct usable by C code.
+///
+/// You should not create an instance of this type in your C code.
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - accesses to the memory pointed to with `start` is never accessed outside `length`
+/// - the lifetime of the `CByteSlice` does not outlive the memory it points to, as described in
+///   the function returning this type.
+/// - an instance of this created from C is never passed to a consuming function, as the rust code
+///   will try to free the memory of a potentially separate allocator.
+pub struct SPByteSlice {
+    /// The start address of the memory
+    pub start: NonNull<u8>,
+    /// The amount of memory in bytes
+    pub length: usize,
+}

src/char_grid.rs

@@ -0,0 +1,263 @@
+//! C functions for interacting with [SPCharGrid]s
+//!
+//! prefix `sp_char_grid_`
+
+use servicepoint::Grid;
+use std::ptr::NonNull;
+
+/// A C-wrapper for grid containing UTF-8 characters.
+///
+/// As the rust [char] type is not FFI-safe, characters are passed in their UTF-32 form as 32bit unsigned integers.
+///
+/// The encoding is enforced in most cases by the rust standard library
+/// and will panic when provided with illegal characters.
+///
+/// # Examples
+///
+/// ```C
+/// CharGrid grid = sp_char_grid_new(4, 3);
+/// sp_char_grid_fill(grid, '?');
+/// sp_char_grid_set(grid, 0, 0, '!');
+/// sp_char_grid_free(grid);
+/// ```
+pub struct SPCharGrid(pub(crate) servicepoint::CharGrid);
+
+impl Clone for SPCharGrid {
+    fn clone(&self) -> Self {
+        SPCharGrid(self.0.clone())
+    }
+}
+
+/// Creates a new [SPCharGrid] with the specified dimensions.
+///
+/// returns: [SPCharGrid] initialized to 0. Will never return NULL.
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - the returned instance is freed in some way, either by using a consuming function or
+///   by explicitly calling `sp_char_grid_free`.
+#[no_mangle]
+pub unsafe extern "C" fn sp_char_grid_new(
+    width: usize,
+    height: usize,
+) -> NonNull<SPCharGrid> {
+    let result =
+        Box::new(SPCharGrid(servicepoint::CharGrid::new(width, height)));
+    NonNull::from(Box::leak(result))
+}
+
+/// Loads a [SPCharGrid] with the specified dimensions from the provided data.
+///
+/// Will never return NULL.
+///
+/// # Panics
+///
+/// - when `data` is NULL
+/// - when the provided `data_length` does not match `height` and `width`
+/// - when `data` is not valid UTF-8
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - `data` points to a valid memory location of at least `data_length`
+///   bytes in size.
+/// - the returned instance is freed in some way, either by using a consuming function or
+///   by explicitly calling `sp_char_grid_free`.
+#[no_mangle]
+pub unsafe extern "C" fn sp_char_grid_load(
+    width: usize,
+    height: usize,
+    data: *const u8,
+    data_length: usize,
+) -> NonNull<SPCharGrid> {
+    assert!(data.is_null());
+    let data = std::slice::from_raw_parts(data, data_length);
+    let result = Box::new(SPCharGrid(
+        servicepoint::CharGrid::load_utf8(width, height, data.to_vec())
+            .unwrap(),
+    ));
+    NonNull::from(Box::leak(result))
+}
+
+/// Clones a [SPCharGrid].
+///
+/// Will never return NULL.
+///
+/// # Panics
+///
+/// - when `char_grid` is NULL
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - `char_grid` points to a valid [SPCharGrid]
+/// - `char_grid` is not written to concurrently
+/// - the returned instance is freed in some way, either by using a consuming function or
+///   by explicitly calling `sp_char_grid_free`.
+#[no_mangle]
+pub unsafe extern "C" fn sp_char_grid_clone(
+    char_grid: *const SPCharGrid,
+) -> NonNull<SPCharGrid> {
+    assert!(!char_grid.is_null());
+    let result = Box::new((*char_grid).clone());
+    NonNull::from(Box::leak(result))
+}
+
+/// Deallocates a [SPCharGrid].
+///
+/// # Panics
+///
+/// - when `char_grid` is NULL
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - `char_grid` points to a valid [SPCharGrid]
+/// - `char_grid` is not used concurrently or after char_grid call
+/// - `char_grid` was not passed to another consuming function, e.g. to create a [SPCommand]
+///
+/// [SPCommand]: [crate::SPCommand]
+#[no_mangle]
+pub unsafe extern "C" fn sp_char_grid_free(char_grid: *mut SPCharGrid) {
+    assert!(!char_grid.is_null());
+    _ = Box::from_raw(char_grid);
+}
+
+/// Gets the current value at the specified position.
+///
+/// # Arguments
+///
+/// - `char_grid`: instance to read from
+/// - `x` and `y`: position of the cell to read
+///
+/// # Panics
+///
+/// - when `char_grid` is NULL
+/// - when accessing `x` or `y` out of bounds
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - `char_grid` points to a valid [SPCharGrid]
+/// - `char_grid` is not written to concurrently
+#[no_mangle]
+pub unsafe extern "C" fn sp_char_grid_get(
+    char_grid: *const SPCharGrid,
+    x: usize,
+    y: usize,
+) -> u32 {
+    assert!(!char_grid.is_null());
+    (*char_grid).0.get(x, y) as u32
+}
+
+/// Sets the value of the specified position in the [SPCharGrid].
+///
+/// # Arguments
+///
+/// - `char_grid`: instance to write to
+/// - `x` and `y`: position of the cell
+/// - `value`: the value to write to the cell
+///
+/// returns: old value of the cell
+///
+/// # Panics
+///
+/// - when `char_grid` is NULL
+/// - when accessing `x` or `y` out of bounds
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - `char_grid` points to a valid [SPBitVec]
+/// - `char_grid` is not written to or read from concurrently
+///
+/// [SPBitVec]: [crate::SPBitVec]
+#[no_mangle]
+pub unsafe extern "C" fn sp_char_grid_set(
+    char_grid: *mut SPCharGrid,
+    x: usize,
+    y: usize,
+    value: u32,
+) {
+    assert!(!char_grid.is_null());
+    (*char_grid).0.set(x, y, char::from_u32(value).unwrap());
+}
+
+/// Sets the value of all cells in the [SPCharGrid].
+///
+/// # Arguments
+///
+/// - `char_grid`: instance to write to
+/// - `value`: the value to set all cells to
+///
+/// # Panics
+///
+/// - when `char_grid` is NULL
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - `char_grid` points to a valid [SPCharGrid]
+/// - `char_grid` is not written to or read from concurrently
+#[no_mangle]
+pub unsafe extern "C" fn sp_char_grid_fill(
+    char_grid: *mut SPCharGrid,
+    value: u32,
+) {
+    assert!(!char_grid.is_null());
+    (*char_grid).0.fill(char::from_u32(value).unwrap());
+}
+
+/// Gets the width of the [SPCharGrid] instance.
+///
+/// # Arguments
+///
+/// - `char_grid`: instance to read from
+///
+/// # Panics
+///
+/// - when `char_grid` is NULL
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - `char_grid` points to a valid [SPCharGrid]
+#[no_mangle]
+pub unsafe extern "C" fn sp_char_grid_width(
+    char_grid: *const SPCharGrid,
+) -> usize {
+    assert!(!char_grid.is_null());
+    (*char_grid).0.width()
+}
+
+/// Gets the height of the [SPCharGrid] instance.
+///
+/// # Arguments
+///
+/// - `char_grid`: instance to read from
+///
+/// # Panics
+///
+/// - when `char_grid` is NULL
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - `char_grid` points to a valid [SPCharGrid]
+#[no_mangle]
+pub unsafe extern "C" fn sp_char_grid_height(
+    char_grid: *const SPCharGrid,
+) -> usize {
+    assert!(!char_grid.is_null());
+    (*char_grid).0.height()
+}

src/command.rs

@@ -0,0 +1,498 @@
+//! C functions for interacting with [SPCommand]s
+//!
+//! prefix `sp_command_`
+
+use std::ptr::{null_mut, NonNull};
+
+use crate::{
+    SPBitVec, SPBitmap, SPBrightnessGrid, SPCharGrid, SPCompressionCode,
+    SPCp437Grid, SPPacket,
+};
+
+/// A low-level display command.
+///
+/// This struct and associated functions implement the UDP protocol for the display.
+///
+/// To send a [SPCommand], use a [SPConnection].
+///
+/// # Examples
+///
+/// ```C
+/// sp_connection_send_command(connection, sp_command_clear());
+/// sp_connection_send_command(connection, sp_command_brightness(5));
+/// ```
+///
+/// [SPConnection]: [crate::SPConnection]
+pub struct SPCommand(pub(crate) servicepoint::Command);
+
+impl Clone for SPCommand {
+    fn clone(&self) -> Self {
+        SPCommand(self.0.clone())
+    }
+}
+
+/// Tries to turn a [SPPacket] into a [SPCommand].
+///
+/// The packet is deallocated in the process.
+///
+/// Returns: pointer to new [SPCommand] instance or NULL if parsing failed.
+///
+/// # Panics
+///
+/// - when `packet` is NULL
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - [SPPacket] points to a valid instance of [SPPacket]
+/// - [SPPacket] is not used concurrently or after this call
+/// - the result is checked for NULL
+/// - the returned [SPCommand] instance is freed in some way, either by using a consuming function or
+///   by explicitly calling `sp_command_free`.
+#[no_mangle]
+pub unsafe extern "C" fn sp_command_try_from_packet(
+    packet: *mut SPPacket,
+) -> *mut SPCommand {
+    let packet = *Box::from_raw(packet);
+    match servicepoint::Command::try_from(packet.0) {
+        Err(_) => null_mut(),
+        Ok(command) => Box::into_raw(Box::new(SPCommand(command))),
+    }
+}
+
+/// Clones a [SPCommand] instance.
+///
+/// returns: new [SPCommand] instance. Will never return NULL.
+///
+/// # Panics
+///
+/// - when `command` is NULL
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - `command` points to a valid instance of [SPCommand]
+/// - `command` is not written to concurrently
+/// - the returned [SPCommand] instance is freed in some way, either by using a consuming function or
+///   by explicitly calling `sp_command_free`.
+#[no_mangle]
+pub unsafe extern "C" fn sp_command_clone(
+    command: *const SPCommand,
+) -> NonNull<SPCommand> {
+    assert!(!command.is_null());
+    let result = Box::new((*command).clone());
+    NonNull::from(Box::leak(result))
+}
+
+/// Set all pixels to the off state.
+///
+/// Does not affect brightness.
+///
+/// Returns: a new [servicepoint::Command::Clear] instance. Will never return NULL.
+///
+/// # Examples
+///
+/// ```C
+/// sp_connection_send_command(connection, sp_command_clear());
+/// ```
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - the returned [SPCommand] instance is freed in some way, either by using a consuming function or
+///   by explicitly calling `sp_command_free`.
+#[no_mangle]
+pub unsafe extern "C" fn sp_command_clear() -> NonNull<SPCommand> {
+    let result = Box::new(SPCommand(servicepoint::Command::Clear));
+    NonNull::from(Box::leak(result))
+}
+
+/// Kills the udp daemon on the display, which usually results in a restart.
+///
+/// Please do not send this in your normal program flow.
+///
+/// Returns: a new [servicepoint::Command::HardReset] instance. Will never return NULL.
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - the returned [SPCommand] instance is freed in some way, either by using a consuming function or
+///   by explicitly calling `sp_command_free`.
+#[no_mangle]
+pub unsafe extern "C" fn sp_command_hard_reset() -> NonNull<SPCommand> {
+    let result = Box::new(SPCommand(servicepoint::Command::HardReset));
+    NonNull::from(Box::leak(result))
+}
+
+/// A yet-to-be-tested command.
+///
+/// Returns: a new [servicepoint::Command::FadeOut] instance. Will never return NULL.
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - the returned [SPCommand] instance is freed in some way, either by using a consuming function or
+///   by explicitly calling `sp_command_free`.
+#[no_mangle]
+pub unsafe extern "C" fn sp_command_fade_out() -> NonNull<SPCommand> {
+    let result = Box::new(SPCommand(servicepoint::Command::FadeOut));
+    NonNull::from(Box::leak(result))
+}
+
+/// Set the brightness of all tiles to the same value.
+///
+/// Returns: a new [servicepoint::Command::Brightness] instance. Will never return NULL.
+///
+/// # Panics
+///
+/// - When the provided brightness value is out of range (0-11).
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - the returned [SPCommand] instance is freed in some way, either by using a consuming function or
+///   by explicitly calling `sp_command_free`.
+#[no_mangle]
+pub unsafe extern "C" fn sp_command_brightness(
+    brightness: u8,
+) -> NonNull<SPCommand> {
+    let brightness = servicepoint::Brightness::try_from(brightness)
+        .expect("invalid brightness");
+    let result =
+        Box::new(SPCommand(servicepoint::Command::Brightness(brightness)));
+    NonNull::from(Box::leak(result))
+}
+
+/// Set the brightness of individual tiles in a rectangular area of the display.
+///
+/// The passed [SPBrightnessGrid] gets consumed.
+///
+/// Returns: a new [servicepoint::Command::CharBrightness] instance. Will never return NULL.
+///
+/// # Panics
+///
+/// - when `grid` is NULL
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - `grid` points to a valid instance of [SPBrightnessGrid]
+/// - `grid` is not used concurrently or after this call
+/// - the returned [SPCommand] instance is freed in some way, either by using a consuming function or
+///   by explicitly calling `sp_command_free`.
+#[no_mangle]
+pub unsafe extern "C" fn sp_command_char_brightness(
+    x: usize,
+    y: usize,
+    grid: *mut SPBrightnessGrid,
+) -> NonNull<SPCommand> {
+    assert!(!grid.is_null());
+    let byte_grid = *Box::from_raw(grid);
+    let result = Box::new(SPCommand(servicepoint::Command::CharBrightness(
+        servicepoint::Origin::new(x, y),
+        byte_grid.0,
+    )));
+    NonNull::from(Box::leak(result))
+}
+
+/// Set pixel data starting at the pixel offset on screen.
+///
+/// The screen will continuously overwrite more pixel data without regarding the offset, meaning
+/// once the starting row is full, overwriting will continue on column 0.
+///
+/// The contained [SPBitVec] is always uncompressed.
+///
+/// The passed [SPBitVec] gets consumed.
+///
+/// Returns: a new [servicepoint::Command::BitmapLinear] instance. Will never return NULL.
+///
+/// # Panics
+///
+/// - when `bit_vec` is null
+/// - when `compression_code` is not a valid value
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - `bit_vec` points to a valid instance of [SPBitVec]
+/// - `bit_vec` is not used concurrently or after this call
+/// - `compression` matches one of the allowed enum values
+/// - the returned [SPCommand] instance is freed in some way, either by using a consuming function or
+///   by explicitly calling `sp_command_free`.
+#[no_mangle]
+pub unsafe extern "C" fn sp_command_bitmap_linear(
+    offset: usize,
+    bit_vec: *mut SPBitVec,
+    compression: SPCompressionCode,
+) -> NonNull<SPCommand> {
+    assert!(!bit_vec.is_null());
+    let bit_vec = *Box::from_raw(bit_vec);
+    let result = Box::new(SPCommand(servicepoint::Command::BitmapLinear(
+        offset,
+        bit_vec.into(),
+        compression.try_into().expect("invalid compression code"),
+    )));
+    NonNull::from(Box::leak(result))
+}
+
+/// Set pixel data according to an and-mask starting at the offset.
+///
+/// The screen will continuously overwrite more pixel data without regarding the offset, meaning
+/// once the starting row is full, overwriting will continue on column 0.
+///
+/// The contained [SPBitVec] is always uncompressed.
+///
+/// The passed [SPBitVec] gets consumed.
+///
+/// Returns: a new [servicepoint::Command::BitmapLinearAnd] instance. Will never return NULL.
+///
+/// # Panics
+///
+/// - when `bit_vec` is null
+/// - when `compression_code` is not a valid value
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - `bit_vec` points to a valid instance of [SPBitVec]
+/// - `bit_vec` is not used concurrently or after this call
+/// - `compression` matches one of the allowed enum values
+/// - the returned [SPCommand] instance is freed in some way, either by using a consuming function or
+///   by explicitly calling `sp_command_free`.
+#[no_mangle]
+pub unsafe extern "C" fn sp_command_bitmap_linear_and(
+    offset: usize,
+    bit_vec: *mut SPBitVec,
+    compression: SPCompressionCode,
+) -> NonNull<SPCommand> {
+    assert!(!bit_vec.is_null());
+    let bit_vec = *Box::from_raw(bit_vec);
+    let result = Box::new(SPCommand(servicepoint::Command::BitmapLinearAnd(
+        offset,
+        bit_vec.into(),
+        compression.try_into().expect("invalid compression code"),
+    )));
+    NonNull::from(Box::leak(result))
+}
+
+/// Set pixel data according to an or-mask starting at the offset.
+///
+/// The screen will continuously overwrite more pixel data without regarding the offset, meaning
+/// once the starting row is full, overwriting will continue on column 0.
+///
+/// The contained [SPBitVec] is always uncompressed.
+///
+/// The passed [SPBitVec] gets consumed.
+///
+/// Returns: a new [servicepoint::Command::BitmapLinearOr] instance. Will never return NULL.
+///
+/// # Panics
+///
+/// - when `bit_vec` is null
+/// - when `compression_code` is not a valid value
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - `bit_vec` points to a valid instance of [SPBitVec]
+/// - `bit_vec` is not used concurrently or after this call
+/// - `compression` matches one of the allowed enum values
+/// - the returned [SPCommand] instance is freed in some way, either by using a consuming function or
+///   by explicitly calling `sp_command_free`.
+#[no_mangle]
+pub unsafe extern "C" fn sp_command_bitmap_linear_or(
+    offset: usize,
+    bit_vec: *mut SPBitVec,
+    compression: SPCompressionCode,
+) -> NonNull<SPCommand> {
+    assert!(!bit_vec.is_null());
+    let bit_vec = *Box::from_raw(bit_vec);
+    let result = Box::new(SPCommand(servicepoint::Command::BitmapLinearOr(
+        offset,
+        bit_vec.into(),
+        compression.try_into().expect("invalid compression code"),
+    )));
+    NonNull::from(Box::leak(result))
+}
+
+/// Set pixel data according to a xor-mask starting at the offset.
+///
+/// The screen will continuously overwrite more pixel data without regarding the offset, meaning
+/// once the starting row is full, overwriting will continue on column 0.
+///
+/// The contained [SPBitVec] is always uncompressed.
+///
+/// The passed [SPBitVec] gets consumed.
+///
+/// Returns: a new [servicepoint::Command::BitmapLinearXor] instance. Will never return NULL.
+///
+/// # Panics
+///
+/// - when `bit_vec` is null
+/// - when `compression_code` is not a valid value
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - `bit_vec` points to a valid instance of [SPBitVec]
+/// - `bit_vec` is not used concurrently or after this call
+/// - `compression` matches one of the allowed enum values
+/// - the returned [SPCommand] instance is freed in some way, either by using a consuming function or
+///   by explicitly calling `sp_command_free`.
+#[no_mangle]
+pub unsafe extern "C" fn sp_command_bitmap_linear_xor(
+    offset: usize,
+    bit_vec: *mut SPBitVec,
+    compression: SPCompressionCode,
+) -> NonNull<SPCommand> {
+    assert!(!bit_vec.is_null());
+    let bit_vec = *Box::from_raw(bit_vec);
+    let result = Box::new(SPCommand(servicepoint::Command::BitmapLinearXor(
+        offset,
+        bit_vec.into(),
+        compression.try_into().expect("invalid compression code"),
+    )));
+    NonNull::from(Box::leak(result))
+}
+
+/// Show codepage 437 encoded text on the screen.
+///
+/// The passed [SPCp437Grid] gets consumed.
+///
+/// Returns: a new [servicepoint::Command::Cp437Data] instance. Will never return NULL.
+///
+/// # Panics
+///
+/// - when `grid` is null
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - `grid` points to a valid instance of [SPCp437Grid]
+/// - `grid` is not used concurrently or after this call
+/// - the returned [SPCommand] instance is freed in some way, either by using a consuming function or
+///   by explicitly calling `sp_command_free`.
+#[no_mangle]
+pub unsafe extern "C" fn sp_command_cp437_data(
+    x: usize,
+    y: usize,
+    grid: *mut SPCp437Grid,
+) -> NonNull<SPCommand> {
+    assert!(!grid.is_null());
+    let grid = *Box::from_raw(grid);
+    let result = Box::new(SPCommand(servicepoint::Command::Cp437Data(
+        servicepoint::Origin::new(x, y),
+        grid.0,
+    )));
+    NonNull::from(Box::leak(result))
+}
+
+/// Show UTF-8 encoded text on the screen.
+///
+/// The passed [SPCharGrid] gets consumed.
+///
+/// Returns: a new [servicepoint::Command::Utf8Data] instance. Will never return NULL.
+///
+/// # Panics
+///
+/// - when `grid` is null
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - `grid` points to a valid instance of [SPCharGrid]
+/// - `grid` is not used concurrently or after this call
+/// - the returned [SPCommand] instance is freed in some way, either by using a consuming function or
+///   by explicitly calling `sp_command_free`.
+#[no_mangle]
+pub unsafe extern "C" fn sp_command_utf8_data(
+    x: usize,
+    y: usize,
+    grid: *mut SPCharGrid,
+) -> NonNull<SPCommand> {
+    assert!(!grid.is_null());
+    let grid = *Box::from_raw(grid);
+    let result = Box::new(SPCommand(servicepoint::Command::Utf8Data(
+        servicepoint::Origin::new(x, y),
+        grid.0,
+    )));
+    NonNull::from(Box::leak(result))
+}
+
+/// Sets a window of pixels to the specified values.
+///
+/// The passed [SPBitmap] gets consumed.
+///
+/// Returns: a new [servicepoint::Command::BitmapLinearWin] instance. Will never return NULL.
+///
+/// # Panics
+///
+/// - when `bitmap` is null
+/// - when `compression_code` is not a valid value
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - `bitmap` points to a valid instance of [SPBitmap]
+/// - `bitmap` is not used concurrently or after this call
+/// - `compression` matches one of the allowed enum values
+/// - the returned [SPCommand] instance is freed in some way, either by using a consuming function or
+///   by explicitly calling `sp_command_free`.
+#[no_mangle]
+pub unsafe extern "C" fn sp_command_bitmap_linear_win(
+    x: usize,
+    y: usize,
+    bitmap: *mut SPBitmap,
+    compression_code: SPCompressionCode,
+) -> NonNull<SPCommand> {
+    assert!(!bitmap.is_null());
+    let byte_grid = (*Box::from_raw(bitmap)).0;
+    let result = Box::new(SPCommand(servicepoint::Command::BitmapLinearWin(
+        servicepoint::Origin::new(x, y),
+        byte_grid,
+        compression_code
+            .try_into()
+            .expect("invalid compression code"),
+    )));
+    NonNull::from(Box::leak(result))
+}
+
+/// Deallocates a [SPCommand].
+///
+/// # Examples
+///
+/// ```C
+/// SPCommand c = sp_command_clear();
+/// sp_command_free(c);
+/// ```
+///
+/// # Panics
+///
+/// - when `command` is NULL
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - `command` points to a valid [SPCommand]
+/// - `command` is not used concurrently or after this call
+/// - `command` was not passed to another consuming function, e.g. to create a [SPPacket]
+#[no_mangle]
+pub unsafe extern "C" fn sp_command_free(command: *mut SPCommand) {
+    assert!(!command.is_null());
+    _ = Box::from_raw(command);
+}

src/connection.rs

@@ -0,0 +1,139 @@
+//! C functions for interacting with [SPConnection]s
+//!
+//! prefix `sp_connection_`
+
+use std::ffi::{c_char, CStr};
+use std::ptr::{null_mut, NonNull};
+
+use crate::{SPCommand, SPPacket};
+
+/// A connection to the display.
+///
+/// # Examples
+///
+/// ```C
+/// CConnection connection = sp_connection_open("172.23.42.29:2342");
+/// if (connection != NULL)
+///     sp_connection_send_command(connection, sp_command_clear());
+/// ```
+pub struct SPConnection(pub(crate) servicepoint::Connection);
+
+/// Creates a new instance of [SPConnection].
+///
+/// returns: NULL if connection fails, or connected instance
+///
+/// # Panics
+///
+/// - when `host` is null or an invalid host
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - the returned instance is freed in some way, either by using a consuming function or
+///   by explicitly calling `sp_connection_free`.
+#[no_mangle]
+pub unsafe extern "C" fn sp_connection_open(
+    host: *const c_char,
+) -> *mut SPConnection {
+    assert!(!host.is_null());
+    let host = CStr::from_ptr(host).to_str().expect("Bad encoding");
+    let connection = match servicepoint::Connection::open(host) {
+        Err(_) => return null_mut(),
+        Ok(value) => value,
+    };
+
+    Box::into_raw(Box::new(SPConnection(connection)))
+}
+
+/// Creates a new instance of [SPConnection] for testing that does not actually send anything.
+///
+/// returns: a new instance. Will never return NULL.
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - the returned instance is freed in some way, either by using a consuming function or
+///   by explicitly calling `sp_connection_free`.
+#[no_mangle]
+pub unsafe extern "C" fn sp_connection_fake() -> NonNull<SPConnection> {
+    let result = Box::new(SPConnection(servicepoint::Connection::Fake));
+    NonNull::from(Box::leak(result))
+}
+
+/// Sends a [SPPacket] to the display using the [SPConnection].
+///
+/// The passed `packet` gets consumed.
+///
+/// returns: true in case of success
+///
+/// # Panics
+///
+/// - when `connection` is NULL
+/// - when `packet` is NULL
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - `connection` points to a valid instance of [SPConnection]
+/// - `packet` points to a valid instance of [SPPacket]
+/// - `packet` is not used concurrently or after this call
+#[no_mangle]
+pub unsafe extern "C" fn sp_connection_send_packet(
+    connection: *const SPConnection,
+    packet: *mut SPPacket,
+) -> bool {
+    assert!(!connection.is_null());
+    assert!(!packet.is_null());
+    let packet = Box::from_raw(packet);
+    (*connection).0.send((*packet).0).is_ok()
+}
+
+/// Sends a [SPCommand] to the display using the [SPConnection].
+///
+/// The passed `command` gets consumed.
+///
+/// returns: true in case of success
+///
+/// # Panics
+///
+/// - when `connection` is NULL
+/// - when `command` is NULL
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - `connection` points to a valid instance of [SPConnection]
+/// - `command` points to a valid instance of [SPPacket]
+/// - `command` is not used concurrently or after this call
+#[no_mangle]
+pub unsafe extern "C" fn sp_connection_send_command(
+    connection: *const SPConnection,
+    command: *mut SPCommand,
+) -> bool {
+    assert!(!connection.is_null());
+    assert!(!command.is_null());
+    let command = (*Box::from_raw(command)).0;
+    (*connection).0.send(command).is_ok()
+}
+
+/// Closes and deallocates a [SPConnection].
+///
+/// # Panics
+///
+/// - when `connection` is NULL
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - `connection` points to a valid [SPConnection]
+/// - `connection` is not used concurrently or after this call
+#[no_mangle]
+pub unsafe extern "C" fn sp_connection_free(connection: *mut SPConnection) {
+    assert!(!connection.is_null());
+    _ = Box::from_raw(connection);
+}

src/constants.rs

@@ -0,0 +1,48 @@
+//! re-exported constants for use in C
+
+use servicepoint::CompressionCode;
+use std::time::Duration;
+
+/// size of a single tile in one dimension
+pub const SP_TILE_SIZE: usize = 8;
+
+/// Display tile count in the x-direction
+pub const SP_TILE_WIDTH: usize = 56;
+
+/// Display tile count in the y-direction
+pub const SP_TILE_HEIGHT: usize = 20;
+
+/// Display width in pixels
+pub const SP_PIXEL_WIDTH: usize = SP_TILE_WIDTH * SP_TILE_SIZE;
+
+/// Display height in pixels
+pub const SP_PIXEL_HEIGHT: usize = SP_TILE_HEIGHT * SP_TILE_SIZE;
+
+/// pixel count on whole screen
+pub const SP_PIXEL_COUNT: usize = SP_PIXEL_WIDTH * SP_PIXEL_HEIGHT;
+
+/// Actual hardware limit is around 28-29ms/frame. Rounded up for less dropped packets.
+pub const SP_FRAME_PACING_MS: u128 = Duration::from_millis(30).as_millis();
+
+/// Specifies the kind of compression to use.
+#[repr(u16)]
+pub enum SPCompressionCode {
+    /// no compression
+    Uncompressed = 0x0,
+    /// compress using flate2 with zlib header
+    Zlib = 0x677a,
+    /// compress using bzip2
+    Bzip2 = 0x627a,
+    /// compress using lzma
+    Lzma = 0x6c7a,
+    /// compress using Zstandard
+    Zstd = 0x7a73,
+}
+
+impl TryFrom<SPCompressionCode> for CompressionCode {
+    type Error = ();
+
+    fn try_from(value: SPCompressionCode) -> Result<Self, Self::Error> {
+        CompressionCode::try_from(value as u16)
+    }
+}

src/cp437_grid.rs

@@ -0,0 +1,285 @@
+//! C functions for interacting with [SPCp437Grid]s
+//!
+//! prefix `sp_cp437_grid_`
+
+use crate::SPByteSlice;
+use servicepoint::{DataRef, Grid};
+use std::ptr::NonNull;
+
+/// A C-wrapper for grid containing codepage 437 characters.
+///
+/// The encoding is currently not enforced.
+///
+/// # Examples
+///
+/// ```C
+/// Cp437Grid grid = sp_cp437_grid_new(4, 3);
+/// sp_cp437_grid_fill(grid, '?');
+/// sp_cp437_grid_set(grid, 0, 0, '!');
+/// sp_cp437_grid_free(grid);
+/// ```
+pub struct SPCp437Grid(pub(crate) servicepoint::Cp437Grid);
+
+impl Clone for SPCp437Grid {
+    fn clone(&self) -> Self {
+        SPCp437Grid(self.0.clone())
+    }
+}
+
+/// Creates a new [SPCp437Grid] with the specified dimensions.
+///
+/// returns: [SPCp437Grid] initialized to 0. Will never return NULL.
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - the returned instance is freed in some way, either by using a consuming function or
+///   by explicitly calling `sp_cp437_grid_free`.
+#[no_mangle]
+pub unsafe extern "C" fn sp_cp437_grid_new(
+    width: usize,
+    height: usize,
+) -> NonNull<SPCp437Grid> {
+    let result =
+        Box::new(SPCp437Grid(servicepoint::Cp437Grid::new(width, height)));
+    NonNull::from(Box::leak(result))
+}
+
+/// Loads a [SPCp437Grid] with the specified dimensions from the provided data.
+///
+/// Will never return NULL.
+///
+/// # Panics
+///
+/// - when `data` is NULL
+/// - when the provided `data_length` does not match `height` and `width`
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - `data` points to a valid memory location of at least `data_length`
+///   bytes in size.
+/// - the returned instance is freed in some way, either by using a consuming function or
+///   by explicitly calling `sp_cp437_grid_free`.
+#[no_mangle]
+pub unsafe extern "C" fn sp_cp437_grid_load(
+    width: usize,
+    height: usize,
+    data: *const u8,
+    data_length: usize,
+) -> NonNull<SPCp437Grid> {
+    assert!(data.is_null());
+    let data = std::slice::from_raw_parts(data, data_length);
+    let result = Box::new(SPCp437Grid(servicepoint::Cp437Grid::load(
+        width, height, data,
+    )));
+    NonNull::from(Box::leak(result))
+}
+
+/// Clones a [SPCp437Grid].
+///
+/// Will never return NULL.
+///
+/// # Panics
+///
+/// - when `cp437_grid` is NULL
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - `cp437_grid` points to a valid [SPCp437Grid]
+/// - `cp437_grid` is not written to concurrently
+/// - the returned instance is freed in some way, either by using a consuming function or
+///   by explicitly calling `sp_cp437_grid_free`.
+#[no_mangle]
+pub unsafe extern "C" fn sp_cp437_grid_clone(
+    cp437_grid: *const SPCp437Grid,
+) -> NonNull<SPCp437Grid> {
+    assert!(!cp437_grid.is_null());
+    let result = Box::new((*cp437_grid).clone());
+    NonNull::from(Box::leak(result))
+}
+
+/// Deallocates a [SPCp437Grid].
+///
+/// # Panics
+///
+/// - when `cp437_grid` is NULL
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - `cp437_grid` points to a valid [SPCp437Grid]
+/// - `cp437_grid` is not used concurrently or after cp437_grid call
+/// - `cp437_grid` was not passed to another consuming function, e.g. to create a [SPCommand]
+///
+/// [SPCommand]: [crate::SPCommand]
+#[no_mangle]
+pub unsafe extern "C" fn sp_cp437_grid_free(cp437_grid: *mut SPCp437Grid) {
+    assert!(!cp437_grid.is_null());
+    _ = Box::from_raw(cp437_grid);
+}
+
+/// Gets the current value at the specified position.
+///
+/// # Arguments
+///
+/// - `cp437_grid`: instance to read from
+/// - `x` and `y`: position of the cell to read
+///
+/// # Panics
+///
+/// - when `cp437_grid` is NULL
+/// - when accessing `x` or `y` out of bounds
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - `cp437_grid` points to a valid [SPCp437Grid]
+/// - `cp437_grid` is not written to concurrently
+#[no_mangle]
+pub unsafe extern "C" fn sp_cp437_grid_get(
+    cp437_grid: *const SPCp437Grid,
+    x: usize,
+    y: usize,
+) -> u8 {
+    assert!(!cp437_grid.is_null());
+    (*cp437_grid).0.get(x, y)
+}
+
+/// Sets the value of the specified position in the [SPCp437Grid].
+///
+/// # Arguments
+///
+/// - `cp437_grid`: instance to write to
+/// - `x` and `y`: position of the cell
+/// - `value`: the value to write to the cell
+///
+/// returns: old value of the cell
+///
+/// # Panics
+///
+/// - when `cp437_grid` is NULL
+/// - when accessing `x` or `y` out of bounds
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - `cp437_grid` points to a valid [SPBitVec]
+/// - `cp437_grid` is not written to or read from concurrently
+///
+/// [SPBitVec]: [crate::SPBitVec]
+#[no_mangle]
+pub unsafe extern "C" fn sp_cp437_grid_set(
+    cp437_grid: *mut SPCp437Grid,
+    x: usize,
+    y: usize,
+    value: u8,
+) {
+    assert!(!cp437_grid.is_null());
+    (*cp437_grid).0.set(x, y, value);
+}
+
+/// Sets the value of all cells in the [SPCp437Grid].
+///
+/// # Arguments
+///
+/// - `cp437_grid`: instance to write to
+/// - `value`: the value to set all cells to
+///
+/// # Panics
+///
+/// - when `cp437_grid` is NULL
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - `cp437_grid` points to a valid [SPCp437Grid]
+/// - `cp437_grid` is not written to or read from concurrently
+#[no_mangle]
+pub unsafe extern "C" fn sp_cp437_grid_fill(
+    cp437_grid: *mut SPCp437Grid,
+    value: u8,
+) {
+    assert!(!cp437_grid.is_null());
+    (*cp437_grid).0.fill(value);
+}
+
+/// Gets the width of the [SPCp437Grid] instance.
+///
+/// # Arguments
+///
+/// - `cp437_grid`: instance to read from
+///
+/// # Panics
+///
+/// - when `cp437_grid` is NULL
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - `cp437_grid` points to a valid [SPCp437Grid]
+#[no_mangle]
+pub unsafe extern "C" fn sp_cp437_grid_width(
+    cp437_grid: *const SPCp437Grid,
+) -> usize {
+    assert!(!cp437_grid.is_null());
+    (*cp437_grid).0.width()
+}
+
+/// Gets the height of the [SPCp437Grid] instance.
+///
+/// # Arguments
+///
+/// - `cp437_grid`: instance to read from
+///
+/// # Panics
+///
+/// - when `cp437_grid` is NULL
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - `cp437_grid` points to a valid [SPCp437Grid]
+#[no_mangle]
+pub unsafe extern "C" fn sp_cp437_grid_height(
+    cp437_grid: *const SPCp437Grid,
+) -> usize {
+    assert!(!cp437_grid.is_null());
+    (*cp437_grid).0.height()
+}
+
+/// Gets an unsafe reference to the data of the [SPCp437Grid] instance.
+///
+/// Will never return NULL.
+///
+/// # Panics
+///
+/// - when `cp437_grid` is NULL
+///
+/// ## Safety
+///
+/// The caller has to make sure that:
+///
+/// - `cp437_grid` points to a valid [SPCp437Grid]
+/// - the returned memory range is never accessed after the passed [SPCp437Grid] has been freed
+/// - the returned memory range is never accessed concurrently, either via the [SPCp437Grid] or directly
+#[no_mangle]
+pub unsafe extern "C" fn sp_cp437_grid_unsafe_data_ref(
+    cp437_grid: *mut SPCp437Grid,
+) -> SPByteSlice {
+    let data = (*cp437_grid).0.data_ref_mut();
+    SPByteSlice {
+        start: NonNull::new(data.as_mut_ptr_range().start).unwrap(),
+        length: data.len(),
+    }
+}

src/lib.rs

@@ -0,0 +1,48 @@
+//! C API wrapper for the [servicepoint](https://docs.rs/servicepoint/latest/servicepoint/) crate.
+//!
+//! # Examples
+//!
+//! Make sure to check out [this GitHub repo](https://github.com/arfst23/ServicePoint) as well!
+//!
+//! ```C
+//! #include <stdio.h>
+//! #include "servicepoint.h"
+//!
+//! int main(void) {
+//!     SPConnection *connection = sp_connection_open("172.23.42.29:2342");
+//!     if (connection == NULL)
+//!         return 1;
+//!
+//!     SPBitmap *pixels = sp_bitmap_new(SP_PIXEL_WIDTH, SP_PIXEL_HEIGHT);
+//!     sp_bitmap_fill(pixels, true);
+//!
+//!     SPCommand *command = sp_command_bitmap_linear_win(0, 0, pixels, Uncompressed);
+//!     while (sp_connection_send_command(connection, sp_command_clone(command)));
+//!
+//!     sp_command_free(command);
+//!     sp_connection_free(connection);
+//!     return 0;
+//! }
+//! ```
+
+pub use crate::bitmap::*;
+pub use crate::bitvec::*;
+pub use crate::brightness_grid::*;
+pub use crate::byte_slice::*;
+pub use crate::char_grid::*;
+pub use crate::command::*;
+pub use crate::connection::*;
+pub use crate::constants::*;
+pub use crate::cp437_grid::*;
+pub use crate::packet::*;
+
+mod bitmap;
+mod bitvec;
+mod brightness_grid;
+mod byte_slice;
+mod char_grid;
+mod command;
+mod connection;
+mod constants;
+mod cp437_grid;
+mod packet;

src/packet.rs

@@ -0,0 +1,166 @@
+//! C functions for interacting with [SPPacket]s
+//!
+//! prefix `sp_packet_`
+
+use std::ptr::{null_mut, NonNull};
+
+use crate::SPCommand;
+
+/// The raw packet
+pub struct SPPacket(pub(crate) servicepoint::Packet);
+
+/// Turns a [SPCommand] into a [SPPacket].
+/// The [SPCommand] gets consumed.
+///
+/// Will never return NULL.
+///
+/// # Panics
+///
+/// - when `command` is NULL
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - [SPCommand] points to a valid instance of [SPCommand]
+/// - [SPCommand] is not used concurrently or after this call
+/// - the returned [SPPacket] instance is freed in some way, either by using a consuming function or
+///   by explicitly calling `sp_packet_free`.
+#[no_mangle]
+pub unsafe extern "C" fn sp_packet_from_command(
+    command: *mut SPCommand,
+) -> NonNull<SPPacket> {
+    assert!(!command.is_null());
+    let command = *Box::from_raw(command);
+    let result = Box::new(SPPacket(command.0.into()));
+    NonNull::from(Box::leak(result))
+}
+
+/// Tries to load a [SPPacket] from the passed array with the specified length.
+///
+/// returns: NULL in case of an error, pointer to the allocated packet otherwise
+///
+/// # Panics
+///
+/// - when `data` is NULL
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - `data` points to a valid memory region of at least `length` bytes
+/// - `data` is not written to concurrently
+/// - the returned [SPPacket] instance is freed in some way, either by using a consuming function or
+///   by explicitly calling `sp_packet_free`.
+#[no_mangle]
+pub unsafe extern "C" fn sp_packet_try_load(
+    data: *const u8,
+    length: usize,
+) -> *mut SPPacket {
+    assert!(!data.is_null());
+    let data = std::slice::from_raw_parts(data, length);
+    match servicepoint::Packet::try_from(data) {
+        Err(_) => null_mut(),
+        Ok(packet) => Box::into_raw(Box::new(SPPacket(packet))),
+    }
+}
+
+/// Creates a raw [SPPacket] from parts.
+///
+/// # Arguments
+///
+/// - `command_code` specifies which command this packet contains
+/// - `a`, `b`, `c` and `d` are command-specific header values
+/// - `payload` is the optional data that is part of the command
+/// - `payload_len` is the size of the payload
+///
+/// returns: new instance. Will never return null.
+///
+/// # Panics
+///
+/// - when `payload` is null, but `payload_len` is not zero
+/// - when `payload_len` is zero, but `payload` is nonnull
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - `payload` points to a valid memory region of at least `payload_len` bytes
+/// - `payload` is not written to concurrently
+/// - the returned [SPPacket] instance is freed in some way, either by using a consuming function or
+///   by explicitly calling [sp_packet_free].
+#[no_mangle]
+pub unsafe extern "C" fn sp_packet_from_parts(
+    command_code: u16,
+    a: u16,
+    b: u16,
+    c: u16,
+    d: u16,
+    payload: *const u8,
+    payload_len: usize,
+) -> NonNull<SPPacket> {
+    assert_eq!(payload.is_null(), payload_len == 0);
+
+    let payload = if payload.is_null() {
+        vec![]
+    } else {
+        let payload = std::slice::from_raw_parts(payload, payload_len);
+        Vec::from(payload)
+    };
+
+    let packet = servicepoint::Packet {
+        header: servicepoint::Header {
+            command_code,
+            a,
+            b,
+            c,
+            d,
+        },
+        payload,
+    };
+    let result = Box::new(SPPacket(packet));
+    NonNull::from(Box::leak(result))
+}
+
+/// Clones a [SPPacket].
+///
+/// Will never return NULL.
+///
+/// # Panics
+///
+/// - when `packet` is NULL
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - `packet` points to a valid [SPPacket]
+/// - `packet` is not written to concurrently
+/// - the returned instance is freed in some way, either by using a consuming function or
+///   by explicitly calling `sp_packet_free`.
+#[no_mangle]
+pub unsafe extern "C" fn sp_packet_clone(
+    packet: *const SPPacket,
+) -> NonNull<SPPacket> {
+    assert!(!packet.is_null());
+    let result = Box::new(SPPacket((*packet).0.clone()));
+    NonNull::from(Box::leak(result))
+}
+
+/// Deallocates a [SPPacket].
+///
+/// # Panics
+///
+/// - when `packet` is NULL
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - `packet` points to a valid [SPPacket]
+/// - `packet` is not used concurrently or after this call
+#[no_mangle]
+pub unsafe extern "C" fn sp_packet_free(packet: *mut SPPacket) {
+    assert!(!packet.is_null());
+    _ = Box::from_raw(packet)
+}