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

wip fix documentation

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

3
cbindgen.toml
View file

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

2
example/main.c
View file

@ -12,7 +12,7 @@ int main(void) {
sp_bitmap_fill(pixels, true); 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) if (command == NULL)
return 1; 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 servicepoint::{Bitmap, DataRef, Grid};
use std::ptr::NonNull; use std::ptr::NonNull;
use crate::byte_slice::SPByteSlice; use crate::byte_slice::SPByteSlice;
/// Creates a new [SPBitmap] with the specified dimensions. /// Creates a new [Bitmap] with the specified dimensions.
/// ///
/// # Arguments /// # Arguments
/// ///
/// - `width`: size in pixels in x-direction /// - `width`: size in pixels in x-direction
/// - `height`: size in pixels in y-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 /// # 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 /// - the returned instance is freed in some way, either by using a consuming function or
/// by explicitly calling `sp_bitmap_free`. /// 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] #[no_mangle]
pub unsafe extern "C" fn sp_bitmap_new( pub unsafe extern "C" fn sp_bitmap_new(
width: usize, 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 /// # Safety
/// ///
@ -67,14 +61,14 @@ pub unsafe extern "C" fn sp_bitmap_new_screen_sized() -> NonNull<Bitmap> {
NonNull::from(Box::leak(result)) 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 /// # Arguments
/// ///
/// - `width`: size in pixels in x-direction /// - `width`: size in pixels in x-direction
/// - `height`: size in pixels in y-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 /// # Errors
/// ///
@ -108,7 +102,7 @@ pub unsafe extern "C" fn sp_bitmap_load(
} }
} }
/// Clones a [SPBitmap]. /// Clones a [Bitmap].
/// ///
/// Will never return NULL. /// Will never return NULL.
/// ///
@ -120,7 +114,7 @@ pub unsafe extern "C" fn sp_bitmap_load(
/// ///
/// The caller has to make sure that: /// 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 /// - `bitmap` is not written to concurrently
/// - the returned instance is freed in some way, either by using a consuming function or /// - the returned instance is freed in some way, either by using a consuming function or
/// by explicitly calling `sp_bitmap_free`. /// by explicitly calling `sp_bitmap_free`.
@ -132,7 +126,7 @@ pub unsafe extern "C" fn sp_bitmap_clone(
NonNull::from(Box::leak(result)) NonNull::from(Box::leak(result))
} }
/// Deallocates a [SPBitmap]. /// Deallocates a [Bitmap].
/// ///
/// # Panics /// # Panics
/// ///
@ -142,15 +136,15 @@ pub unsafe extern "C" fn sp_bitmap_clone(
/// ///
/// The caller has to make sure that: /// 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] #[no_mangle]
pub unsafe extern "C" fn sp_bitmap_free(bitmap: NonNull<Bitmap>) { pub unsafe extern "C" fn sp_bitmap_free(bitmap: NonNull<Bitmap>) {
_ = unsafe { Box::from_raw(bitmap.as_ptr()) }; _ = 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 /// # Arguments
/// ///
@ -166,7 +160,7 @@ pub unsafe extern "C" fn sp_bitmap_free(bitmap: NonNull<Bitmap>) {
/// ///
/// The caller has to make sure that: /// 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 /// - `bitmap` is not written to concurrently
#[no_mangle] #[no_mangle]
pub unsafe extern "C" fn sp_bitmap_get( 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) } 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 /// # Arguments
/// ///
@ -196,7 +190,7 @@ pub unsafe extern "C" fn sp_bitmap_get(
/// ///
/// The caller has to make sure that: /// 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 /// - `bitmap` is not written to or read from concurrently
#[no_mangle] #[no_mangle]
pub unsafe extern "C" fn sp_bitmap_set( 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) }; 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 /// # Arguments
/// ///
@ -223,14 +217,14 @@ pub unsafe extern "C" fn sp_bitmap_set(
/// ///
/// The caller has to make sure that: /// 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 /// - `bitmap` is not written to or read from concurrently
#[no_mangle] #[no_mangle]
pub unsafe extern "C" fn sp_bitmap_fill(bitmap: NonNull<Bitmap>, value: bool) { pub unsafe extern "C" fn sp_bitmap_fill(bitmap: NonNull<Bitmap>, value: bool) {
unsafe { (*bitmap.as_ptr()).fill(value) }; 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 /// # 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: /// The caller has to make sure that:
/// ///
/// - `bitmap` points to a valid [SPBitmap] /// - `bitmap` points to a valid [Bitmap]
#[no_mangle] #[no_mangle]
pub unsafe extern "C" fn sp_bitmap_width(bitmap: NonNull<Bitmap>) -> usize { pub unsafe extern "C" fn sp_bitmap_width(bitmap: NonNull<Bitmap>) -> usize {
unsafe { bitmap.as_ref().width() } unsafe { bitmap.as_ref().width() }
} }
/// Gets the height in pixels of the [SPBitmap] instance. /// Gets the height in pixels of the [Bitmap] instance.
/// ///
/// # Arguments /// # Arguments
/// ///
@ -264,13 +258,13 @@ pub unsafe extern "C" fn sp_bitmap_width(bitmap: NonNull<Bitmap>) -> usize {
/// ///
/// The caller has to make sure that: /// The caller has to make sure that:
/// ///
/// - `bitmap` points to a valid [SPBitmap] /// - `bitmap` points to a valid [Bitmap]
#[no_mangle] #[no_mangle]
pub unsafe extern "C" fn sp_bitmap_height(bitmap: NonNull<Bitmap>) -> usize { pub unsafe extern "C" fn sp_bitmap_height(bitmap: NonNull<Bitmap>) -> usize {
unsafe { bitmap.as_ref().height() } 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 /// # Panics
/// ///
@ -280,9 +274,9 @@ pub unsafe extern "C" fn sp_bitmap_height(bitmap: NonNull<Bitmap>) -> usize {
/// ///
/// The caller has to make sure that: /// The caller has to make sure that:
/// ///
/// - `bitmap` points to a valid [SPBitmap] /// - `bitmap` points to a valid [Bitmap]
/// - the returned memory range is never accessed after the passed [SPBitmap] has been freed /// - 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 [SPBitmap] or directly /// - the returned memory range is never accessed concurrently, either via the [Bitmap] or directly
#[no_mangle] #[no_mangle]
pub unsafe extern "C" fn sp_bitmap_unsafe_data_ref( pub unsafe extern "C" fn sp_bitmap_unsafe_data_ref(
mut bitmap: NonNull<Bitmap>, 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` points to a valid [SPBitVec]
/// - `bit_vec` is not used concurrently or after this call /// - `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] #[no_mangle]
pub unsafe extern "C" fn sp_bitvec_free(bit_vec: NonNull<SPBitVec>) { pub unsafe extern "C" fn sp_bitvec_free(bit_vec: NonNull<SPBitVec>) {
_ = unsafe { Box::from_raw(bit_vec.as_ptr()) }; _ = 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_` //! prefix `sp_brightness_grid_`
//! //!
@ -7,15 +7,15 @@
//! //!
//! # Examples //! # Examples
//! ```C //! ```C
//! SPConnection connection = sp_connection_open("127.0.0.1:2342"); //! UdpConnection connection = sp_connection_open("127.0.0.1:2342");
//! if (connection == NULL) //! if (connection == NULL)
//! return 1; //! 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, 0, 0, 0);
//! sp_brightness_grid_set(grid, 1, 1, 10); //! 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); //! sp_connection_free(connection);
//! ``` //! ```
@ -24,9 +24,9 @@ use servicepoint::{Brightness, BrightnessGrid, DataRef, Grid};
use std::mem::transmute; use std::mem::transmute;
use std::ptr::NonNull; 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 /// # Safety
/// ///
@ -43,9 +43,9 @@ pub unsafe extern "C" fn sp_brightness_grid_new(
NonNull::from(Box::leak(result)) 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 /// # Panics
/// ///
@ -78,13 +78,13 @@ pub unsafe extern "C" fn sp_brightness_grid_load(
} }
} }
/// Clones a [SPBrightnessGrid]. /// Clones a [BrightnessGrid].
/// ///
/// # Arguments /// # Arguments
/// ///
/// - `brightness_grid`: instance to read from /// - `brightness_grid`: instance to read from
/// ///
/// returns: new [SPBrightnessGrid] instance. Will never return NULL. /// returns: new [BrightnessGrid] instance. Will never return NULL.
/// ///
/// # Panics /// # Panics
/// ///
@ -94,7 +94,7 @@ pub unsafe extern "C" fn sp_brightness_grid_load(
/// ///
/// The caller has to make sure that: /// 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 /// - `brightness_grid` is not written to concurrently
/// - the returned instance is freed in some way, either by using a consuming function or /// - the returned instance is freed in some way, either by using a consuming function or
/// by explicitly calling `sp_brightness_grid_free`. /// 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)) NonNull::from(Box::leak(result))
} }
/// Deallocates a [SPBrightnessGrid]. /// Deallocates a [BrightnessGrid].
/// ///
/// # Arguments /// # Arguments
/// ///
@ -120,11 +120,11 @@ pub unsafe extern "C" fn sp_brightness_grid_clone(
/// ///
/// The caller has to make sure that: /// 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` 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] #[no_mangle]
pub unsafe extern "C" fn sp_brightness_grid_free( pub unsafe extern "C" fn sp_brightness_grid_free(
brightness_grid: NonNull<BrightnessGrid>, brightness_grid: NonNull<BrightnessGrid>,
@ -150,7 +150,7 @@ pub unsafe extern "C" fn sp_brightness_grid_free(
/// ///
/// The caller has to make sure that: /// 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 /// - `brightness_grid` is not written to concurrently
#[no_mangle] #[no_mangle]
pub unsafe extern "C" fn sp_brightness_grid_get( 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) } 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 /// # Arguments
/// ///
@ -181,7 +181,7 @@ pub unsafe extern "C" fn sp_brightness_grid_get(
/// ///
/// The caller has to make sure that: /// 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 /// - `brightness_grid` is not written to or read from concurrently
#[no_mangle] #[no_mangle]
pub unsafe extern "C" fn sp_brightness_grid_set( 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) }; 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 /// # Arguments
/// ///
@ -209,7 +209,7 @@ pub unsafe extern "C" fn sp_brightness_grid_set(
/// ///
/// The caller has to make sure that: /// 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 /// - `brightness_grid` is not written to or read from concurrently
#[no_mangle] #[no_mangle]
pub unsafe extern "C" fn sp_brightness_grid_fill( 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) }; unsafe { (*brightness_grid.as_ptr()).fill(value) };
} }
/// Gets the width of the [SPBrightnessGrid] instance. /// Gets the width of the [BrightnessGrid] instance.
/// ///
/// # Arguments /// # Arguments
/// ///
@ -235,7 +235,7 @@ pub unsafe extern "C" fn sp_brightness_grid_fill(
/// ///
/// The caller has to make sure that: /// The caller has to make sure that:
/// ///
/// - `brightness_grid` points to a valid [SPBrightnessGrid] /// - `brightness_grid` points to a valid [BrightnessGrid]
#[no_mangle] #[no_mangle]
pub unsafe extern "C" fn sp_brightness_grid_width( pub unsafe extern "C" fn sp_brightness_grid_width(
brightness_grid: NonNull<BrightnessGrid>, brightness_grid: NonNull<BrightnessGrid>,
@ -243,7 +243,7 @@ pub unsafe extern "C" fn sp_brightness_grid_width(
unsafe { brightness_grid.as_ref().width() } unsafe { brightness_grid.as_ref().width() }
} }
/// Gets the height of the [SPBrightnessGrid] instance. /// Gets the height of the [BrightnessGrid] instance.
/// ///
/// # Arguments /// # Arguments
/// ///
@ -259,7 +259,7 @@ pub unsafe extern "C" fn sp_brightness_grid_width(
/// ///
/// The caller has to make sure that: /// The caller has to make sure that:
/// ///
/// - `brightness_grid` points to a valid [SPBrightnessGrid] /// - `brightness_grid` points to a valid [BrightnessGrid]
#[no_mangle] #[no_mangle]
pub unsafe extern "C" fn sp_brightness_grid_height( pub unsafe extern "C" fn sp_brightness_grid_height(
brightness_grid: NonNull<BrightnessGrid>, brightness_grid: NonNull<BrightnessGrid>,
@ -267,7 +267,7 @@ pub unsafe extern "C" fn sp_brightness_grid_height(
unsafe { brightness_grid.as_ref().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 /// # Arguments
/// ///
@ -283,9 +283,9 @@ pub unsafe extern "C" fn sp_brightness_grid_height(
/// ///
/// The caller has to make sure that: /// The caller has to make sure that:
/// ///
/// - `brightness_grid` points to a valid [SPBrightnessGrid] /// - `brightness_grid` points to a valid [BrightnessGrid]
/// - the returned memory range is never accessed after the passed [SPBrightnessGrid] has been freed /// - 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 [SPBrightnessGrid] or directly /// - the returned memory range is never accessed concurrently, either via the [BrightnessGrid] or directly
#[no_mangle] #[no_mangle]
pub unsafe extern "C" fn sp_brightness_grid_unsafe_data_ref( pub unsafe extern "C" fn sp_brightness_grid_unsafe_data_ref(
brightness_grid: NonNull<BrightnessGrid>, 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_` //! prefix `sp_char_grid_`
//! //!
@ -22,9 +22,9 @@ use crate::SPByteSlice;
use servicepoint::{CharGrid, Grid}; use servicepoint::{CharGrid, Grid};
use std::ptr::NonNull; 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 /// # Safety
/// ///
@ -41,7 +41,7 @@ pub unsafe extern "C" fn sp_char_grid_new(
NonNull::from(Box::leak(result)) 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. /// Will never return NULL.
/// ///
@ -72,7 +72,7 @@ pub unsafe extern "C" fn sp_char_grid_load(
NonNull::from(Box::leak(result)) NonNull::from(Box::leak(result))
} }
/// Clones a [SPCharGrid]. /// Clones a [CharGrid].
/// ///
/// Will never return NULL. /// Will never return NULL.
/// ///
@ -84,7 +84,7 @@ pub unsafe extern "C" fn sp_char_grid_load(
/// ///
/// The caller has to make sure that: /// 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 /// - `char_grid` is not written to concurrently
/// - the returned instance is freed in some way, either by using a consuming function or /// - the returned instance is freed in some way, either by using a consuming function or
/// by explicitly calling `sp_char_grid_free`. /// 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)) NonNull::from(Box::leak(result))
} }
/// Deallocates a [SPCharGrid]. /// Deallocates a [CharGrid].
/// ///
/// # Panics /// # Panics
/// ///
@ -106,11 +106,11 @@ pub unsafe extern "C" fn sp_char_grid_clone(
/// ///
/// The caller has to make sure that: /// 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` 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] #[no_mangle]
pub unsafe extern "C" fn sp_char_grid_free(char_grid: NonNull<CharGrid>) { pub unsafe extern "C" fn sp_char_grid_free(char_grid: NonNull<CharGrid>) {
_ = unsafe { Box::from_raw(char_grid.as_ptr()) }; _ = 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: /// 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 /// - `char_grid` is not written to concurrently
#[no_mangle] #[no_mangle]
pub unsafe extern "C" fn sp_char_grid_get( 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 } 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 /// # 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()) }; 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 /// # Arguments
/// ///
@ -191,7 +191,7 @@ pub unsafe extern "C" fn sp_char_grid_set(
/// ///
/// The caller has to make sure that: /// 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 /// - `char_grid` is not written to or read from concurrently
#[no_mangle] #[no_mangle]
pub unsafe extern "C" fn sp_char_grid_fill( 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()) }; 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 /// # Arguments
/// ///
@ -215,7 +215,7 @@ pub unsafe extern "C" fn sp_char_grid_fill(
/// ///
/// The caller has to make sure that: /// The caller has to make sure that:
/// ///
/// - `char_grid` points to a valid [SPCharGrid] /// - `char_grid` points to a valid [CharGrid]
#[no_mangle] #[no_mangle]
pub unsafe extern "C" fn sp_char_grid_width( pub unsafe extern "C" fn sp_char_grid_width(
char_grid: NonNull<CharGrid>, char_grid: NonNull<CharGrid>,
@ -223,7 +223,7 @@ pub unsafe extern "C" fn sp_char_grid_width(
unsafe { char_grid.as_ref().width() } unsafe { char_grid.as_ref().width() }
} }
/// Gets the height of the [SPCharGrid] instance. /// Gets the height of the [CharGrid] instance.
/// ///
/// # Arguments /// # Arguments
/// ///
@ -237,7 +237,7 @@ pub unsafe extern "C" fn sp_char_grid_width(
/// ///
/// The caller has to make sure that: /// The caller has to make sure that:
/// ///
/// - `char_grid` points to a valid [SPCharGrid] /// - `char_grid` points to a valid [CharGrid]
#[no_mangle] #[no_mangle]
pub unsafe extern "C" fn sp_char_grid_height( pub unsafe extern "C" fn sp_char_grid_height(
char_grid: NonNull<CharGrid>, 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_` //! prefix `sp_command_`
@ -10,7 +10,7 @@ use std::ptr::NonNull;
/// ///
/// This struct and associated functions implement the UDP protocol for the display. /// 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 /// # Examples
/// ///
@ -18,14 +18,12 @@ use std::ptr::NonNull;
/// sp_connection_send_command(connection, sp_command_clear()); /// sp_connection_send_command(connection, sp_command_clear());
/// sp_connection_send_command(connection, sp_command_brightness(5)); /// 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. /// 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 /// # Panics
/// ///
@ -35,10 +33,10 @@ use std::ptr::NonNull;
/// ///
/// The caller has to make sure that: /// The caller has to make sure that:
/// ///
/// - [SPPacket] points to a valid instance of [SPPacket] /// - [Packet] points to a valid instance of [Packet]
/// - [SPPacket] is not used concurrently or after this call /// - [Packet] is not used concurrently or after this call
/// - the result is checked for NULL /// - 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`. /// by explicitly calling `sp_command_free`.
#[no_mangle] #[no_mangle]
pub unsafe extern "C" fn sp_command_try_from_packet( 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 /// # Panics
/// ///
@ -63,9 +61,9 @@ pub unsafe extern "C" fn sp_command_try_from_packet(
/// ///
/// The caller has to make sure that: /// 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 /// - `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`. /// by explicitly calling `sp_command_free`.
#[no_mangle] #[no_mangle]
pub unsafe extern "C" fn sp_command_clone( 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 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`. /// by explicitly calling `sp_command_free`.
#[no_mangle] #[no_mangle]
pub unsafe extern "C" fn sp_command_clear() -> NonNull<TypedCommand> { 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 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`. /// by explicitly calling `sp_command_free`.
#[no_mangle] #[no_mangle]
pub unsafe extern "C" fn sp_command_hard_reset() -> NonNull<TypedCommand> { 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 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`. /// by explicitly calling `sp_command_free`.
#[no_mangle] #[no_mangle]
pub unsafe extern "C" fn sp_command_fade_out() -> NonNull<TypedCommand> { 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 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`. /// by explicitly calling `sp_command_free`.
#[no_mangle] #[no_mangle]
pub unsafe extern "C" fn sp_command_brightness( 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. /// 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. /// 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: /// 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 /// - `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`. /// by explicitly calling `sp_command_free`.
#[no_mangle] #[no_mangle]
pub unsafe extern "C" fn sp_command_char_brightness( 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` points to a valid instance of [SPBitVec]
/// - `bit_vec` is not used concurrently or after this call /// - `bit_vec` is not used concurrently or after this call
/// - `compression` matches one of the allowed enum values /// - `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`. /// by explicitly calling `sp_command_free`.
#[no_mangle] #[no_mangle]
pub unsafe extern "C" fn sp_command_bitmap_linear( 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` points to a valid instance of [SPBitVec]
/// - `bit_vec` is not used concurrently or after this call /// - `bit_vec` is not used concurrently or after this call
/// - `compression` matches one of the allowed enum values /// - `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`. /// by explicitly calling `sp_command_free`.
#[no_mangle] #[no_mangle]
pub unsafe extern "C" fn sp_command_bitmap_linear_and( 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` points to a valid instance of [SPBitVec]
/// - `bit_vec` is not used concurrently or after this call /// - `bit_vec` is not used concurrently or after this call
/// - `compression` matches one of the allowed enum values /// - `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`. /// by explicitly calling `sp_command_free`.
#[no_mangle] #[no_mangle]
pub unsafe extern "C" fn sp_command_bitmap_linear_or( 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` points to a valid instance of [SPBitVec]
/// - `bit_vec` is not used concurrently or after this call /// - `bit_vec` is not used concurrently or after this call
/// - `compression` matches one of the allowed enum values /// - `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`. /// by explicitly calling `sp_command_free`.
#[no_mangle] #[no_mangle]
pub unsafe extern "C" fn sp_command_bitmap_linear_xor( 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. /// 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. /// 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: /// 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 /// - `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`. /// by explicitly calling `sp_command_free`.
#[no_mangle] #[no_mangle]
pub unsafe extern "C" fn sp_command_cp437_data( 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. /// 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. /// 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: /// 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 /// - `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`. /// by explicitly calling `sp_command_free`.
#[no_mangle] #[no_mangle]
pub unsafe extern "C" fn sp_command_utf8_data( 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. /// 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. /// 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: /// 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 /// - `bitmap` is not used concurrently or after this call
/// - `compression` matches one of the allowed enum values /// - `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`. /// by explicitly calling `sp_command_free`.
#[no_mangle] #[no_mangle]
pub unsafe extern "C" fn sp_command_bitmap_linear_win( 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)) Box::leak(Box::new(command))
} }
/// Deallocates a [SPCommand]. /// Deallocates a [TypedCommand].
/// ///
/// # Examples /// # Examples
/// ///
/// ```C /// ```C
/// SPCommand c = sp_command_clear(); /// TypedCommand c = sp_command_clear();
/// sp_command_free(c); /// 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: /// 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` 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] #[no_mangle]
pub unsafe extern "C" fn sp_command_free(command: NonNull<TypedCommand>) { pub unsafe extern "C" fn sp_command_free(command: NonNull<TypedCommand>) {
_ = unsafe { Box::from_raw(command.as_ptr()) }; _ = 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_` //! prefix `sp_connection_`
//! //!
@ -16,7 +16,7 @@ use servicepoint::{Connection, Packet, TypedCommand, UdpConnection};
use std::ffi::{c_char, CStr}; use std::ffi::{c_char, CStr};
use std::ptr::NonNull; use std::ptr::NonNull;
/// Creates a new instance of [SPConnection]. /// Creates a new instance of [UdpConnection].
/// ///
/// returns: NULL if connection fails, or connected instance /// returns: NULL if connection fails, or connected instance
/// ///
@ -48,13 +48,13 @@ pub unsafe extern "C" fn sp_connection_open(
//#[no_mangle] //#[no_mangle]
//pub unsafe extern "C" fn sp_connection_open_ipv4( //pub unsafe extern "C" fn sp_connection_open_ipv4(
// host: SocketAddrV4, // host: SocketAddrV4,
//) -> *mut SPConnection { //) -> *mut UdpConnection {
// let connection = match servicepoint::UdpConnection::open(host) { // let connection = match servicepoint::UdpConnection::open(host) {
// Err(_) => return std::ptr::null_mut(), // Err(_) => return std::ptr::null_mut(),
// Ok(value) => value, // 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. // /// 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)) // 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. /// The passed `packet` gets consumed.
/// ///
@ -88,8 +88,8 @@ pub unsafe extern "C" fn sp_connection_open(
/// ///
/// The caller has to make sure that: /// The caller has to make sure that:
/// ///
/// - `connection` points to a valid instance of [SPConnection] /// - `connection` points to a valid instance of [UdpConnection]
/// - `packet` points to a valid instance of [SPPacket] /// - `packet` points to a valid instance of [Packet]
/// - `packet` is not used concurrently or after this call /// - `packet` is not used concurrently or after this call
#[no_mangle] #[no_mangle]
pub unsafe extern "C" fn sp_connection_send_packet( 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() 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. /// 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: /// The caller has to make sure that:
/// ///
/// - `connection` points to a valid instance of [SPConnection] /// - `connection` points to a valid instance of [UdpConnection]
/// - `command` points to a valid instance of [SPPacket] /// - `command` points to a valid instance of [Packet]
/// - `command` is not used concurrently or after this call /// - `command` is not used concurrently or after this call
#[no_mangle] #[no_mangle]
pub unsafe extern "C" fn sp_connection_send_command( 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() unsafe { connection.as_ref().send(command) }.is_ok()
} }
/// Closes and deallocates a [SPConnection]. /// Closes and deallocates a [UdpConnection].
/// ///
/// # Panics /// # Panics
/// ///
@ -137,7 +137,7 @@ pub unsafe extern "C" fn sp_connection_send_command(
/// ///
/// The caller has to make sure that: /// 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 /// - `connection` is not used concurrently or after this call
#[no_mangle] #[no_mangle]
pub unsafe extern "C" fn sp_connection_free( 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_` //! prefix `sp_cp437_grid_`
//! //!
@ -20,9 +20,9 @@ use crate::SPByteSlice;
use servicepoint::{Cp437Grid, DataRef, Grid}; use servicepoint::{Cp437Grid, DataRef, Grid};
use std::ptr::NonNull; 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 /// # Safety
/// ///
@ -39,7 +39,7 @@ pub unsafe extern "C" fn sp_cp437_grid_new(
NonNull::from(Box::leak(result)) 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. /// 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. /// Will never return NULL.
/// ///
@ -83,7 +83,7 @@ pub unsafe extern "C" fn sp_cp437_grid_load(
/// ///
/// The caller has to make sure that: /// 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 /// - `cp437_grid` is not written to concurrently
/// - the returned instance is freed in some way, either by using a consuming function or /// - the returned instance is freed in some way, either by using a consuming function or
/// by explicitly calling `sp_cp437_grid_free`. /// 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)) NonNull::from(Box::leak(result))
} }
/// Deallocates a [SPCp437Grid]. /// Deallocates a [Cp437Grid].
/// ///
/// # Panics /// # Panics
/// ///
@ -105,11 +105,11 @@ pub unsafe extern "C" fn sp_cp437_grid_clone(
/// ///
/// The caller has to make sure that: /// 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` 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] #[no_mangle]
pub unsafe extern "C" fn sp_cp437_grid_free(cp437_grid: NonNull<Cp437Grid>) { pub unsafe extern "C" fn sp_cp437_grid_free(cp437_grid: NonNull<Cp437Grid>) {
_ = unsafe { Box::from_raw(cp437_grid.as_ptr()) }; _ = 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: /// 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 /// - `cp437_grid` is not written to concurrently
#[no_mangle] #[no_mangle]
pub unsafe extern "C" fn sp_cp437_grid_get( 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) } 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 /// # Arguments
/// ///
@ -175,7 +175,7 @@ pub unsafe extern "C" fn sp_cp437_grid_set(
unsafe { (*cp437_grid.as_ptr()).set(x, y, value) }; 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 /// # Arguments
/// ///
@ -190,7 +190,7 @@ pub unsafe extern "C" fn sp_cp437_grid_set(
/// ///
/// The caller has to make sure that: /// 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 /// - `cp437_grid` is not written to or read from concurrently
#[no_mangle] #[no_mangle]
pub unsafe extern "C" fn sp_cp437_grid_fill( 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) }; unsafe { (*cp437_grid.as_ptr()).fill(value) };
} }
/// Gets the width of the [SPCp437Grid] instance. /// Gets the width of the [Cp437Grid] instance.
/// ///
/// # Arguments /// # Arguments
/// ///
@ -214,7 +214,7 @@ pub unsafe extern "C" fn sp_cp437_grid_fill(
/// ///
/// The caller has to make sure that: /// The caller has to make sure that:
/// ///
/// - `cp437_grid` points to a valid [SPCp437Grid] /// - `cp437_grid` points to a valid [Cp437Grid]
#[no_mangle] #[no_mangle]
pub unsafe extern "C" fn sp_cp437_grid_width( pub unsafe extern "C" fn sp_cp437_grid_width(
cp437_grid: NonNull<Cp437Grid>, cp437_grid: NonNull<Cp437Grid>,
@ -222,7 +222,7 @@ pub unsafe extern "C" fn sp_cp437_grid_width(
unsafe { cp437_grid.as_ref().width() } unsafe { cp437_grid.as_ref().width() }
} }
/// Gets the height of the [SPCp437Grid] instance. /// Gets the height of the [Cp437Grid] instance.
/// ///
/// # Arguments /// # Arguments
/// ///
@ -236,7 +236,7 @@ pub unsafe extern "C" fn sp_cp437_grid_width(
/// ///
/// The caller has to make sure that: /// The caller has to make sure that:
/// ///
/// - `cp437_grid` points to a valid [SPCp437Grid] /// - `cp437_grid` points to a valid [Cp437Grid]
#[no_mangle] #[no_mangle]
pub unsafe extern "C" fn sp_cp437_grid_height( pub unsafe extern "C" fn sp_cp437_grid_height(
cp437_grid: NonNull<Cp437Grid>, cp437_grid: NonNull<Cp437Grid>,
@ -244,7 +244,7 @@ pub unsafe extern "C" fn sp_cp437_grid_height(
unsafe { cp437_grid.as_ref().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. /// Will never return NULL.
/// ///
@ -256,9 +256,9 @@ pub unsafe extern "C" fn sp_cp437_grid_height(
/// ///
/// The caller has to make sure that: /// The caller has to make sure that:
/// ///
/// - `cp437_grid` points to a valid [SPCp437Grid] /// - `cp437_grid` points to a valid [Cp437Grid]
/// - the returned memory range is never accessed after the passed [SPCp437Grid] has been freed /// - 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 [SPCp437Grid] or directly /// - the returned memory range is never accessed concurrently, either via the [Cp437Grid] or directly
#[no_mangle] #[no_mangle]
pub unsafe extern "C" fn sp_cp437_grid_unsafe_data_ref( pub unsafe extern "C" fn sp_cp437_grid_unsafe_data_ref(
cp437_grid: NonNull<Cp437Grid>, cp437_grid: NonNull<Cp437Grid>,

6
src/lib.rs
View file

@ -9,14 +9,14 @@
//! #include "servicepoint.h" //! #include "servicepoint.h"
//! //!
//! int main(void) { //! 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) //! if (connection == NULL)
//! return 1; //! 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); //! 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))); //! while (sp_connection_send_command(connection, sp_command_clone(command)));
//! //!
//! sp_command_free(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_` //! prefix `sp_packet_`
//! //!
@ -9,10 +9,10 @@ use crate::SPByteSlice;
use servicepoint::{Header, Packet, TypedCommand}; use servicepoint::{Header, Packet, TypedCommand};
use std::ptr::NonNull; use std::ptr::NonNull;
/// Turns a [SPCommand] into a [SPPacket]. /// Turns a [TypedCommand] into a [Packet].
/// The [SPCommand] gets consumed. /// The [TypedCommand] gets consumed.
/// ///
/// Will never return NULL. /// Returns NULL in case of an error.
/// ///
/// # Panics /// # Panics
/// ///
@ -22,9 +22,9 @@ use std::ptr::NonNull;
/// ///
/// The caller has to make sure that: /// The caller has to make sure that:
/// ///
/// - [SPCommand] points to a valid instance of [SPCommand] /// - [TypedCommand] points to a valid instance of [TypedCommand]
/// - [SPCommand] is not used concurrently or after this call /// - [TypedCommand] is not used concurrently or after this call
/// - 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`. /// by explicitly calling `sp_packet_free`.
#[no_mangle] #[no_mangle]
pub unsafe extern "C" fn sp_packet_from_command( 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 /// 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` points to a valid memory region of at least `length` bytes
/// - `data` is not written to concurrently /// - `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`. /// by explicitly calling `sp_packet_free`.
#[no_mangle] #[no_mangle]
pub unsafe extern "C" fn sp_packet_try_load(data: SPByteSlice) -> *mut Packet { 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 /// # 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` points to a valid memory region of at least `payload_len` bytes
/// - `payload` is not written to concurrently /// - `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]. /// by explicitly calling [sp_packet_free].
#[no_mangle] #[no_mangle]
pub unsafe extern "C" fn sp_packet_from_parts( 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)) 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] #[no_mangle]
pub unsafe extern "C" fn sp_packet_get_header( pub unsafe extern "C" fn sp_packet_get_header(
packet: NonNull<Packet>, packet: NonNull<Packet>,
@ -110,6 +113,9 @@ pub unsafe extern "C" fn sp_packet_get_header(
NonNull::from(&mut unsafe { (*packet.as_ptr()).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] #[no_mangle]
pub unsafe extern "C" fn sp_packet_get_payload( pub unsafe extern "C" fn sp_packet_get_payload(
packet: NonNull<Packet>, 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) } 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] #[no_mangle]
pub unsafe extern "C" fn sp_packet_set_payload( pub unsafe extern "C" fn sp_packet_set_payload(
packet: NonNull<Packet>, 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() } 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] #[no_mangle]
pub unsafe extern "C" fn sp_packet_write_to( pub unsafe extern "C" fn sp_packet_serialize_to(
packet: NonNull<Packet>, packet: NonNull<Packet>,
buffer: SPByteSlice, 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. /// Will never return NULL.
/// ///
@ -147,7 +161,7 @@ pub unsafe extern "C" fn sp_packet_write_to(
/// ///
/// The caller has to make sure that: /// 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 /// - `packet` is not written to concurrently
/// - the returned instance is freed in some way, either by using a consuming function or /// - the returned instance is freed in some way, either by using a consuming function or
/// by explicitly calling `sp_packet_free`. /// by explicitly calling `sp_packet_free`.
@ -159,7 +173,7 @@ pub unsafe extern "C" fn sp_packet_clone(
NonNull::from(Box::leak(result)) NonNull::from(Box::leak(result))
} }
/// Deallocates a [SPPacket]. /// Deallocates a [Packet].
/// ///
/// # Panics /// # Panics
/// ///
@ -169,7 +183,7 @@ pub unsafe extern "C" fn sp_packet_clone(
/// ///
/// The caller has to make sure that: /// 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 /// - `packet` is not used concurrently or after this call
#[no_mangle] #[no_mangle]
pub unsafe extern "C" fn sp_packet_free(packet: NonNull<Packet>) { pub unsafe extern "C" fn sp_packet_free(packet: NonNull<Packet>) {