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

doc changes

Browse source
This commit is contained in:
Vinzenz Schroeter 2025-05-07 08:29:16 +02:00
parent a4bacd53a2
commit e7cad5b5a3
6 changed files with 87 additions and 31 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

66
include/servicepoint.h
View file

@ -125,6 +125,11 @@ enum CommandCode
typedef uint16_t CommandCode; typedef uint16_t CommandCode;
#endif // __cplusplus #endif // __cplusplus
/**
* Specifies the kind of command struct.
*
* This is _not_ equivalent to the [servicepoint::CommandCode]s.
*/
enum CommandTag enum CommandTag
#ifdef __cplusplus #ifdef __cplusplus
: uint8_t : uint8_t
@ -531,6 +536,9 @@ typedef size_t Offset;
*/ */
typedef ValueGrid_u8 Cp437Grid; typedef ValueGrid_u8 Cp437Grid;
/**
* Pointer to one of the available command structs.
*/
typedef union { typedef union {
uint8_t *null; uint8_t *null;
BitmapCommand */*notnull*/ bitmap; BitmapCommand */*notnull*/ bitmap;
@ -545,6 +553,13 @@ typedef union {
FadeOutCommand */*notnull*/ fade_out; FadeOutCommand */*notnull*/ fade_out;
} CommandUnion; } CommandUnion;
/**
* This struct represents a pointer to one of the possible command structs.
*
* Only ever access `data` with the correct data type as specified by `tag`!
*
* Rust equivalent: [TypedCommand].
*/
typedef struct { typedef struct {
/** /**
* Specifies which kind of command struct is contained in `data` * Specifies which kind of command struct is contained in `data`
@ -754,12 +769,12 @@ ByteSlice sp_bitmap_unsafe_data_ref(Bitmap */*notnull*/ bitmap);
size_t sp_bitmap_width(Bitmap */*notnull*/ bitmap); size_t sp_bitmap_width(Bitmap */*notnull*/ bitmap);
/** /**
* Clones a [SPBitVec]. * Clones a [DisplayBitVec].
*/ */
DisplayBitVec */*notnull*/ sp_bitvec_clone(DisplayBitVec */*notnull*/ bit_vec); DisplayBitVec */*notnull*/ sp_bitvec_clone(DisplayBitVec */*notnull*/ bit_vec);
/** /**
* Sets the value of all bits in the [SPBitVec]. * Sets the value of all bits in the [DisplayBitVec].
* *
* # Arguments * # Arguments
* *
@ -769,12 +784,12 @@ DisplayBitVec */*notnull*/ sp_bitvec_clone(DisplayBitVec */*notnull*/ bit_vec);
void sp_bitvec_fill(DisplayBitVec */*notnull*/ bit_vec, bool value); void sp_bitvec_fill(DisplayBitVec */*notnull*/ bit_vec, bool value);
/** /**
* Deallocates a [SPBitVec]. * Deallocates a [DisplayBitVec].
*/ */
void sp_bitvec_free(DisplayBitVec */*notnull*/ bit_vec); void sp_bitvec_free(DisplayBitVec */*notnull*/ bit_vec);
/** /**
* Gets the value of a bit from the [SPBitVec]. * Gets the value of a bit from the [DisplayBitVec].
* *
* # Arguments * # Arguments
* *
@ -792,7 +807,7 @@ bool sp_bitvec_get(DisplayBitVec */*notnull*/ bit_vec, size_t index);
/** /**
* Creates a [BitVecCommand] and immediately turns that into a [Packet]. * Creates a [BitVecCommand] and immediately turns that into a [Packet].
* *
* The provided [SPBitVec] gets consumed. * The provided [DisplayBitVec] gets consumed.
* *
* Returns NULL in case of an error. * Returns NULL in case of an error.
*/ */
@ -811,7 +826,7 @@ Packet *sp_bitvec_into_packet(DisplayBitVec */*notnull*/ bitvec,
bool sp_bitvec_is_empty(DisplayBitVec */*notnull*/ bit_vec); bool sp_bitvec_is_empty(DisplayBitVec */*notnull*/ bit_vec);
/** /**
* Gets the length of the [SPBitVec] in bits. * Gets the length of the [DisplayBitVec] in bits.
* *
* # Arguments * # Arguments
* *
@ -820,20 +835,20 @@ bool sp_bitvec_is_empty(DisplayBitVec */*notnull*/ bit_vec);
size_t sp_bitvec_len(DisplayBitVec */*notnull*/ bit_vec); size_t sp_bitvec_len(DisplayBitVec */*notnull*/ bit_vec);
/** /**
* Interpret the data as a series of bits and load then into a new [SPBitVec] instance. * Interpret the data as a series of bits and load then into a new [DisplayBitVec] instance.
* *
* returns: [SPBitVec] instance containing data. * returns: [DisplayBitVec] instance containing data.
*/ */
DisplayBitVec */*notnull*/ sp_bitvec_load(ByteSlice data); DisplayBitVec */*notnull*/ sp_bitvec_load(ByteSlice data);
/** /**
* Creates a new [SPBitVec] instance. * Creates a new [DisplayBitVec] instance.
* *
* # Arguments * # Arguments
* *
* - `size`: size in bits. * - `size`: size in bits.
* *
* returns: [SPBitVec] with all bits set to false. * returns: [DisplayBitVec] with all bits set to false.
* *
* # Panics * # Panics
* *
@ -842,7 +857,7 @@ DisplayBitVec */*notnull*/ sp_bitvec_load(ByteSlice data);
DisplayBitVec */*notnull*/ sp_bitvec_new(size_t size); DisplayBitVec */*notnull*/ sp_bitvec_new(size_t size);
/** /**
* Sets the value of a bit in the [SPBitVec]. * Sets the value of a bit in the [DisplayBitVec].
* *
* # Arguments * # Arguments
* *
@ -859,7 +874,7 @@ void sp_bitvec_set(DisplayBitVec */*notnull*/ bit_vec,
bool value); bool value);
/** /**
* Gets an unsafe reference to the data of the [SPBitVec] instance. * Gets an unsafe reference to the data of the [DisplayBitVec] instance.
* *
* The returned memory is valid for the lifetime of the bitvec. * The returned memory is valid for the lifetime of the bitvec.
* *
@ -1119,7 +1134,7 @@ void sp_cmd_bitmap_free(BitmapCommand */*notnull*/ command);
* Move the provided [Bitmap] into a new [BitmapCommand], * Move the provided [Bitmap] into a new [BitmapCommand],
* leaving other fields as their default values. * leaving other fields as their default values.
* *
* Rust equivalent: [`<BitmapCommand as From<Bitmap>>::from`] * Rust equivalent: `BitmapCommand::from(bitmap)`
*/ */
BitmapCommand */*notnull*/ sp_cmd_bitmap_from_bitmap(Bitmap */*notnull*/ bitmap); BitmapCommand */*notnull*/ sp_cmd_bitmap_from_bitmap(Bitmap */*notnull*/ bitmap);
@ -1311,6 +1326,11 @@ Cp437GridCommand */*notnull*/ sp_cmd_cp437_grid_from_grid(Cp437Grid */*notnull*/
Cp437Grid *sp_cmd_cp437_grid_get(Cp437GridCommand */*notnull*/ command); Cp437Grid *sp_cmd_cp437_grid_get(Cp437GridCommand */*notnull*/ command);
/**
* Gets the origin field of the [Cp437GridCommand].
*
* Rust equivalent: `cp437_command.origin`
*/
void sp_cmd_cp437_grid_get_origin(Cp437GridCommand */*notnull*/ command, void sp_cmd_cp437_grid_get_origin(Cp437GridCommand */*notnull*/ command,
size_t */*notnull*/ origin_x, size_t */*notnull*/ origin_x,
size_t */*notnull*/ origin_y); size_t */*notnull*/ origin_y);
@ -1322,11 +1342,18 @@ Cp437GridCommand */*notnull*/ sp_cmd_cp437_grid_new(Cp437Grid */*notnull*/ grid,
size_t origin_y); size_t origin_y);
/** /**
* Moves the provided bitmap to be contained in the command. * Moves the provided bitmap into the provided command.
*
* This drops the previously contained [Cp437Grid].
*/ */
void sp_cmd_cp437_grid_set(Cp437GridCommand */*notnull*/ command, void sp_cmd_cp437_grid_set(Cp437GridCommand */*notnull*/ command,
Cp437Grid */*notnull*/ grid); Cp437Grid */*notnull*/ grid);
/**
* Sets the origin field of the [Cp437GridCommand].
*
* Rust equivalent: `cp437_command.origin = Origin::new(origin_x, origin_y)`
*/
void sp_cmd_cp437_grid_set_origin(Cp437GridCommand */*notnull*/ command, void sp_cmd_cp437_grid_set_origin(Cp437GridCommand */*notnull*/ command,
size_t origin_x, size_t origin_x,
size_t origin_y); size_t origin_y);
@ -1367,6 +1394,15 @@ void sp_cmd_generic_free(SPCommand command);
*/ */
Packet *sp_cmd_generic_into_packet(SPCommand command); Packet *sp_cmd_generic_into_packet(SPCommand command);
/**
* Tries to turn a [Packet] into a [TypedCommand].
*
* The packet is deallocated in the process.
*
* Returns: pointer to new [TypedCommand] instance or NULL if parsing failed.
*/
SPCommand *sp_cmd_generic_try_from_packet(Packet */*notnull*/ packet);
void sp_cmd_hard_reset_free(ClearCommand */*notnull*/ command); void sp_cmd_hard_reset_free(ClearCommand */*notnull*/ command);
/** /**
@ -1585,7 +1621,7 @@ UdpSocket *sp_udp_open_ipv4(uint8_t ip1,
uint16_t port); uint16_t port);
/** /**
* Sends a [TypedCommand] to the display using the [UdpSocket]. * Sends a [SPCommand] to the display using the [UdpSocket].
* *
* The passed `command` gets consumed. * The passed `command` gets consumed.
* *

24
src/bitvec.rs
View file

@ -7,13 +7,13 @@ use servicepoint::{
}; };
use std::ptr::NonNull; use std::ptr::NonNull;
/// Creates a new [SPBitVec] instance. /// Creates a new [DisplayBitVec] instance.
/// ///
/// # Arguments /// # Arguments
/// ///
/// - `size`: size in bits. /// - `size`: size in bits.
/// ///
/// returns: [SPBitVec] with all bits set to false. /// returns: [DisplayBitVec] with all bits set to false.
/// ///
/// # Panics /// # Panics
/// ///
@ -23,9 +23,9 @@ pub unsafe extern "C" fn sp_bitvec_new(size: usize) -> NonNull<DisplayBitVec> {
heap_move_nonnull(DisplayBitVec::repeat(false, size)) heap_move_nonnull(DisplayBitVec::repeat(false, size))
} }
/// Interpret the data as a series of bits and load then into a new [SPBitVec] instance. /// Interpret the data as a series of bits and load then into a new [DisplayBitVec] instance.
/// ///
/// returns: [SPBitVec] instance containing data. /// returns: [DisplayBitVec] instance containing data.
#[no_mangle] #[no_mangle]
pub unsafe extern "C" fn sp_bitvec_load( pub unsafe extern "C" fn sp_bitvec_load(
data: ByteSlice, data: ByteSlice,
@ -34,7 +34,7 @@ pub unsafe extern "C" fn sp_bitvec_load(
heap_move_nonnull(DisplayBitVec::from_slice(data)) heap_move_nonnull(DisplayBitVec::from_slice(data))
} }
/// Clones a [SPBitVec]. /// Clones a [DisplayBitVec].
#[no_mangle] #[no_mangle]
pub unsafe extern "C" fn sp_bitvec_clone( pub unsafe extern "C" fn sp_bitvec_clone(
bit_vec: NonNull<DisplayBitVec>, bit_vec: NonNull<DisplayBitVec>,
@ -42,13 +42,13 @@ pub unsafe extern "C" fn sp_bitvec_clone(
unsafe { heap_clone(bit_vec) } unsafe { heap_clone(bit_vec) }
} }
/// Deallocates a [SPBitVec]. /// Deallocates a [DisplayBitVec].
#[no_mangle] #[no_mangle]
pub unsafe extern "C" fn sp_bitvec_free(bit_vec: NonNull<DisplayBitVec>) { pub unsafe extern "C" fn sp_bitvec_free(bit_vec: NonNull<DisplayBitVec>) {
unsafe { heap_drop(bit_vec) } unsafe { heap_drop(bit_vec) }
} }
/// Gets the value of a bit from the [SPBitVec]. /// Gets the value of a bit from the [DisplayBitVec].
/// ///
/// # Arguments /// # Arguments
/// ///
@ -68,7 +68,7 @@ pub unsafe extern "C" fn sp_bitvec_get(
unsafe { *bit_vec.as_ref().get(index).unwrap() } unsafe { *bit_vec.as_ref().get(index).unwrap() }
} }
/// Sets the value of a bit in the [SPBitVec]. /// Sets the value of a bit in the [DisplayBitVec].
/// ///
/// # Arguments /// # Arguments
/// ///
@ -88,7 +88,7 @@ pub unsafe extern "C" fn sp_bitvec_set(
unsafe { (*bit_vec.as_ptr()).set(index, value) } unsafe { (*bit_vec.as_ptr()).set(index, value) }
} }
/// Sets the value of all bits in the [SPBitVec]. /// Sets the value of all bits in the [DisplayBitVec].
/// ///
/// # Arguments /// # Arguments
/// ///
@ -102,7 +102,7 @@ pub unsafe extern "C" fn sp_bitvec_fill(
unsafe { (*bit_vec.as_ptr()).fill(value) } unsafe { (*bit_vec.as_ptr()).fill(value) }
} }
/// Gets the length of the [SPBitVec] in bits. /// Gets the length of the [DisplayBitVec] in bits.
/// ///
/// # Arguments /// # Arguments
/// ///
@ -126,7 +126,7 @@ pub unsafe extern "C" fn sp_bitvec_is_empty(
unsafe { bit_vec.as_ref().is_empty() } unsafe { bit_vec.as_ref().is_empty() }
} }
/// Gets an unsafe reference to the data of the [SPBitVec] instance. /// Gets an unsafe reference to the data of the [DisplayBitVec] instance.
/// ///
/// The returned memory is valid for the lifetime of the bitvec. /// The returned memory is valid for the lifetime of the bitvec.
/// ///
@ -142,7 +142,7 @@ pub unsafe extern "C" fn sp_bitvec_unsafe_data_ref(
/// Creates a [BitVecCommand] and immediately turns that into a [Packet]. /// Creates a [BitVecCommand] and immediately turns that into a [Packet].
/// ///
/// The provided [SPBitVec] gets consumed. /// The provided [DisplayBitVec] gets consumed.
/// ///
/// Returns NULL in case of an error. /// Returns NULL in case of an error.
#[no_mangle] #[no_mangle]

2
src/commands/bitmap_command.rs
View file

@ -26,7 +26,7 @@ pub unsafe extern "C" fn sp_cmd_bitmap_new(
/// Move the provided [Bitmap] into a new [BitmapCommand], /// Move the provided [Bitmap] into a new [BitmapCommand],
/// leaving other fields as their default values. /// leaving other fields as their default values.
/// ///
/// Rust equivalent: [`<BitmapCommand as From<Bitmap>>::from`] /// Rust equivalent: `BitmapCommand::from(bitmap)`
#[no_mangle] #[no_mangle]
pub unsafe extern "C" fn sp_cmd_bitmap_from_bitmap( pub unsafe extern "C" fn sp_cmd_bitmap_from_bitmap(
bitmap: NonNull<Bitmap>, bitmap: NonNull<Bitmap>,

11
src/commands/cp437_grid_command.rs
View file

@ -46,7 +46,9 @@ pub unsafe extern "C" fn sp_cmd_cp437_grid_free(
unsafe { heap_drop(command) } unsafe { heap_drop(command) }
} }
/// Moves the provided bitmap to be contained in the command. /// Moves the provided bitmap into the provided command.
///
/// This drops the previously contained [Cp437Grid].
#[no_mangle] #[no_mangle]
pub unsafe extern "C" fn sp_cmd_cp437_grid_set( pub unsafe extern "C" fn sp_cmd_cp437_grid_set(
mut command: NonNull<Cp437GridCommand>, mut command: NonNull<Cp437GridCommand>,
@ -64,6 +66,9 @@ pub unsafe extern "C" fn sp_cmd_cp437_grid_get(
&mut unsafe { command.as_mut() }.grid &mut unsafe { command.as_mut() }.grid
} }
/// Gets the origin field of the [Cp437GridCommand].
///
/// Rust equivalent: `cp437_command.origin`
#[no_mangle] #[no_mangle]
pub unsafe extern "C" fn sp_cmd_cp437_grid_get_origin( pub unsafe extern "C" fn sp_cmd_cp437_grid_get_origin(
command: NonNull<Cp437GridCommand>, command: NonNull<Cp437GridCommand>,
@ -77,6 +82,10 @@ pub unsafe extern "C" fn sp_cmd_cp437_grid_get_origin(
} }
} }
/// Sets the origin field of the [Cp437GridCommand].
///
/// Rust equivalent: `cp437_command.origin = Origin::new(origin_x, origin_y)`
#[no_mangle] #[no_mangle]
pub unsafe extern "C" fn sp_cmd_cp437_grid_set_origin( pub unsafe extern "C" fn sp_cmd_cp437_grid_set_origin(
mut command: NonNull<Cp437GridCommand>, mut command: NonNull<Cp437GridCommand>,

13
src/commands/generic_command.rs
View file

@ -8,7 +8,9 @@ use servicepoint::{
}; };
use std::ptr::{null_mut, NonNull}; use std::ptr::{null_mut, NonNull};
/// Pointer to one of the available command structs.
#[repr(C)] #[repr(C)]
#[allow(missing_docs)]
pub union CommandUnion { pub union CommandUnion {
pub null: *mut u8, pub null: *mut u8,
pub bitmap: NonNull<BitmapCommand>, pub bitmap: NonNull<BitmapCommand>,
@ -24,7 +26,11 @@ pub union CommandUnion {
pub fade_out: NonNull<FadeOutCommand>, pub fade_out: NonNull<FadeOutCommand>,
} }
/// Specifies the kind of command struct.
///
/// This is _not_ equivalent to the [servicepoint::CommandCode]s.
#[repr(u8)] #[repr(u8)]
#[allow(missing_docs)]
pub enum CommandTag { pub enum CommandTag {
Invalid = 0, Invalid = 0,
Bitmap, Bitmap,
@ -39,6 +45,11 @@ pub enum CommandTag {
BitmapLegacy, BitmapLegacy,
} }
/// This struct represents a pointer to one of the possible command structs.
///
/// Only ever access `data` with the correct data type as specified by `tag`!
///
/// Rust equivalent: [TypedCommand].
#[repr(C)] #[repr(C)]
pub struct SPCommand { pub struct SPCommand {
/// Specifies which kind of command struct is contained in `data` /// Specifies which kind of command struct is contained in `data`
@ -59,7 +70,7 @@ impl SPCommand {
/// The packet is deallocated in the process. /// The packet is deallocated in the process.
/// ///
/// Returns: pointer to new [TypedCommand] instance or NULL if parsing failed. /// Returns: pointer to new [TypedCommand] instance or NULL if parsing failed.
/// #[no_mangle] #[no_mangle]
pub unsafe extern "C" fn sp_cmd_generic_try_from_packet( pub unsafe extern "C" fn sp_cmd_generic_try_from_packet(
packet: NonNull<Packet>, packet: NonNull<Packet>,
) -> *mut SPCommand { ) -> *mut SPCommand {

2
src/udp.rs
View file

@ -62,7 +62,7 @@ pub unsafe extern "C" fn sp_udp_send_packet(
unsafe { connection.as_ref().send(&Vec::from(packet)) }.is_ok() unsafe { connection.as_ref().send(&Vec::from(packet)) }.is_ok()
} }
/// Sends a [TypedCommand] to the display using the [UdpSocket]. /// Sends a [SPCommand] to the display using the [UdpSocket].
/// ///
/// The passed `command` gets consumed. /// The passed `command` gets consumed.
/// ///