servicepoint/servicepoint-binding-c
0
2
Fork 0
Code Issues 1 Pull requests 1 Projects Releases 2 Packages Wiki Activity Actions

wip fix documentation

Browse source
This commit is contained in:
Vinzenz Schroeter 2025-04-12 13:34:02 +02:00
parent 597614bc95
commit e0d82b2b87
13 changed files with 405 additions and 380 deletions
Download patch file Download diff file Expand all files Collapse all files

3
cbindgen.toml
View file

@ -35,7 +35,8 @@ include = []
exclude = []
[export.rename]
"TypedCommand" = "Command"
"SpBitVec" = "BitVec"
"SpByteSlice" = "ByteSlice"
[enum]
rename_variants = "QualifiedScreamingSnakeCase"

2
example/main.c
View file

@ -12,7 +12,7 @@ int main(void) {
sp_bitmap_fill(pixels, true);
Command *command = sp_command_bitmap_linear_win(0, 0, pixels, COMPRESSION_CODE_UNCOMPRESSED);
TypedCommand *command = sp_command_bitmap_linear_win(0, 0, pixels, COMPRESSION_CODE_UNCOMPRESSED);
if (command == NULL)
return 1;

4
examples/.gitignore vendored Normal file
View file

@ -0,0 +1,4 @@
# examples only use library in this repo
Cargo.lock
out
target

414
include/servicepoint.h
View file

File diff suppressed because it is too large Load diff

74
src/bitmap.rs
View file

@ -1,31 +1,16 @@
//! C functions for interacting with [SPBitmap]s
//!
//! prefix `sp_bitmap_`
//!
//! 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);
//! ```
use servicepoint::{Bitmap, DataRef, Grid};
use std::ptr::NonNull;
use crate::byte_slice::SPByteSlice;
/// Creates a new [SPBitmap] with the specified dimensions.
/// Creates a new [Bitmap] 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, or NULL in case of an error.
/// returns: [Bitmap] initialized to all pixels off, or NULL in case of an error.
///
/// # Errors
///
@ -39,6 +24,15 @@ use crate::byte_slice::SPByteSlice;
///
/// - the returned instance is freed in some way, either by using a consuming function or
/// by explicitly calling `sp_bitmap_free`.
///
/// # 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);
/// ```
#[no_mangle]
pub unsafe extern "C" fn sp_bitmap_new(
width: usize,
@ -51,9 +45,9 @@ pub unsafe extern "C" fn sp_bitmap_new(
}
}
/// Creates a new [SPBitmap] with a size matching the screen.
/// Creates a new [Bitmap] with a size matching the screen.
///
/// returns: [SPBitmap] initialized to all pixels off. Will never return NULL.
/// returns: [Bitmap] initialized to all pixels off. Will never return NULL.
///
/// # Safety
///
@ -67,14 +61,14 @@ pub unsafe extern "C" fn sp_bitmap_new_screen_sized() -> NonNull<Bitmap> {
NonNull::from(Box::leak(result))
}
/// Loads a [SPBitmap] with the specified dimensions from the provided data.
/// Loads a [Bitmap] 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, or NULL in case of an error.
/// returns: [Bitmap] that contains a copy of the provided data, or NULL in case of an error.
///
/// # Errors
///
@ -108,7 +102,7 @@ pub unsafe extern "C" fn sp_bitmap_load(
}
}
/// Clones a [SPBitmap].
/// Clones a [Bitmap].
///
/// Will never return NULL.
///
@ -120,7 +114,7 @@ pub unsafe extern "C" fn sp_bitmap_load(
///
/// The caller has to make sure that:
///
/// - `bitmap` points to a valid [SPBitmap]
/// - `bitmap` points to a valid [Bitmap]
/// - `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`.
@ -132,7 +126,7 @@ pub unsafe extern "C" fn sp_bitmap_clone(
NonNull::from(Box::leak(result))
}
/// Deallocates a [SPBitmap].
/// Deallocates a [Bitmap].
///
/// # Panics
///
@ -142,15 +136,15 @@ pub unsafe extern "C" fn sp_bitmap_clone(
///
/// The caller has to make sure that:
///
/// - `bitmap` points to a valid [SPBitmap]
/// - `bitmap` points to a valid [Bitmap]
///
/// [SPCommand]: [crate::SPCommand]
/// [TypedCommand]: [crate::TypedCommand]
#[no_mangle]
pub unsafe extern "C" fn sp_bitmap_free(bitmap: NonNull<Bitmap>) {
_ = unsafe { Box::from_raw(bitmap.as_ptr()) };
}
/// Gets the current value at the specified position in the [SPBitmap].
/// Gets the current value at the specified position in the [Bitmap].
///
/// # Arguments
///
@ -166,7 +160,7 @@ pub unsafe extern "C" fn sp_bitmap_free(bitmap: NonNull<Bitmap>) {
///
/// The caller has to make sure that:
///
/// - `bitmap` points to a valid [SPBitmap]
/// - `bitmap` points to a valid [Bitmap]
/// - `bitmap` is not written to concurrently
#[no_mangle]
pub unsafe extern "C" fn sp_bitmap_get(
@ -177,7 +171,7 @@ pub unsafe extern "C" fn sp_bitmap_get(
unsafe { bitmap.as_ref().get(x, y) }
}
/// Sets the value of the specified position in the [SPBitmap].
/// Sets the value of the specified position in the [Bitmap].
///
/// # Arguments
///
@ -196,7 +190,7 @@ pub unsafe extern "C" fn sp_bitmap_get(
///
/// The caller has to make sure that:
///
/// - `bitmap` points to a valid [SPBitmap]
/// - `bitmap` points to a valid [Bitmap]
/// - `bitmap` is not written to or read from concurrently
#[no_mangle]
pub unsafe extern "C" fn sp_bitmap_set(
@ -208,7 +202,7 @@ pub unsafe extern "C" fn sp_bitmap_set(
unsafe { (*bitmap.as_ptr()).set(x, y, value) };
}
/// Sets the state of all pixels in the [SPBitmap].
/// Sets the state of all pixels in the [Bitmap].
///
/// # Arguments
///
@ -223,14 +217,14 @@ pub unsafe extern "C" fn sp_bitmap_set(
///
/// The caller has to make sure that:
///
/// - `bitmap` points to a valid [SPBitmap]
/// - `bitmap` points to a valid [Bitmap]
/// - `bitmap` is not written to or read from concurrently
#[no_mangle]
pub unsafe extern "C" fn sp_bitmap_fill(bitmap: NonNull<Bitmap>, value: bool) {
unsafe { (*bitmap.as_ptr()).fill(value) };
}
/// Gets the width in pixels of the [SPBitmap] instance.
/// Gets the width in pixels of the [Bitmap] instance.
///
/// # Arguments
///
@ -244,13 +238,13 @@ pub unsafe extern "C" fn sp_bitmap_fill(bitmap: NonNull<Bitmap>, value: bool) {
///
/// The caller has to make sure that:
///
/// - `bitmap` points to a valid [SPBitmap]
/// - `bitmap` points to a valid [Bitmap]
#[no_mangle]
pub unsafe extern "C" fn sp_bitmap_width(bitmap: NonNull<Bitmap>) -> usize {
unsafe { bitmap.as_ref().width() }
}
/// Gets the height in pixels of the [SPBitmap] instance.
/// Gets the height in pixels of the [Bitmap] instance.
///
/// # Arguments
///
@ -264,13 +258,13 @@ pub unsafe extern "C" fn sp_bitmap_width(bitmap: NonNull<Bitmap>) -> usize {
///
/// The caller has to make sure that:
///
/// - `bitmap` points to a valid [SPBitmap]
/// - `bitmap` points to a valid [Bitmap]
#[no_mangle]
pub unsafe extern "C" fn sp_bitmap_height(bitmap: NonNull<Bitmap>) -> usize {
unsafe { bitmap.as_ref().height() }
}
/// Gets an unsafe reference to the data of the [SPBitmap] instance.
/// Gets an unsafe reference to the data of the [Bitmap] instance.
///
/// # Panics
///
@ -280,9 +274,9 @@ pub unsafe extern "C" fn sp_bitmap_height(bitmap: NonNull<Bitmap>) -> usize {
///
/// 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
/// - `bitmap` points to a valid [Bitmap]
/// - the returned memory range is never accessed after the passed [Bitmap] has been freed
/// - the returned memory range is never accessed concurrently, either via the [Bitmap] or directly
#[no_mangle]
pub unsafe extern "C" fn sp_bitmap_unsafe_data_ref(
mut bitmap: NonNull<Bitmap>,

4
src/bitvec.rs
View file

@ -108,9 +108,9 @@ pub unsafe extern "C" fn sp_bitvec_clone(
///
/// - `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]
/// - `bit_vec` was not passed to another consuming function, e.g. to create a [TypedCommand]
///
/// [SPCommand]: [crate::SPCommand]
/// [TypedCommand]: [crate::TypedCommand]
#[no_mangle]
pub unsafe extern "C" fn sp_bitvec_free(bit_vec: NonNull<SPBitVec>) {
_ = unsafe { Box::from_raw(bit_vec.as_ptr()) };

56
src/brightness_grid.rs
View file

@ -1,4 +1,4 @@
//! C functions for interacting with [SPBrightnessGrid]s
//! C functions for interacting with [BrightnessGrid]s
//!
//! prefix `sp_brightness_grid_`
//!
@ -7,15 +7,15 @@
//!
//! # Examples
//! ```C
//! SPConnection connection = sp_connection_open("127.0.0.1:2342");
//! UdpConnection connection = sp_connection_open("127.0.0.1:2342");
//! if (connection == NULL)
//! return 1;
//!
//! SPBrightnessGrid grid = sp_brightness_grid_new(2, 2);
//! BrightnessGrid 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);
//! TypedCommand command = sp_command_char_brightness(grid);
//! sp_connection_free(connection);
//! ```
@ -24,9 +24,9 @@ use servicepoint::{Brightness, BrightnessGrid, DataRef, Grid};
use std::mem::transmute;
use std::ptr::NonNull;
/// Creates a new [SPBrightnessGrid] with the specified dimensions.
/// Creates a new [BrightnessGrid] with the specified dimensions.
///
/// returns: [SPBrightnessGrid] initialized to 0. Will never return NULL.
/// returns: [BrightnessGrid] initialized to 0. Will never return NULL.
///
/// # Safety
///
@ -43,9 +43,9 @@ pub unsafe extern "C" fn sp_brightness_grid_new(
NonNull::from(Box::leak(result))
}
/// Loads a [SPBrightnessGrid] with the specified dimensions from the provided data.
/// Loads a [BrightnessGrid] with the specified dimensions from the provided data.
///
/// returns: new [SPBrightnessGrid] instance. Will never return NULL.
/// returns: new [BrightnessGrid] instance. Will never return NULL.
///
/// # Panics
///
@ -78,13 +78,13 @@ pub unsafe extern "C" fn sp_brightness_grid_load(
}
}
/// Clones a [SPBrightnessGrid].
/// Clones a [BrightnessGrid].
///
/// # Arguments
///
/// - `brightness_grid`: instance to read from
///
/// returns: new [SPBrightnessGrid] instance. Will never return NULL.
/// returns: new [BrightnessGrid] instance. Will never return NULL.
///
/// # Panics
///
@ -94,7 +94,7 @@ pub unsafe extern "C" fn sp_brightness_grid_load(
///
/// The caller has to make sure that:
///
/// - `brightness_grid` points to a valid [SPBrightnessGrid]
/// - `brightness_grid` points to a valid [BrightnessGrid]
/// - `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`.
@ -106,7 +106,7 @@ pub unsafe extern "C" fn sp_brightness_grid_clone(
NonNull::from(Box::leak(result))
}
/// Deallocates a [SPBrightnessGrid].
/// Deallocates a [BrightnessGrid].
///
/// # Arguments
///
@ -120,11 +120,11 @@ pub unsafe extern "C" fn sp_brightness_grid_clone(
///
/// The caller has to make sure that:
///
/// - `brightness_grid` points to a valid [SPBrightnessGrid]
/// - `brightness_grid` points to a valid [BrightnessGrid]
/// - `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]
/// - `brightness_grid` was not passed to another consuming function, e.g. to create a [TypedCommand]
///
/// [SPCommand]: [crate::SPCommand]
/// [TypedCommand]: [crate::TypedCommand]
#[no_mangle]
pub unsafe extern "C" fn sp_brightness_grid_free(
brightness_grid: NonNull<BrightnessGrid>,
@ -150,7 +150,7 @@ pub unsafe extern "C" fn sp_brightness_grid_free(
///
/// The caller has to make sure that:
///
/// - `brightness_grid` points to a valid [SPBrightnessGrid]
/// - `brightness_grid` points to a valid [BrightnessGrid]
/// - `brightness_grid` is not written to concurrently
#[no_mangle]
pub unsafe extern "C" fn sp_brightness_grid_get(
@ -161,7 +161,7 @@ pub unsafe extern "C" fn sp_brightness_grid_get(
unsafe { brightness_grid.as_ref().get(x, y) }
}
/// Sets the value of the specified position in the [SPBrightnessGrid].
/// Sets the value of the specified position in the [BrightnessGrid].
///
/// # Arguments
///
@ -181,7 +181,7 @@ pub unsafe extern "C" fn sp_brightness_grid_get(
///
/// The caller has to make sure that:
///
/// - `brightness_grid` points to a valid [SPBrightnessGrid]
/// - `brightness_grid` points to a valid [BrightnessGrid]
/// - `brightness_grid` is not written to or read from concurrently
#[no_mangle]
pub unsafe extern "C" fn sp_brightness_grid_set(
@ -193,7 +193,7 @@ pub unsafe extern "C" fn sp_brightness_grid_set(
unsafe { (*brightness_grid.as_ptr()).set(x, y, value) };
}
/// Sets the value of all cells in the [SPBrightnessGrid].
/// Sets the value of all cells in the [BrightnessGrid].
///
/// # Arguments
///
@ -209,7 +209,7 @@ pub unsafe extern "C" fn sp_brightness_grid_set(
///
/// The caller has to make sure that:
///
/// - `brightness_grid` points to a valid [SPBrightnessGrid]
/// - `brightness_grid` points to a valid [BrightnessGrid]
/// - `brightness_grid` is not written to or read from concurrently
#[no_mangle]
pub unsafe extern "C" fn sp_brightness_grid_fill(
@ -219,7 +219,7 @@ pub unsafe extern "C" fn sp_brightness_grid_fill(
unsafe { (*brightness_grid.as_ptr()).fill(value) };
}
/// Gets the width of the [SPBrightnessGrid] instance.
/// Gets the width of the [BrightnessGrid] instance.
///
/// # Arguments
///
@ -235,7 +235,7 @@ pub unsafe extern "C" fn sp_brightness_grid_fill(
///
/// The caller has to make sure that:
///
/// - `brightness_grid` points to a valid [SPBrightnessGrid]
/// - `brightness_grid` points to a valid [BrightnessGrid]
#[no_mangle]
pub unsafe extern "C" fn sp_brightness_grid_width(
brightness_grid: NonNull<BrightnessGrid>,
@ -243,7 +243,7 @@ pub unsafe extern "C" fn sp_brightness_grid_width(
unsafe { brightness_grid.as_ref().width() }
}
/// Gets the height of the [SPBrightnessGrid] instance.
/// Gets the height of the [BrightnessGrid] instance.
///
/// # Arguments
///
@ -259,7 +259,7 @@ pub unsafe extern "C" fn sp_brightness_grid_width(
///
/// The caller has to make sure that:
///
/// - `brightness_grid` points to a valid [SPBrightnessGrid]
/// - `brightness_grid` points to a valid [BrightnessGrid]
#[no_mangle]
pub unsafe extern "C" fn sp_brightness_grid_height(
brightness_grid: NonNull<BrightnessGrid>,
@ -267,7 +267,7 @@ pub unsafe extern "C" fn sp_brightness_grid_height(
unsafe { brightness_grid.as_ref().height() }
}
/// Gets an unsafe reference to the data of the [SPBrightnessGrid] instance.
/// Gets an unsafe reference to the data of the [BrightnessGrid] instance.
///
/// # Arguments
///
@ -283,9 +283,9 @@ pub unsafe extern "C" fn sp_brightness_grid_height(
///
/// 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
/// - `brightness_grid` points to a valid [BrightnessGrid]
/// - the returned memory range is never accessed after the passed [BrightnessGrid] has been freed
/// - the returned memory range is never accessed concurrently, either via the [BrightnessGrid] or directly
#[no_mangle]
pub unsafe extern "C" fn sp_brightness_grid_unsafe_data_ref(
brightness_grid: NonNull<BrightnessGrid>,

36
src/char_grid.rs
View file

@ -1,4 +1,4 @@
//! C functions for interacting with [SPCharGrid]s
//! C functions for interacting with [CharGrid]s
//!
//! prefix `sp_char_grid_`
//!
@ -22,9 +22,9 @@ use crate::SPByteSlice;
use servicepoint::{CharGrid, Grid};
use std::ptr::NonNull;
/// Creates a new [SPCharGrid] with the specified dimensions.
/// Creates a new [CharGrid] with the specified dimensions.
///
/// returns: [SPCharGrid] initialized to 0. Will never return NULL.
/// returns: [CharGrid] initialized to 0. Will never return NULL.
///
/// # Safety
///
@ -41,7 +41,7 @@ pub unsafe extern "C" fn sp_char_grid_new(
NonNull::from(Box::leak(result))
}
/// Loads a [SPCharGrid] with the specified dimensions from the provided data.
/// Loads a [CharGrid] with the specified dimensions from the provided data.
///
/// Will never return NULL.
///
@ -72,7 +72,7 @@ pub unsafe extern "C" fn sp_char_grid_load(
NonNull::from(Box::leak(result))
}
/// Clones a [SPCharGrid].
/// Clones a [CharGrid].
///
/// Will never return NULL.
///
@ -84,7 +84,7 @@ pub unsafe extern "C" fn sp_char_grid_load(
///
/// The caller has to make sure that:
///
/// - `char_grid` points to a valid [SPCharGrid]
/// - `char_grid` points to a valid [CharGrid]
/// - `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`.
@ -96,7 +96,7 @@ pub unsafe extern "C" fn sp_char_grid_clone(
NonNull::from(Box::leak(result))
}
/// Deallocates a [SPCharGrid].
/// Deallocates a [CharGrid].
///
/// # Panics
///
@ -106,11 +106,11 @@ pub unsafe extern "C" fn sp_char_grid_clone(
///
/// The caller has to make sure that:
///
/// - `char_grid` points to a valid [SPCharGrid]
/// - `char_grid` points to a valid [CharGrid]
/// - `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]
/// - `char_grid` was not passed to another consuming function, e.g. to create a [TypedCommand]
///
/// [SPCommand]: [crate::SPCommand]
/// [TypedCommand]: [crate::TypedCommand]
#[no_mangle]
pub unsafe extern "C" fn sp_char_grid_free(char_grid: NonNull<CharGrid>) {
_ = unsafe { Box::from_raw(char_grid.as_ptr()) };
@ -132,7 +132,7 @@ pub unsafe extern "C" fn sp_char_grid_free(char_grid: NonNull<CharGrid>) {
///
/// The caller has to make sure that:
///
/// - `char_grid` points to a valid [SPCharGrid]
/// - `char_grid` points to a valid [CharGrid]
/// - `char_grid` is not written to concurrently
#[no_mangle]
pub unsafe extern "C" fn sp_char_grid_get(
@ -143,7 +143,7 @@ pub unsafe extern "C" fn sp_char_grid_get(
unsafe { char_grid.as_ref().get(x, y) as u32 }
}
/// Sets the value of the specified position in the [SPCharGrid].
/// Sets the value of the specified position in the [CharGrid].
///
/// # Arguments
///
@ -176,7 +176,7 @@ pub unsafe extern "C" fn sp_char_grid_set(
unsafe { (*char_grid.as_ptr()).set(x, y, char::from_u32(value).unwrap()) };
}
/// Sets the value of all cells in the [SPCharGrid].
/// Sets the value of all cells in the [CharGrid].
///
/// # Arguments
///
@ -191,7 +191,7 @@ pub unsafe extern "C" fn sp_char_grid_set(
///
/// The caller has to make sure that:
///
/// - `char_grid` points to a valid [SPCharGrid]
/// - `char_grid` points to a valid [CharGrid]
/// - `char_grid` is not written to or read from concurrently
#[no_mangle]
pub unsafe extern "C" fn sp_char_grid_fill(
@ -201,7 +201,7 @@ pub unsafe extern "C" fn sp_char_grid_fill(
unsafe { (*char_grid.as_ptr()).fill(char::from_u32(value).unwrap()) };
}
/// Gets the width of the [SPCharGrid] instance.
/// Gets the width of the [CharGrid] instance.
///
/// # Arguments
///
@ -215,7 +215,7 @@ pub unsafe extern "C" fn sp_char_grid_fill(
///
/// The caller has to make sure that:
///
/// - `char_grid` points to a valid [SPCharGrid]
/// - `char_grid` points to a valid [CharGrid]
#[no_mangle]
pub unsafe extern "C" fn sp_char_grid_width(
char_grid: NonNull<CharGrid>,
@ -223,7 +223,7 @@ pub unsafe extern "C" fn sp_char_grid_width(
unsafe { char_grid.as_ref().width() }
}
/// Gets the height of the [SPCharGrid] instance.
/// Gets the height of the [CharGrid] instance.
///
/// # Arguments
///
@ -237,7 +237,7 @@ pub unsafe extern "C" fn sp_char_grid_width(
///
/// The caller has to make sure that:
///
/// - `char_grid` points to a valid [SPCharGrid]
/// - `char_grid` points to a valid [CharGrid]
#[no_mangle]
pub unsafe extern "C" fn sp_char_grid_height(
char_grid: NonNull<CharGrid>,

72
src/command.rs
View file

@ -1,4 +1,4 @@
//! C functions for interacting with [SPCommand]s
//! C functions for interacting with [TypedCommand]s
//!
//! prefix `sp_command_`
@ -10,7 +10,7 @@ use std::ptr::NonNull;
///
/// This struct and associated functions implement the UDP protocol for the display.
///
/// To send a [SPCommand], use a [SPConnection].
/// To send a [TypedCommand], use a [UdpConnection].
///
/// # Examples
///
@ -18,14 +18,12 @@ use std::ptr::NonNull;
/// sp_connection_send_command(connection, sp_command_clear());
/// sp_connection_send_command(connection, sp_command_brightness(5));
/// ```
///
/// [SPConnection]: [crate::SPConnection]
/// Tries to turn a [SPPacket] into a [SPCommand].
/// Tries to turn a [Packet] into a [TypedCommand].
///
/// The packet is deallocated in the process.
///
/// Returns: pointer to new [SPCommand] instance or NULL if parsing failed.
/// Returns: pointer to new [TypedCommand] instance or NULL if parsing failed.
///
/// # Panics
///
@ -35,10 +33,10 @@ use std::ptr::NonNull;
///
/// The caller has to make sure that:
///
/// - [SPPacket] points to a valid instance of [SPPacket]
/// - [SPPacket] is not used concurrently or after this call
/// - [Packet] points to a valid instance of [Packet]
/// - [Packet] 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
/// - the returned [TypedCommand] 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(
@ -51,9 +49,9 @@ pub unsafe extern "C" fn sp_command_try_from_packet(
}
}
/// Clones a [SPCommand] instance.
/// Clones a [TypedCommand] instance.
///
/// returns: new [SPCommand] instance. Will never return NULL.
/// returns: new [TypedCommand] instance. Will never return NULL.
///
/// # Panics
///
@ -63,9 +61,9 @@ pub unsafe extern "C" fn sp_command_try_from_packet(
///
/// The caller has to make sure that:
///
/// - `command` points to a valid instance of [SPCommand]
/// - `command` points to a valid instance of [TypedCommand]
/// - `command` is not written to concurrently
/// - the returned [SPCommand] instance is freed in some way, either by using a consuming function or
/// - the returned [TypedCommand] 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(
@ -91,7 +89,7 @@ pub unsafe extern "C" fn sp_command_clone(
///
/// The caller has to make sure that:
///
/// - the returned [SPCommand] instance is freed in some way, either by using a consuming function or
/// - the returned [TypedCommand] 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<TypedCommand> {
@ -109,7 +107,7 @@ pub unsafe extern "C" fn sp_command_clear() -> NonNull<TypedCommand> {
///
/// The caller has to make sure that:
///
/// - the returned [SPCommand] instance is freed in some way, either by using a consuming function or
/// - the returned [TypedCommand] 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<TypedCommand> {
@ -125,7 +123,7 @@ pub unsafe extern "C" fn sp_command_hard_reset() -> NonNull<TypedCommand> {
///
/// The caller has to make sure that:
///
/// - the returned [SPCommand] instance is freed in some way, either by using a consuming function or
/// - the returned [TypedCommand] 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<TypedCommand> {
@ -145,7 +143,7 @@ pub unsafe extern "C" fn sp_command_fade_out() -> NonNull<TypedCommand> {
///
/// The caller has to make sure that:
///
/// - the returned [SPCommand] instance is freed in some way, either by using a consuming function or
/// - the returned [TypedCommand] 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(
@ -157,7 +155,7 @@ pub unsafe extern "C" fn sp_command_brightness(
/// Set the brightness of individual tiles in a rectangular area of the display.
///
/// The passed [SPBrightnessGrid] gets consumed.
/// The passed [BrightnessGrid] gets consumed.
///
/// Returns: a new [servicepoint::Command::CharBrightness] instance. Will never return NULL.
///
@ -169,9 +167,9 @@ pub unsafe extern "C" fn sp_command_brightness(
///
/// The caller has to make sure that:
///
/// - `grid` points to a valid instance of [SPBrightnessGrid]
/// - `grid` points to a valid instance of [BrightnessGrid]
/// - `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
/// - the returned [TypedCommand] 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(
@ -213,7 +211,7 @@ pub unsafe extern "C" fn sp_command_char_brightness(
/// - `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
/// - the returned [TypedCommand] 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(
@ -254,7 +252,7 @@ pub unsafe extern "C" fn sp_command_bitmap_linear(
/// - `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
/// - the returned [TypedCommand] 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(
@ -295,7 +293,7 @@ pub unsafe extern "C" fn sp_command_bitmap_linear_and(
/// - `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
/// - the returned [TypedCommand] 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(
@ -336,7 +334,7 @@ pub unsafe extern "C" fn sp_command_bitmap_linear_or(
/// - `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
/// - the returned [TypedCommand] 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(
@ -378,7 +376,7 @@ unsafe fn sp_command_bitmap_linear_internal(
/// Show codepage 437 encoded text on the screen.
///
/// The passed [SPCp437Grid] gets consumed.
/// The passed [Cp437Grid] gets consumed.
///
/// Returns: a new [servicepoint::Command::Cp437Data] instance. Will never return NULL.
///
@ -390,9 +388,9 @@ unsafe fn sp_command_bitmap_linear_internal(
///
/// The caller has to make sure that:
///
/// - `grid` points to a valid instance of [SPCp437Grid]
/// - `grid` points to a valid instance of [Cp437Grid]
/// - `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
/// - the returned [TypedCommand] 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(
@ -413,7 +411,7 @@ pub unsafe extern "C" fn sp_command_cp437_data(
/// Show UTF-8 encoded text on the screen.
///
/// The passed [SPCharGrid] gets consumed.
/// The passed [CharGrid] gets consumed.
///
/// Returns: a new [servicepoint::Command::Utf8Data] instance. Will never return NULL.
///
@ -425,9 +423,9 @@ pub unsafe extern "C" fn sp_command_cp437_data(
///
/// The caller has to make sure that:
///
/// - `grid` points to a valid instance of [SPCharGrid]
/// - `grid` points to a valid instance of [CharGrid]
/// - `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
/// - the returned [TypedCommand] 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(
@ -448,7 +446,7 @@ pub unsafe extern "C" fn sp_command_utf8_data(
/// Sets a window of pixels to the specified values.
///
/// The passed [SPBitmap] gets consumed.
/// The passed [Bitmap] gets consumed.
///
/// Returns: a new [servicepoint::Command::BitmapLinearWin] instance. Will never return NULL.
///
@ -461,10 +459,10 @@ pub unsafe extern "C" fn sp_command_utf8_data(
///
/// The caller has to make sure that:
///
/// - `bitmap` points to a valid instance of [SPBitmap]
/// - `bitmap` points to a valid instance of [Bitmap]
/// - `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
/// - the returned [TypedCommand] 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(
@ -487,12 +485,12 @@ pub unsafe extern "C" fn sp_command_bitmap_linear_win(
Box::leak(Box::new(command))
}
/// Deallocates a [SPCommand].
/// Deallocates a [TypedCommand].
///
/// # Examples
///
/// ```C
/// SPCommand c = sp_command_clear();
/// TypedCommand c = sp_command_clear();
/// sp_command_free(c);
/// ```
///
@ -504,9 +502,9 @@ pub unsafe extern "C" fn sp_command_bitmap_linear_win(
///
/// The caller has to make sure that:
///
/// - `command` points to a valid [SPCommand]
/// - `command` points to a valid [TypedCommand]
/// - `command` is not used concurrently or after this call
/// - `command` was not passed to another consuming function, e.g. to create a [SPPacket]
/// - `command` was not passed to another consuming function, e.g. to create a [Packet]
#[no_mangle]
pub unsafe extern "C" fn sp_command_free(command: NonNull<TypedCommand>) {
_ = unsafe { Box::from_raw(command.as_ptr()) };

24
src/connection.rs
View file

@ -1,4 +1,4 @@
//! C functions for interacting with [SPConnection]s
//! C functions for interacting with [UdpConnection]s
//!
//! prefix `sp_connection_`
//!
@ -16,7 +16,7 @@ use servicepoint::{Connection, Packet, TypedCommand, UdpConnection};
use std::ffi::{c_char, CStr};
use std::ptr::NonNull;
/// Creates a new instance of [SPConnection].
/// Creates a new instance of [UdpConnection].
///
/// returns: NULL if connection fails, or connected instance
///
@ -48,13 +48,13 @@ pub unsafe extern "C" fn sp_connection_open(
//#[no_mangle]
//pub unsafe extern "C" fn sp_connection_open_ipv4(
// host: SocketAddrV4,
//) -> *mut SPConnection {
//) -> *mut UdpConnection {
// let connection = match servicepoint::UdpConnection::open(host) {
// Err(_) => return std::ptr::null_mut(),
// Ok(value) => value,
// };
//
// Box::into_raw(Box::new(SPConnection(connection)))
// Box::into_raw(Box::new(UdpConnection(connection)))
//}
// /// Creates a new instance of [SPUdpConnection] for testing that does not actually send anything.
@ -73,7 +73,7 @@ pub unsafe extern "C" fn sp_connection_open(
// NonNull::from(Box::leak(result))
// }
/// Sends a [SPPacket] to the display using the [SPConnection].
/// Sends a [Packet] to the display using the [UdpConnection].
///
/// The passed `packet` gets consumed.
///
@ -88,8 +88,8 @@ pub unsafe extern "C" fn sp_connection_open(
///
/// The caller has to make sure that:
///
/// - `connection` points to a valid instance of [SPConnection]
/// - `packet` points to a valid instance of [SPPacket]
/// - `connection` points to a valid instance of [UdpConnection]
/// - `packet` points to a valid instance of [Packet]
/// - `packet` is not used concurrently or after this call
#[no_mangle]
pub unsafe extern "C" fn sp_connection_send_packet(
@ -100,7 +100,7 @@ pub unsafe extern "C" fn sp_connection_send_packet(
unsafe { connection.as_ref().send(*packet) }.is_ok()
}
/// Sends a [SPCommand] to the display using the [SPConnection].
/// Sends a [TypedCommand] to the display using the [UdpConnection].
///
/// The passed `command` gets consumed.
///
@ -115,8 +115,8 @@ pub unsafe extern "C" fn sp_connection_send_packet(
///
/// The caller has to make sure that:
///
/// - `connection` points to a valid instance of [SPConnection]
/// - `command` points to a valid instance of [SPPacket]
/// - `connection` points to a valid instance of [UdpConnection]
/// - `command` points to a valid instance of [Packet]
/// - `command` is not used concurrently or after this call
#[no_mangle]
pub unsafe extern "C" fn sp_connection_send_command(
@ -127,7 +127,7 @@ pub unsafe extern "C" fn sp_connection_send_command(
unsafe { connection.as_ref().send(command) }.is_ok()
}
/// Closes and deallocates a [SPConnection].
/// Closes and deallocates a [UdpConnection].
///
/// # Panics
///
@ -137,7 +137,7 @@ pub unsafe extern "C" fn sp_connection_send_command(
///
/// The caller has to make sure that:
///
/// - `connection` points to a valid [SPConnection]
/// - `connection` points to a valid [UdpConnection]
/// - `connection` is not used concurrently or after this call
#[no_mangle]
pub unsafe extern "C" fn sp_connection_free(

44
src/cp437_grid.rs
View file

@ -1,4 +1,4 @@
//! C functions for interacting with [SPCp437Grid]s
//! C functions for interacting with [Cp437Grid]s
//!
//! prefix `sp_cp437_grid_`
//!
@ -20,9 +20,9 @@ use crate::SPByteSlice;
use servicepoint::{Cp437Grid, DataRef, Grid};
use std::ptr::NonNull;
/// Creates a new [SPCp437Grid] with the specified dimensions.
/// Creates a new [Cp437Grid] with the specified dimensions.
///
/// returns: [SPCp437Grid] initialized to 0. Will never return NULL.
/// returns: [Cp437Grid] initialized to 0. Will never return NULL.
///
/// # Safety
///
@ -39,7 +39,7 @@ pub unsafe extern "C" fn sp_cp437_grid_new(
NonNull::from(Box::leak(result))
}
/// Loads a [SPCp437Grid] with the specified dimensions from the provided data.
/// Loads a [Cp437Grid] with the specified dimensions from the provided data.
///
/// Will never return NULL.
///
@ -71,7 +71,7 @@ pub unsafe extern "C" fn sp_cp437_grid_load(
}
}
/// Clones a [SPCp437Grid].
/// Clones a [Cp437Grid].
///
/// Will never return NULL.
///
@ -83,7 +83,7 @@ pub unsafe extern "C" fn sp_cp437_grid_load(
///
/// The caller has to make sure that:
///
/// - `cp437_grid` points to a valid [SPCp437Grid]
/// - `cp437_grid` points to a valid [Cp437Grid]
/// - `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`.
@ -95,7 +95,7 @@ pub unsafe extern "C" fn sp_cp437_grid_clone(
NonNull::from(Box::leak(result))
}
/// Deallocates a [SPCp437Grid].
/// Deallocates a [Cp437Grid].
///
/// # Panics
///
@ -105,11 +105,11 @@ pub unsafe extern "C" fn sp_cp437_grid_clone(
///
/// The caller has to make sure that:
///
/// - `cp437_grid` points to a valid [SPCp437Grid]
/// - `cp437_grid` points to a valid [Cp437Grid]
/// - `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]
/// - `cp437_grid` was not passed to another consuming function, e.g. to create a [TypedCommand]
///
/// [SPCommand]: [crate::SPCommand]
/// [TypedCommand]: [crate::TypedCommand]
#[no_mangle]
pub unsafe extern "C" fn sp_cp437_grid_free(cp437_grid: NonNull<Cp437Grid>) {
_ = unsafe { Box::from_raw(cp437_grid.as_ptr()) };
@ -131,7 +131,7 @@ pub unsafe extern "C" fn sp_cp437_grid_free(cp437_grid: NonNull<Cp437Grid>) {
///
/// The caller has to make sure that:
///
/// - `cp437_grid` points to a valid [SPCp437Grid]
/// - `cp437_grid` points to a valid [Cp437Grid]
/// - `cp437_grid` is not written to concurrently
#[no_mangle]
pub unsafe extern "C" fn sp_cp437_grid_get(
@ -142,7 +142,7 @@ pub unsafe extern "C" fn sp_cp437_grid_get(
unsafe { cp437_grid.as_ref().get(x, y) }
}
/// Sets the value of the specified position in the [SPCp437Grid].
/// Sets the value of the specified position in the [Cp437Grid].
///
/// # Arguments
///
@ -175,7 +175,7 @@ pub unsafe extern "C" fn sp_cp437_grid_set(
unsafe { (*cp437_grid.as_ptr()).set(x, y, value) };
}
/// Sets the value of all cells in the [SPCp437Grid].
/// Sets the value of all cells in the [Cp437Grid].
///
/// # Arguments
///
@ -190,7 +190,7 @@ pub unsafe extern "C" fn sp_cp437_grid_set(
///
/// The caller has to make sure that:
///
/// - `cp437_grid` points to a valid [SPCp437Grid]
/// - `cp437_grid` points to a valid [Cp437Grid]
/// - `cp437_grid` is not written to or read from concurrently
#[no_mangle]
pub unsafe extern "C" fn sp_cp437_grid_fill(
@ -200,7 +200,7 @@ pub unsafe extern "C" fn sp_cp437_grid_fill(
unsafe { (*cp437_grid.as_ptr()).fill(value) };
}
/// Gets the width of the [SPCp437Grid] instance.
/// Gets the width of the [Cp437Grid] instance.
///
/// # Arguments
///
@ -214,7 +214,7 @@ pub unsafe extern "C" fn sp_cp437_grid_fill(
///
/// The caller has to make sure that:
///
/// - `cp437_grid` points to a valid [SPCp437Grid]
/// - `cp437_grid` points to a valid [Cp437Grid]
#[no_mangle]
pub unsafe extern "C" fn sp_cp437_grid_width(
cp437_grid: NonNull<Cp437Grid>,
@ -222,7 +222,7 @@ pub unsafe extern "C" fn sp_cp437_grid_width(
unsafe { cp437_grid.as_ref().width() }
}
/// Gets the height of the [SPCp437Grid] instance.
/// Gets the height of the [Cp437Grid] instance.
///
/// # Arguments
///
@ -236,7 +236,7 @@ pub unsafe extern "C" fn sp_cp437_grid_width(
///
/// The caller has to make sure that:
///
/// - `cp437_grid` points to a valid [SPCp437Grid]
/// - `cp437_grid` points to a valid [Cp437Grid]
#[no_mangle]
pub unsafe extern "C" fn sp_cp437_grid_height(
cp437_grid: NonNull<Cp437Grid>,
@ -244,7 +244,7 @@ pub unsafe extern "C" fn sp_cp437_grid_height(
unsafe { cp437_grid.as_ref().height() }
}
/// Gets an unsafe reference to the data of the [SPCp437Grid] instance.
/// Gets an unsafe reference to the data of the [Cp437Grid] instance.
///
/// Will never return NULL.
///
@ -256,9 +256,9 @@ pub unsafe extern "C" fn sp_cp437_grid_height(
///
/// 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
/// - `cp437_grid` points to a valid [Cp437Grid]
/// - the returned memory range is never accessed after the passed [Cp437Grid] has been freed
/// - the returned memory range is never accessed concurrently, either via the [Cp437Grid] or directly
#[no_mangle]
pub unsafe extern "C" fn sp_cp437_grid_unsafe_data_ref(
cp437_grid: NonNull<Cp437Grid>,

6
src/lib.rs
View file

@ -9,14 +9,14 @@
//! #include "servicepoint.h"
//!
//! int main(void) {
//! SPConnection *connection = sp_connection_open("172.23.42.29:2342");
//! UdpConnection *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);
//! Bitmap *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);
//! TypedCommand *command = sp_command_bitmap_linear_win(0, 0, pixels, Uncompressed);
//! while (sp_connection_send_command(connection, sp_command_clone(command)));
//!
//! sp_command_free(command);

46
src/packet.rs
View file

@ -1,4 +1,4 @@
//! C functions for interacting with [SPPacket]s
//! C functions for interacting with [Packet]s
//!
//! prefix `sp_packet_`
//!
@ -9,10 +9,10 @@ use crate::SPByteSlice;
use servicepoint::{Header, Packet, TypedCommand};
use std::ptr::NonNull;
/// Turns a [SPCommand] into a [SPPacket].
/// The [SPCommand] gets consumed.
/// Turns a [TypedCommand] into a [Packet].
/// The [TypedCommand] gets consumed.
///
/// Will never return NULL.
/// Returns NULL in case of an error.
///
/// # Panics
///
@ -22,9 +22,9 @@ use std::ptr::NonNull;
///
/// 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
/// - [TypedCommand] points to a valid instance of [TypedCommand]
/// - [TypedCommand] is not used concurrently or after this call
/// - the returned [Packet] 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(
@ -38,7 +38,7 @@ pub unsafe extern "C" fn sp_packet_from_command(
}
}
/// Tries to load a [SPPacket] from the passed array with the specified length.
/// Tries to load a [Packet] from the passed array with the specified length.
///
/// returns: NULL in case of an error, pointer to the allocated packet otherwise
///
@ -52,7 +52,7 @@ pub unsafe extern "C" fn sp_packet_from_command(
///
/// - `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
/// - the returned [Packet] 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: SPByteSlice) -> *mut Packet {
@ -63,7 +63,7 @@ pub unsafe extern "C" fn sp_packet_try_load(data: SPByteSlice) -> *mut Packet {
}
}
/// Creates a raw [SPPacket] from parts.
/// Creates a raw [Packet] from parts.
///
/// # Arguments
///
@ -85,7 +85,7 @@ pub unsafe extern "C" fn sp_packet_try_load(data: SPByteSlice) -> *mut Packet {
///
/// - `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
/// - the returned [Packet] 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(
@ -103,6 +103,9 @@ pub unsafe extern "C" fn sp_packet_from_parts(
NonNull::from(Box::leak(packet))
}
/// Returns a pointer to the header field of the provided packet.
///
/// The returned header can be changed and will be valid for the lifetime of the packet.
#[no_mangle]
pub unsafe extern "C" fn sp_packet_get_header(
packet: NonNull<Packet>,
@ -110,6 +113,9 @@ pub unsafe extern "C" fn sp_packet_get_header(
NonNull::from(&mut unsafe { (*packet.as_ptr()).header })
}
/// Returns a pointer to the current payload of the provided packet.
///
/// The returned memory can be changed and will be valid until a new payload is set.
#[no_mangle]
pub unsafe extern "C" fn sp_packet_get_payload(
packet: NonNull<Packet>,
@ -117,6 +123,9 @@ pub unsafe extern "C" fn sp_packet_get_payload(
unsafe { SPByteSlice::from_slice(&mut *(*packet.as_ptr()).payload) }
}
/// Sets the payload of the provided packet to the provided data.
///
/// This makes previous payload pointers invalid.
#[no_mangle]
pub unsafe extern "C" fn sp_packet_set_payload(
packet: NonNull<Packet>,
@ -125,8 +134,13 @@ pub unsafe extern "C" fn sp_packet_set_payload(
unsafe { (*packet.as_ptr()).payload = data.as_slice().to_vec() }
}
/// Serialize the packet into the provided buffer.
///
/// # Panics
///
/// - if the buffer is not big enough to hold header+payload.
#[no_mangle]
pub unsafe extern "C" fn sp_packet_write_to(
pub unsafe extern "C" fn sp_packet_serialize_to(
packet: NonNull<Packet>,
buffer: SPByteSlice,
) {
@ -135,7 +149,7 @@ pub unsafe extern "C" fn sp_packet_write_to(
}
}
/// Clones a [SPPacket].
/// Clones a [Packet].
///
/// Will never return NULL.
///
@ -147,7 +161,7 @@ pub unsafe extern "C" fn sp_packet_write_to(
///
/// The caller has to make sure that:
///
/// - `packet` points to a valid [SPPacket]
/// - `packet` points to a valid [Packet]
/// - `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`.
@ -159,7 +173,7 @@ pub unsafe extern "C" fn sp_packet_clone(
NonNull::from(Box::leak(result))
}
/// Deallocates a [SPPacket].
/// Deallocates a [Packet].
///
/// # Panics
///
@ -169,7 +183,7 @@ pub unsafe extern "C" fn sp_packet_clone(
///
/// The caller has to make sure that:
///
/// - `packet` points to a valid [SPPacket]
/// - `packet` points to a valid [Packet]
/// - `packet` is not used concurrently or after this call
#[no_mangle]
pub unsafe extern "C" fn sp_packet_free(packet: NonNull<Packet>) {