add ability to send commands directly in C code, annotate which functions may return null

crates/servicepoint_binding_c/src/bit_vec.rs

@@ -39,7 +39,7 @@ impl Clone for SPBitVec {
 ///
 /// - `size`: size in bits.
 ///
-/// returns: `SPBitVec` with all bits set to false.
+/// returns: `SPBitVec` with all bits set to false. Will never return NULL.
 ///
 /// # Panics
 ///

crates/servicepoint_binding_c/src/brightness_grid.rs

@@ -35,7 +35,7 @@ impl Clone for SPBrightnessGrid {
 
 /// Creates a new `SPBrightnessGrid` with the specified dimensions.
 ///
-/// returns: `SPBrightnessGrid` initialized to 0.
+/// returns: `SPBrightnessGrid` initialized to 0. Will never return NULL.
 ///
 /// # Safety
 ///

crates/servicepoint_binding_c/src/command.rs

@@ -314,6 +314,8 @@ pub unsafe extern "C" fn sp_command_bitmap_linear_xor(
 ///     Because Rust expects UTF-8 strings, it might be necessary to only send ASCII for now.
 /// </div>
 ///
+/// Will never return NULL.
+///
 /// # Safety
 ///
 /// The caller has to make sure that:
@@ -338,7 +340,9 @@ pub unsafe extern "C" fn sp_command_cp437_data(
 /// Allocates a new `Command::BitmapLinearWin` instance.
 /// The passed `SPPixelGrid` gets consumed.
 ///
-/// Sets a window of pixels to the specified values
+/// Sets a window of pixels to the specified values.
+///
+/// Will never return NULL.
 ///
 /// # Safety
 ///

crates/servicepoint_binding_c/src/connection.rs

@@ -5,7 +5,7 @@
 use std::ffi::{c_char, CStr};
 use std::ptr::null_mut;
 
-use crate::SPPacket;
+use crate::{SPCommand, SPPacket};
 
 /// A connection to the display.
 ///
@@ -58,7 +58,7 @@ pub unsafe extern "C" fn sp_connection_open(
 /// - `SPPacket` points to a valid instance of `SPPacket`
 /// - `SPPacket` is not used concurrently or after this call
 #[no_mangle]
-pub unsafe extern "C" fn sp_connection_send(
+pub unsafe extern "C" fn sp_connection_send_packet(
     connection: *const SPConnection,
     packet: *mut SPPacket,
 ) -> bool {
@@ -66,6 +66,27 @@ pub unsafe extern "C" fn sp_connection_send(
     (*connection).0.send((*packet).0).is_ok()
 }
 
+/// Sends a `SPCommand` to the display using the `SPConnection`.
+/// The passed `SPCommand` gets consumed.
+///
+/// returns: true in case of success
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - `connection` points to a valid instance of `SPConnection`
+/// - `command` points to a valid instance of `SPPacket`
+/// - `command` is not used concurrently or after this call
+#[no_mangle]
+pub unsafe extern "C" fn sp_connection_send_command(
+    connection: *const SPConnection,
+    command: *mut SPCommand,
+) -> bool {
+    let command = (*Box::from_raw(command)).0;
+    (*connection).0.send(command).is_ok()
+}
+
 /// Closes and deallocates a `SPConnection`.
 ///
 /// # Safety

crates/servicepoint_binding_c/src/cp437_grid.rs

@@ -51,6 +51,8 @@ pub unsafe extern "C" fn sp_cp437_grid_new(
 
 /// Loads a `SPCp437Grid` with the specified dimensions from the provided data.
 ///
+/// Will never return NULL.
+///
 /// # Panics
 ///
 /// When the provided `data_length` is not sufficient for the `height` and `width`
@@ -78,6 +80,8 @@ pub unsafe extern "C" fn sp_cp437_grid_load(
 
 /// Clones a `SPCp437Grid`.
 ///
+/// Will never return NULL.
+///
 /// # Safety
 ///
 /// The caller has to make sure that:
@@ -219,6 +223,8 @@ pub unsafe extern "C" fn sp_cp437_grid_height(
 
 /// Gets an unsafe reference to the data of the `SPCp437Grid` instance.
 ///
+/// Will never return NULL.
+///
 /// ## Safety
 ///
 /// The caller has to make sure that:

crates/servicepoint_binding_c/src/lib.rs

@@ -17,8 +17,7 @@
 //!     sp_pixel_grid_fill(pixels, true);
 //!
 //!     SPCommand *command = sp_command_bitmap_linear_win(0, 0, pixels, Uncompressed);
-//!     SPPacket *packet = sp_packet_from_command(command);
-//!     while (sp_connection_send(connection, sp_packet_clone(packet)));
+//!     while (sp_connection_send(connection, sp_command_clone(command)));
 //!
 //!     sp_packet_free(packet);
 //!     sp_connection_free(connection);

crates/servicepoint_binding_c/src/packet.rs

@@ -12,6 +12,8 @@ pub struct SPPacket(pub(crate) servicepoint::Packet);
 /// Turns a `SPCommand` into a `SPPacket`.
 /// The `SPCommand` gets consumed.
 ///
+/// Will never return NULL.
+///
 /// # Safety
 ///
 /// The caller has to make sure that:
@@ -55,6 +57,8 @@ pub unsafe extern "C" fn sp_packet_try_load(
 
 /// Clones a `SPPacket`.
 ///
+/// Will never return NULL.
+///
 /// # Safety
 ///
 /// The caller has to make sure that:

crates/servicepoint_binding_c/src/pixel_grid.rs

@@ -25,7 +25,7 @@ pub struct SPPixelGrid(pub(crate) servicepoint::PixelGrid);
 /// - `width`: size in pixels in x-direction
 /// - `height`: size in pixels in y-direction
 ///
-/// returns: `SPPixelGrid` initialized to all pixels off
+/// returns: `SPPixelGrid` initialized to all pixels off. Will never return NULL.
 ///
 /// # Panics
 ///
@@ -54,7 +54,7 @@ pub unsafe extern "C" fn sp_pixel_grid_new(
 /// - `width`: size in pixels in x-direction
 /// - `height`: size in pixels in y-direction
 ///
-/// returns: `SPPixelGrid` that contains a copy of the provided data
+/// returns: `SPPixelGrid` that contains a copy of the provided data. Will never return NULL.
 ///
 /// # Panics
 ///
@@ -83,6 +83,8 @@ pub unsafe extern "C" fn sp_pixel_grid_load(
 
 /// Clones a `SPPixelGrid`.
 ///
+/// Will never return NULL.
+///
 /// # Safety
 ///
 /// The caller has to make sure that: