re-export everything from top-level for nicer docs

crates/servicepoint_binding_c/README.md

@@ -17,18 +17,18 @@ This crate contains C bindings for the `servicepoint` library, enabling users to
 #include "servicepoint.h"
 
 int main(void) {
-    sp_Connection *connection = sp_connection_open("localhost:2342");
+    SPConnection *connection = sp_connection_open("172.23.42.29:2342");
     if (connection == NULL)
         return 1;
 
-    sp_PixelGrid *pixels = sp_pixel_grid_new(sp_PIXEL_WIDTH, sp_PIXEL_HEIGHT);
+    SPPixelGrid *pixels = sp_pixel_grid_new(SP_PIXEL_WIDTH, SP_PIXEL_HEIGHT);
     sp_pixel_grid_fill(pixels, true);
 
-    sp_Command *command = sp_command_bitmap_linear_win(0, 0, pixels, Uncompressed);
-    sp_Packet *packet = sp_packet_from_command(command);
-    if (!sp_connection_send(connection, packet))
-        return 1;
+    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)));
 
+    sp_packet_dealloc(packet);
     sp_connection_dealloc(connection);
     return 0;
 }
@@ -53,7 +53,7 @@ You have the choice of linking statically (recommended) or dynamically.
 ## Notes on differences to rust library
 
 - function names are: `sp_` \<struct_name\> \<rust name\>.
-- Instances get consumed in the same way they do when writing rust / C# code. Do not use an instance after an (implicit!) free.
+- Instances get consumed in the same way they do when writing rust code. Do not use an instance after an (implicit!) free.
 - Option<T> or Result<T, E> turn into nullable return values - check for NULL!
 - There are no specifics for C++ here yet. You might get a nicer header when generating directly for C++, but it should be usable.
 - Reading and writing to instances concurrently is not safe. Only reading concurrently is safe.

crates/servicepoint_binding_c/examples/lang_c/include/servicepoint.h

@@ -167,13 +167,17 @@ typedef struct SPPixelGrid SPPixelGrid;
 /**
  * Represents a span of memory (`&mut [u8]` ) as a struct usable by C code.
  *
+ * You should not create an instance of this type in your C code.
+ *
  * # Safety
  *
  * The caller has to make sure that:
  *
  * - accesses to the memory pointed to with `start` is never accessed outside `length`
  * - the lifetime of the `CByteSlice` does not outlive the memory it points to, as described in
  *   the function returning this type.
+ * - an instance of this created from C is never passed to a consuming function, as the rust code
+ *   will try to free the memory of a potentially separate allocator.
  */
 typedef struct SPByteSlice {
     /**
@@ -186,11 +190,6 @@ typedef struct SPByteSlice {
     size_t length;
 } SPByteSlice;
 
-/**
- * Type alias for documenting the meaning of the variable in enum values
- */
-typedef size_t SPOffset;
-
 #ifdef __cplusplus
 extern "C" {
 #endif // __cplusplus
@@ -556,7 +555,7 @@ size_t sp_brightness_grid_width(const struct SPBrightnessGrid *this_);
  * - the returned `Command` instance is freed in some way, either by using a consuming function or
  *   by explicitly calling `sp_command_dealloc`.
  */
-struct SPCommand *sp_command_bitmap_linear(SPOffset offset,
+struct SPCommand *sp_command_bitmap_linear(size_t offset,
                                            struct SPBitVec *bit_vec,
                                            SPCompressionCode compression);
 
@@ -581,7 +580,7 @@ struct SPCommand *sp_command_bitmap_linear(SPOffset offset,
  * - the returned `Command` instance is freed in some way, either by using a consuming function or
  *   by explicitly calling `sp_command_dealloc`.
  */
-struct SPCommand *sp_command_bitmap_linear_and(SPOffset offset,
+struct SPCommand *sp_command_bitmap_linear_and(size_t offset,
                                                struct SPBitVec *bit_vec,
                                                SPCompressionCode compression);
 
@@ -606,7 +605,7 @@ struct SPCommand *sp_command_bitmap_linear_and(SPOffset offset,
  * - the returned `Command` instance is freed in some way, either by using a consuming function or
  *   by explicitly calling `sp_command_dealloc`.
  */
-struct SPCommand *sp_command_bitmap_linear_or(SPOffset offset,
+struct SPCommand *sp_command_bitmap_linear_or(size_t offset,
                                               struct SPBitVec *bit_vec,
                                               SPCompressionCode compression);
 
@@ -652,7 +651,7 @@ struct SPCommand *sp_command_bitmap_linear_win(size_t x,
  * - the returned `Command` instance is freed in some way, either by using a consuming function or
  *   by explicitly calling `sp_command_dealloc`.
  */
-struct SPCommand *sp_command_bitmap_linear_xor(SPOffset offset,
+struct SPCommand *sp_command_bitmap_linear_xor(size_t offset,
                                                struct SPBitVec *bit_vec,
                                                SPCompressionCode compression);
 

crates/servicepoint_binding_c/src/bit_vec.rs

@@ -2,7 +2,7 @@
 //!
 //! prefix `sp_bit_vec_`
 
-use crate::c_slice::SPByteSlice;
+use crate::SPByteSlice;
 use servicepoint::bitvec::prelude::{BitVec, Msb0};
 
 /// A vector of bits

crates/servicepoint_binding_c/src/brightness_grid.rs

@@ -2,7 +2,7 @@
 //!
 //! prefix `sp_brightness_grid_`
 
-use crate::c_slice::SPByteSlice;
+use crate::SPByteSlice;
 use servicepoint::{Brightness, DataRef, Grid, PrimitiveGrid};
 use std::intrinsics::transmute;
 

crates/servicepoint_binding_c/src/c_slice.rs → crates/servicepoint_binding_c/src/byte_slice.rs

@@ -3,13 +3,17 @@
 #[repr(C)]
 /// Represents a span of memory (`&mut [u8]` ) as a struct usable by C code.
 ///
+/// You should not create an instance of this type in your C code.
+///
 /// # Safety
 ///
 /// The caller has to make sure that:
 ///
 /// - accesses to the memory pointed to with `start` is never accessed outside `length`
 /// - the lifetime of the `CByteSlice` does not outlive the memory it points to, as described in
 ///   the function returning this type.
+/// - an instance of this created from C is never passed to a consuming function, as the rust code
+///   will try to free the memory of a potentially separate allocator.
 pub struct SPByteSlice {
     /// The start address of the memory
     pub start: *mut u8,

crates/servicepoint_binding_c/src/command.rs

@@ -6,13 +6,10 @@ use std::ptr::null_mut;
 
 use servicepoint::{Brightness, Origin};
 
-use crate::bit_vec::SPBitVec;
-use crate::brightness_grid::SPBrightnessGrid;
-use crate::constants::SPCompressionCode;
-use crate::cp437_grid::SPCp437Grid;
-use crate::packet::SPPacket;
-use crate::pixel_grid::SPPixelGrid;
-use crate::SPOffset;
+use crate::{
+    SPBitVec, SPBrightnessGrid, SPCompressionCode, SPCp437Grid, SPPacket,
+    SPPixelGrid,
+};
 
 /// A low-level display command.
 ///
@@ -196,7 +193,7 @@ pub unsafe extern "C" fn sp_command_char_brightness(
 ///   by explicitly calling `sp_command_dealloc`.
 #[no_mangle]
 pub unsafe extern "C" fn sp_command_bitmap_linear(
-    offset: SPOffset,
+    offset: usize,
     bit_vec: *mut SPBitVec,
     compression: SPCompressionCode,
 ) -> *mut SPCommand {
@@ -229,7 +226,7 @@ pub unsafe extern "C" fn sp_command_bitmap_linear(
 ///   by explicitly calling `sp_command_dealloc`.
 #[no_mangle]
 pub unsafe extern "C" fn sp_command_bitmap_linear_and(
-    offset: SPOffset,
+    offset: usize,
     bit_vec: *mut SPBitVec,
     compression: SPCompressionCode,
 ) -> *mut SPCommand {
@@ -262,7 +259,7 @@ pub unsafe extern "C" fn sp_command_bitmap_linear_and(
 ///   by explicitly calling `sp_command_dealloc`.
 #[no_mangle]
 pub unsafe extern "C" fn sp_command_bitmap_linear_or(
-    offset: SPOffset,
+    offset: usize,
     bit_vec: *mut SPBitVec,
     compression: SPCompressionCode,
 ) -> *mut SPCommand {
@@ -295,7 +292,7 @@ pub unsafe extern "C" fn sp_command_bitmap_linear_or(
 ///   by explicitly calling `sp_command_dealloc`.
 #[no_mangle]
 pub unsafe extern "C" fn sp_command_bitmap_linear_xor(
-    offset: SPOffset,
+    offset: usize,
     bit_vec: *mut SPBitVec,
     compression: SPCompressionCode,
 ) -> *mut SPCommand {

crates/servicepoint_binding_c/src/connection.rs

@@ -5,7 +5,7 @@
 use std::ffi::{c_char, CStr};
 use std::ptr::null_mut;
 
-use crate::packet::SPPacket;
+use crate::SPPacket;
 
 /// A connection to the display.
 ///

crates/servicepoint_binding_c/src/cp437_grid.rs

@@ -2,8 +2,8 @@
 //!
 //! prefix `sp_cp437_grid_`
 
-use crate::c_slice::SPByteSlice;
-use servicepoint::{Cp437Grid, DataRef, Grid};
+use crate::SPByteSlice;
+use servicepoint::{DataRef, Grid};
 
 /// A C-wrapper for grid containing codepage 437 characters.
 ///
@@ -18,7 +18,7 @@ use servicepoint::{Cp437Grid, DataRef, Grid};
 /// sp_cp437_grid_dealloc(grid);
 /// ```
 pub struct SPCp437Grid {
-    pub(crate) actual: Cp437Grid,
+    pub(crate) actual: servicepoint::Cp437Grid,
 }
 
 impl Clone for SPCp437Grid {
@@ -45,7 +45,7 @@ pub unsafe extern "C" fn sp_cp437_grid_new(
     height: usize,
 ) -> *mut SPCp437Grid {
     Box::into_raw(Box::new(SPCp437Grid {
-        actual: Cp437Grid::new(width, height),
+        actual: servicepoint::Cp437Grid::new(width, height),
     }))
 }
 
@@ -72,7 +72,7 @@ pub unsafe extern "C" fn sp_cp437_grid_load(
 ) -> *mut SPCp437Grid {
     let data = std::slice::from_raw_parts(data, data_length);
     Box::into_raw(Box::new(SPCp437Grid {
-        actual: Cp437Grid::load(width, height, data),
+        actual: servicepoint::Cp437Grid::load(width, height, data),
     }))
 }
 

crates/servicepoint_binding_c/src/lib.rs

@@ -1,24 +1,55 @@
-//! C API wrapper for the `servicepoint` crate.
-
-pub use crate::c_slice::SPByteSlice;
-
-pub mod bit_vec;
-
-pub mod brightness_grid;
-
-pub mod command;
-
-pub mod connection;
-
-pub mod packet;
-
-pub mod pixel_grid;
-
-pub mod c_slice;
-
-pub mod cp437_grid;
-
-pub mod constants;
-
-/// Type alias for documenting the meaning of the variable in enum values
-pub type SPOffset = usize;
+//! C API wrapper for the [servicepoint](https://docs.rs/servicepoint/latest/servicepoint/) crate.
+//!
+//! # Examples
+//!
+//! Make sure to check out [this GitHub repo](https://github.com/arfst23/ServicePoint) as well!
+//!
+//! ```C
+//! #include <stdio.h>
+//! #include "servicepoint.h"
+//!
+//! int main(void) {
+//!     SPConnection *connection = sp_connection_open("172.23.42.29:2342");
+//!     if (connection == NULL)
+//!         return 1;
+//!
+//!     SPPixelGrid *pixels = sp_pixel_grid_new(SP_PIXEL_WIDTH, SP_PIXEL_HEIGHT);
+//!     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)));
+//!
+//!     sp_packet_dealloc(packet);
+//!     sp_connection_dealloc(connection);
+//!     return 0;
+//! }
+//! ```
+
+pub use bit_vec::*;
+pub use brightness_grid::*;
+pub use byte_slice::*;
+pub use command::*;
+pub use connection::*;
+pub use constants::*;
+pub use cp437_grid::*;
+pub use packet::*;
+pub use pixel_grid::*;
+
+mod bit_vec;
+
+mod brightness_grid;
+
+mod command;
+
+mod connection;
+
+mod packet;
+
+mod pixel_grid;
+
+mod byte_slice;
+
+mod cp437_grid;
+
+mod constants;

crates/servicepoint_binding_c/src/packet.rs

@@ -4,7 +4,7 @@
 
 use std::ptr::null_mut;
 
-use crate::command::SPCommand;
+use crate::SPCommand;
 
 /// The raw packet
 pub struct SPPacket(pub(crate) servicepoint::Packet);

crates/servicepoint_binding_c/src/pixel_grid.rs

@@ -4,7 +4,7 @@
 
 use servicepoint::{DataRef, Grid};
 
-use crate::c_slice::SPByteSlice;
+use crate::byte_slice::SPByteSlice;
 
 /// A grid of pixels.
 ///

crates/servicepoint_binding_cs/build.rs

@@ -11,7 +11,7 @@ fn main() {
         .input_extern_file("../servicepoint_binding_c/src/connection.rs")
         .input_extern_file("../servicepoint_binding_c/src/pixel_grid.rs")
         .input_extern_file("../servicepoint_binding_c/src/lib.rs")
-        .input_extern_file("../servicepoint_binding_c/src/c_slice.rs")
+        .input_extern_file("../servicepoint_binding_c/src/byte_slice.rs")
         .input_extern_file("../servicepoint_binding_c/src/packet.rs")
         .input_extern_file("../servicepoint_binding_c/src/constants.rs")
         .csharp_dll_name("servicepoint_binding_c")