mirror of
https://github.com/cccb/servicepoint.git
synced 2025-01-18 10:00:14 +01:00
add NULL checks - command
This commit is contained in:
Vinzenz Schroeter
parent
bcb73999da
commit
2e1cb6f681
|
|
@ -4,7 +4,7 @@
|
|||
|
||||
use std::ptr::null_mut;
|
||||
|
||||
use servicepoint::{Brightness, Origin};
|
||||
use servicepoint::{Brightness, Command, Origin};
|
||||
|
||||
use crate::{
|
||||
SPBitVec, SPBrightnessGrid, SPCompressionCode, SPCp437Grid, SPPacket,
|
||||
|
|
@ -15,7 +15,7 @@ use crate::{
|
|||
///
|
||||
/// This struct and associated functions implement the UDP protocol for the display.
|
||||
///
|
||||
/// To send a [SPCommand], use a `SPConnection`.
|
||||
/// To send a [SPCommand], use a [SPConnection].
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
|
|
@ -31,18 +31,22 @@ impl Clone for SPCommand {
|
|||
}
|
||||
}
|
||||
|
||||
/// Tries to turn a `SPPacket` into a [SPCommand].
|
||||
/// Tries to turn a [SPPacket] into a [SPCommand].
|
||||
///
|
||||
/// The packet is deallocated in the process.
|
||||
///
|
||||
/// Returns: pointer to new [SPCommand] instance or NULL
|
||||
/// Returns: pointer to new [SPCommand] instance or NULL if parsing failed.
|
||||
///
|
||||
/// # Panics
|
||||
///
|
||||
/// - when `packet` is NULL
|
||||
///
|
||||
/// # Safety
|
||||
///
|
||||
/// The caller has to make sure that:
|
||||
///
|
||||
/// - `SPPacket` points to a valid instance of `SPPacket`
|
||||
/// - `SPPacket` is not used concurrently or after this call
|
||||
/// - [SPPacket] points to a valid instance of [SPPacket]
|
||||
/// - [SPPacket] is not used concurrently or after this call
|
||||
/// - the result is checked for NULL
|
||||
/// - the returned [SPCommand] instance is freed in some way, either by using a consuming function or
|
||||
/// by explicitly calling `sp_command_free`.
|
||||
|
|
@ -59,6 +63,12 @@ pub unsafe extern "C" fn sp_command_try_from_packet(
|
|||
|
||||
/// Clones a [SPCommand] instance.
|
||||
///
|
||||
/// returns: new [SPCommand] instance. Will never return NULL.
|
||||
///
|
||||
/// # Panics
|
||||
///
|
||||
/// - when `command` is NULL
|
||||
///
|
||||
/// # Safety
|
||||
///
|
||||
/// The caller has to make sure that:
|
||||
|
|
@ -71,14 +81,17 @@ pub unsafe extern "C" fn sp_command_try_from_packet(
|
|||
pub unsafe extern "C" fn sp_command_clone(
|
||||
command: *const SPCommand,
|
||||
) -> *mut SPCommand {
|
||||
Box::into_raw(Box::new((*command).clone()))
|
||||
assert!(!command.is_null());
|
||||
let result = Box::into_raw(Box::new((*command).clone()));
|
||||
assert!(!result.is_null());
|
||||
result
|
||||
}
|
||||
|
||||
/// Set all pixels to the off state.
|
||||
///
|
||||
/// Does not affect brightness.
|
||||
///
|
||||
/// Returns: a new `Command::Clear` instance. Will never return NULL.
|
||||
/// Returns: a new [Command::Clear] instance. Will never return NULL.
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
|
|
@ -94,14 +107,16 @@ pub unsafe extern "C" fn sp_command_clone(
|
|||
/// by explicitly calling `sp_command_free`.
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn sp_command_clear() -> *mut SPCommand {
|
||||
Box::into_raw(Box::new(SPCommand(servicepoint::Command::Clear)))
|
||||
let result = Box::into_raw(Box::new(SPCommand(servicepoint::Command::Clear)));
|
||||
assert!(!result.is_null());
|
||||
result
|
||||
}
|
||||
|
||||
/// Kills the udp daemon on the display, which usually results in a restart.
|
||||
///
|
||||
/// Please do not send this in your normal program flow.
|
||||
///
|
||||
/// Returns: a new `Command::HardReset` instance. Will never return NULL.
|
||||
/// Returns: a new [Command::HardReset] instance. Will never return NULL.
|
||||
///
|
||||
/// # Safety
|
||||
///
|
||||
|
|
@ -111,7 +126,9 @@ pub unsafe extern "C" fn sp_command_clear() -> *mut SPCommand {
|
|||
/// by explicitly calling `sp_command_free`.
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn sp_command_hard_reset() -> *mut SPCommand {
|
||||
Box::into_raw(Box::new(SPCommand(servicepoint::Command::HardReset)))
|
||||
let result = Box::into_raw(Box::new(SPCommand(servicepoint::Command::HardReset)));
|
||||
assert!(!result.is_null());
|
||||
result
|
||||
}
|
||||
|
||||
/// A yet-to-be-tested command.
|
||||
|
|
@ -126,12 +143,14 @@ pub unsafe extern "C" fn sp_command_hard_reset() -> *mut SPCommand {
|
|||
/// by explicitly calling `sp_command_free`.
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn sp_command_fade_out() -> *mut SPCommand {
|
||||
Box::into_raw(Box::new(SPCommand(servicepoint::Command::FadeOut)))
|
||||
let result = Box::into_raw(Box::new(SPCommand(servicepoint::Command::FadeOut)));
|
||||
assert!(!result.is_null());
|
||||
result
|
||||
}
|
||||
|
||||
/// Set the brightness of all tiles to the same value.
|
||||
///
|
||||
/// Returns: a new `Command::Brightness` instance. Will never return NULL.
|
||||
/// Returns: a new [Command::Brightness] instance. Will never return NULL.
|
||||
///
|
||||
/// # Panics
|
||||
///
|
||||
|
|
@ -149,16 +168,22 @@ pub unsafe extern "C" fn sp_command_brightness(
|
|||
) -> *mut SPCommand {
|
||||
let brightness =
|
||||
Brightness::try_from(brightness).expect("invalid brightness");
|
||||
Box::into_raw(Box::new(SPCommand(servicepoint::Command::Brightness(
|
||||
let result = Box::into_raw(Box::new(SPCommand(servicepoint::Command::Brightness(
|
||||
brightness,
|
||||
))))
|
||||
))));
|
||||
assert!(!result.is_null());
|
||||
result
|
||||
}
|
||||
|
||||
/// Set the brightness of individual tiles in a rectangular area of the display.
|
||||
///
|
||||
/// The passed [SPBrightnessGrid] gets consumed.
|
||||
///
|
||||
/// Returns: a new `Command::CharBrightness` instance. Will never return NULL.
|
||||
/// Returns: a new [Command::CharBrightness] instance. Will never return NULL.
|
||||
///
|
||||
/// # Panics
|
||||
///
|
||||
/// - when `grid` is NULL
|
||||
///
|
||||
/// # Safety
|
||||
///
|
||||
|
|
@ -174,11 +199,14 @@ pub unsafe extern "C" fn sp_command_char_brightness(
|
|||
y: usize,
|
||||
grid: *mut SPBrightnessGrid,
|
||||
) -> *mut SPCommand {
|
||||
assert!(!grid.is_null());
|
||||
let byte_grid = *Box::from_raw(grid);
|
||||
Box::into_raw(Box::new(SPCommand(servicepoint::Command::CharBrightness(
|
||||
let result = Box::into_raw(Box::new(SPCommand(servicepoint::Command::CharBrightness(
|
||||
Origin::new(x, y),
|
||||
byte_grid.0,
|
||||
))))
|
||||
))));
|
||||
assert!(!result.is_null());
|
||||
result
|
||||
}
|
||||
|
||||
/// Set pixel data starting at the pixel offset on screen.
|
||||
|
|
@ -190,7 +218,12 @@ pub unsafe extern "C" fn sp_command_char_brightness(
|
|||
///
|
||||
/// The passed [SPBitVec] gets consumed.
|
||||
///
|
||||
/// Returns: a new `Command::BitmapLinear` instance. Will never return NULL.
|
||||
/// Returns: a new [Command::BitmapLinear] instance. Will never return NULL.
|
||||
///
|
||||
/// # Panics
|
||||
///
|
||||
/// - when `bit_vec` is null
|
||||
/// - when `compression_code` is not a valid value
|
||||
///
|
||||
/// # Safety
|
||||
///
|
||||
|
|
@ -207,12 +240,15 @@ pub unsafe extern "C" fn sp_command_bitmap_linear(
|
|||
bit_vec: *mut SPBitVec,
|
||||
compression: SPCompressionCode,
|
||||
) -> *mut SPCommand {
|
||||
assert!(!bit_vec.is_null());
|
||||
let bit_vec = *Box::from_raw(bit_vec);
|
||||
Box::into_raw(Box::new(SPCommand(servicepoint::Command::BitmapLinear(
|
||||
let result = Box::into_raw(Box::new(SPCommand(servicepoint::Command::BitmapLinear(
|
||||
offset,
|
||||
bit_vec.into(),
|
||||
compression.try_into().expect("invalid compression code"),
|
||||
))))
|
||||
))));
|
||||
assert!(!result.is_null());
|
||||
result
|
||||
}
|
||||
|
||||
/// Set pixel data according to an and-mask starting at the offset.
|
||||
|
|
@ -224,7 +260,12 @@ pub unsafe extern "C" fn sp_command_bitmap_linear(
|
|||
///
|
||||
/// The passed [SPBitVec] gets consumed.
|
||||
///
|
||||
/// Returns: a new `Command::BitmapLinearAnd` instance. Will never return NULL.
|
||||
/// Returns: a new [Command::BitmapLinearAnd] instance. Will never return NULL.
|
||||
///
|
||||
/// # Panics
|
||||
///
|
||||
/// - when `bit_vec` is null
|
||||
/// - when `compression_code` is not a valid value
|
||||
///
|
||||
/// # Safety
|
||||
///
|
||||
|
|
@ -241,12 +282,15 @@ pub unsafe extern "C" fn sp_command_bitmap_linear_and(
|
|||
bit_vec: *mut SPBitVec,
|
||||
compression: SPCompressionCode,
|
||||
) -> *mut SPCommand {
|
||||
assert!(!bit_vec.is_null());
|
||||
let bit_vec = *Box::from_raw(bit_vec);
|
||||
Box::into_raw(Box::new(SPCommand(servicepoint::Command::BitmapLinearAnd(
|
||||
let result = Box::into_raw(Box::new(SPCommand(servicepoint::Command::BitmapLinearAnd(
|
||||
offset,
|
||||
bit_vec.into(),
|
||||
compression.try_into().expect("invalid compression code"),
|
||||
))))
|
||||
))));
|
||||
assert!(!result.is_null());
|
||||
result
|
||||
}
|
||||
|
||||
/// Set pixel data according to an or-mask starting at the offset.
|
||||
|
|
@ -258,7 +302,12 @@ pub unsafe extern "C" fn sp_command_bitmap_linear_and(
|
|||
///
|
||||
/// The passed [SPBitVec] gets consumed.
|
||||
///
|
||||
/// Returns: a new `Command::BitmapLinearOr` instance. Will never return NULL.
|
||||
/// Returns: a new [Command::BitmapLinearOr] instance. Will never return NULL.
|
||||
///
|
||||
/// # Panics
|
||||
///
|
||||
/// - when `bit_vec` is null
|
||||
/// - when `compression_code` is not a valid value
|
||||
///
|
||||
/// # Safety
|
||||
///
|
||||
|
|
@ -275,12 +324,15 @@ pub unsafe extern "C" fn sp_command_bitmap_linear_or(
|
|||
bit_vec: *mut SPBitVec,
|
||||
compression: SPCompressionCode,
|
||||
) -> *mut SPCommand {
|
||||
assert!(!bit_vec.is_null());
|
||||
let bit_vec = *Box::from_raw(bit_vec);
|
||||
Box::into_raw(Box::new(SPCommand(servicepoint::Command::BitmapLinearOr(
|
||||
let result = Box::into_raw(Box::new(SPCommand(servicepoint::Command::BitmapLinearOr(
|
||||
offset,
|
||||
bit_vec.into(),
|
||||
compression.try_into().expect("invalid compression code"),
|
||||
))))
|
||||
))));
|
||||
assert!(!result.is_null());
|
||||
result
|
||||
}
|
||||
|
||||
/// Set pixel data according to a xor-mask starting at the offset.
|
||||
|
|
@ -292,7 +344,12 @@ pub unsafe extern "C" fn sp_command_bitmap_linear_or(
|
|||
///
|
||||
/// The passed [SPBitVec] gets consumed.
|
||||
///
|
||||
/// Returns: a new `Command::BitmapLinearXor` instance. Will never return NULL.
|
||||
/// Returns: a new [Command::BitmapLinearXor] instance. Will never return NULL.
|
||||
///
|
||||
/// # Panics
|
||||
///
|
||||
/// - when `bit_vec` is null
|
||||
/// - when `compression_code` is not a valid value
|
||||
///
|
||||
/// # Safety
|
||||
///
|
||||
|
|
@ -309,30 +366,32 @@ pub unsafe extern "C" fn sp_command_bitmap_linear_xor(
|
|||
bit_vec: *mut SPBitVec,
|
||||
compression: SPCompressionCode,
|
||||
) -> *mut SPCommand {
|
||||
assert!(!bit_vec.is_null());
|
||||
let bit_vec = *Box::from_raw(bit_vec);
|
||||
Box::into_raw(Box::new(SPCommand(servicepoint::Command::BitmapLinearXor(
|
||||
let result = Box::into_raw(Box::new(SPCommand(servicepoint::Command::BitmapLinearXor(
|
||||
offset,
|
||||
bit_vec.into(),
|
||||
compression.try_into().expect("invalid compression code"),
|
||||
))))
|
||||
))));
|
||||
assert!(!result.is_null());
|
||||
result
|
||||
}
|
||||
|
||||
/// Show text on the screen.
|
||||
///
|
||||
/// <div class="warning">
|
||||
/// The library does not currently convert between UTF-8 and CP-437.
|
||||
/// Because Rust expects UTF-8 strings, it might be necessary to only send ASCII for now.
|
||||
/// </div>
|
||||
/// The passed [SPCp437Grid] gets consumed.
|
||||
///
|
||||
/// The passed `SPCp437Grid` gets consumed.///
|
||||
/// Returns: a new [Command::Cp437Data] instance. Will never return NULL.
|
||||
///
|
||||
/// Returns: a new `Command::Cp437Data` instance. Will never return NULL.
|
||||
/// # Panics
|
||||
///
|
||||
/// - when `grid` is null
|
||||
///
|
||||
/// # Safety
|
||||
///
|
||||
/// The caller has to make sure that:
|
||||
///
|
||||
/// - `grid` points to a valid instance of `SPCp437Grid`
|
||||
/// - `grid` points to a valid instance of [SPCp437Grid]
|
||||
/// - `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
|
||||
/// by explicitly calling `sp_command_free`.
|
||||
|
|
@ -342,24 +401,32 @@ pub unsafe extern "C" fn sp_command_cp437_data(
|
|||
y: usize,
|
||||
grid: *mut SPCp437Grid,
|
||||
) -> *mut SPCommand {
|
||||
assert!(!grid.is_null());
|
||||
let grid = *Box::from_raw(grid);
|
||||
Box::into_raw(Box::new(SPCommand(servicepoint::Command::Cp437Data(
|
||||
let result = Box::into_raw(Box::new(SPCommand(servicepoint::Command::Cp437Data(
|
||||
Origin::new(x, y),
|
||||
grid.0,
|
||||
))))
|
||||
))));
|
||||
assert!(!result.is_null());
|
||||
result
|
||||
}
|
||||
|
||||
/// Sets a window of pixels to the specified values.
|
||||
///
|
||||
/// The passed `SPPixelGrid` gets consumed.
|
||||
/// The passed [SPPixelGrid] gets consumed.
|
||||
///
|
||||
/// Returns: a new `Command::BitmapLinearWin` instance. Will never return NULL.
|
||||
/// Returns: a new [Command::BitmapLinearWin] instance. Will never return NULL.
|
||||
///
|
||||
/// # Panics
|
||||
///
|
||||
/// - when `pixel_grid` is null
|
||||
/// - when `compression_code` is not a valid value
|
||||
///
|
||||
/// # Safety
|
||||
///
|
||||
/// The caller has to make sure that:
|
||||
///
|
||||
/// - `pixel_grid` points to a valid instance of `SPPixelGrid`
|
||||
/// - `pixel_grid` points to a valid instance of [SPPixelGrid]
|
||||
/// - `pixel_grid` is not used concurrently or after this call
|
||||
/// - `compression` matches one of the allowed enum values
|
||||
/// - the returned [SPCommand] instance is freed in some way, either by using a consuming function or
|
||||
|
|
@ -371,14 +438,17 @@ pub unsafe extern "C" fn sp_command_bitmap_linear_win(
|
|||
pixel_grid: *mut SPPixelGrid,
|
||||
compression_code: SPCompressionCode,
|
||||
) -> *mut SPCommand {
|
||||
assert!(!pixel_grid.is_null());
|
||||
let byte_grid = (*Box::from_raw(pixel_grid)).0;
|
||||
Box::into_raw(Box::new(SPCommand(servicepoint::Command::BitmapLinearWin(
|
||||
let result = Box::into_raw(Box::new(SPCommand(servicepoint::Command::BitmapLinearWin(
|
||||
Origin::new(x, y),
|
||||
byte_grid,
|
||||
compression_code
|
||||
.try_into()
|
||||
.expect("invalid compression code"),
|
||||
))))
|
||||
))));
|
||||
assert!(!result.is_null());
|
||||
result
|
||||
}
|
||||
|
||||
/// Deallocates a [SPCommand].
|
||||
|
|
@ -390,14 +460,19 @@ pub unsafe extern "C" fn sp_command_bitmap_linear_win(
|
|||
/// sp_command_free(c);
|
||||
/// ```
|
||||
///
|
||||
/// # Panics
|
||||
///
|
||||
/// - when `command` is NULL
|
||||
///
|
||||
/// # Safety
|
||||
///
|
||||
/// The caller has to make sure that:
|
||||
///
|
||||
/// - `command` points to a valid [SPCommand]
|
||||
/// - `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 [SPPacket]
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn sp_command_free(command: *mut SPCommand) {
|
||||
assert!(!command.is_null());
|
||||
_ = Box::from_raw(command);
|
||||
}
|
||||
|
|
|
|||
|
|
@ -18,7 +18,7 @@ use crate::{SPCommand, SPPacket};
|
|||
/// ```
|
||||
pub struct SPConnection(pub(crate) servicepoint::Connection);
|
||||
|
||||
/// Creates a new instance of `SPConnection`.
|
||||
/// Creates a new instance of [SPConnection].
|
||||
///
|
||||
/// returns: NULL if connection fails, or connected instance
|
||||
///
|
||||
|
|
@ -45,7 +45,7 @@ pub unsafe extern "C" fn sp_connection_open(
|
|||
Box::into_raw(Box::new(SPConnection(connection)))
|
||||
}
|
||||
|
||||
/// Sends a `SPPacket` to the display using the `SPConnection`.
|
||||
/// Sends a [SPPacket] to the display using the [SPConnection].
|
||||
///
|
||||
/// The passed `packet` gets consumed.
|
||||
///
|
||||
|
|
@ -55,8 +55,8 @@ pub unsafe extern "C" fn sp_connection_open(
|
|||
///
|
||||
/// The caller has to make sure that:
|
||||
///
|
||||
/// - `connection` points to a valid instance of `SPConnection`
|
||||
/// - `packet` points to a valid instance of `SPPacket`
|
||||
/// - `connection` points to a valid instance of [SPConnection]
|
||||
/// - `packet` points to a valid instance of [SPPacket]
|
||||
/// - `packet` is not used concurrently or after this call
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn sp_connection_send_packet(
|
||||
|
|
@ -77,8 +77,8 @@ pub unsafe extern "C" fn sp_connection_send_packet(
|
|||
///
|
||||
/// The caller has to make sure that:
|
||||
///
|
||||
/// - `connection` points to a valid instance of `SPConnection`
|
||||
/// - `command` points to a valid instance of `SPPacket`
|
||||
/// - `connection` points to a valid instance of [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(
|
||||
|
|
@ -89,13 +89,19 @@ pub unsafe extern "C" fn sp_connection_send_command(
|
|||
(*connection).0.send(command).is_ok()
|
||||
}
|
||||
|
||||
/// Closes and deallocates a `SPConnection`.
|
||||
/// Closes and deallocates a [SPConnection].
|
||||
///
|
||||
/// # Panics
|
||||
///
|
||||
/// # Panics
|
||||
///
|
||||
/// - when `connection` is NULL
|
||||
///
|
||||
/// # Safety
|
||||
///
|
||||
/// The caller has to make sure that:
|
||||
///
|
||||
/// - `connection` points to a valid `SPConnection`
|
||||
/// - `connection` points to a valid [SPConnection]
|
||||
/// - `connection` is not used concurrently or after this call
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn sp_connection_free(connection: *mut SPConnection) {
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
//! C functions for interacting with `SPCp437Grid`s
|
||||
//! C functions for interacting with [SPCp437Grid]s
|
||||
//!
|
||||
//! prefix `sp_cp437_grid_`
|
||||
|
||||
|
|
@ -25,9 +25,9 @@ impl Clone for SPCp437Grid {
|
|||
}
|
||||
}
|
||||
|
||||
/// Creates a new `SPCp437Grid` with the specified dimensions.
|
||||
/// Creates a new [SPCp437Grid] with the specified dimensions.
|
||||
///
|
||||
/// returns: `SPCp437Grid` initialized to 0.
|
||||
/// returns: [SPCp437Grid] initialized to 0.
|
||||
///
|
||||
/// # Safety
|
||||
///
|
||||
|
|
@ -45,7 +45,7 @@ pub unsafe extern "C" fn sp_cp437_grid_new(
|
|||
))))
|
||||
}
|
||||
|
||||
/// Loads a `SPCp437Grid` with the specified dimensions from the provided data.
|
||||
/// Loads a [SPCp437Grid] with the specified dimensions from the provided data.
|
||||
///
|
||||
/// Will never return NULL.
|
||||
///
|
||||
|
|
@ -74,7 +74,7 @@ pub unsafe extern "C" fn sp_cp437_grid_load(
|
|||
))))
|
||||
}
|
||||
|
||||
/// Clones a `SPCp437Grid`.
|
||||
/// Clones a [SPCp437Grid].
|
||||
///
|
||||
/// Will never return NULL.
|
||||
///
|
||||
|
|
@ -82,7 +82,7 @@ pub unsafe extern "C" fn sp_cp437_grid_load(
|
|||
///
|
||||
/// The caller has to make sure that:
|
||||
///
|
||||
/// - `cp437_grid` points to a valid `SPCp437Grid`
|
||||
/// - `cp437_grid` points to a valid [SPCp437Grid]
|
||||
/// - `cp437_grid` is not written to concurrently
|
||||
/// - the returned instance is freed in some way, either by using a consuming function or
|
||||
/// by explicitly calling `sp_cp437_grid_free`.
|
||||
|
|
@ -93,13 +93,13 @@ pub unsafe extern "C" fn sp_cp437_grid_clone(
|
|||
Box::into_raw(Box::new((*cp437_grid).clone()))
|
||||
}
|
||||
|
||||
/// Deallocates a `SPCp437Grid`.
|
||||
/// Deallocates a [SPCp437Grid].
|
||||
///
|
||||
/// # Safety
|
||||
///
|
||||
/// The caller has to make sure that:
|
||||
///
|
||||
/// - `cp437_grid` points to a valid `SPCp437Grid`
|
||||
/// - `cp437_grid` points to a valid [SPCp437Grid]
|
||||
/// - `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]
|
||||
#[no_mangle]
|
||||
|
|
@ -122,7 +122,7 @@ pub unsafe extern "C" fn sp_cp437_grid_free(cp437_grid: *mut SPCp437Grid) {
|
|||
///
|
||||
/// The caller has to make sure that:
|
||||
///
|
||||
/// - `cp437_grid` points to a valid `SPCp437Grid`
|
||||
/// - `cp437_grid` points to a valid [SPCp437Grid]
|
||||
/// - `cp437_grid` is not written to concurrently
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn sp_cp437_grid_get(
|
||||
|
|
@ -133,7 +133,7 @@ pub unsafe extern "C" fn sp_cp437_grid_get(
|
|||
(*cp437_grid).0.get(x, y)
|
||||
}
|
||||
|
||||
/// Sets the value of the specified position in the `SPCp437Grid`.
|
||||
/// Sets the value of the specified position in the [SPCp437Grid].
|
||||
///
|
||||
/// # Arguments
|
||||
///
|
||||
|
|
@ -163,7 +163,7 @@ pub unsafe extern "C" fn sp_cp437_grid_set(
|
|||
(*cp437_grid).0.set(x, y, value);
|
||||
}
|
||||
|
||||
/// Sets the value of all cells in the `SPCp437Grid`.
|
||||
/// Sets the value of all cells in the [SPCp437Grid].
|
||||
///
|
||||
/// # Arguments
|
||||
///
|
||||
|
|
@ -174,7 +174,7 @@ pub unsafe extern "C" fn sp_cp437_grid_set(
|
|||
///
|
||||
/// The caller has to make sure that:
|
||||
///
|
||||
/// - `cp437_grid` points to a valid `SPCp437Grid`
|
||||
/// - `cp437_grid` points to a valid [SPCp437Grid]
|
||||
/// - `cp437_grid` is not written to or read from concurrently
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn sp_cp437_grid_fill(
|
||||
|
|
@ -184,7 +184,7 @@ pub unsafe extern "C" fn sp_cp437_grid_fill(
|
|||
(*cp437_grid).0.fill(value);
|
||||
}
|
||||
|
||||
/// Gets the width of the `SPCp437Grid` instance.
|
||||
/// Gets the width of the [SPCp437Grid] instance.
|
||||
///
|
||||
/// # Arguments
|
||||
///
|
||||
|
|
@ -194,7 +194,7 @@ pub unsafe extern "C" fn sp_cp437_grid_fill(
|
|||
///
|
||||
/// The caller has to make sure that:
|
||||
///
|
||||
/// - `cp437_grid` points to a valid `SPCp437Grid`
|
||||
/// - `cp437_grid` points to a valid [SPCp437Grid]
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn sp_cp437_grid_width(
|
||||
cp437_grid: *const SPCp437Grid,
|
||||
|
|
@ -202,7 +202,7 @@ pub unsafe extern "C" fn sp_cp437_grid_width(
|
|||
(*cp437_grid).0.width()
|
||||
}
|
||||
|
||||
/// Gets the height of the `SPCp437Grid` instance.
|
||||
/// Gets the height of the [SPCp437Grid] instance.
|
||||
///
|
||||
/// # Arguments
|
||||
///
|
||||
|
|
@ -212,7 +212,7 @@ pub unsafe extern "C" fn sp_cp437_grid_width(
|
|||
///
|
||||
/// The caller has to make sure that:
|
||||
///
|
||||
/// - `cp437_grid` points to a valid `SPCp437Grid`
|
||||
/// - `cp437_grid` points to a valid [SPCp437Grid]
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn sp_cp437_grid_height(
|
||||
cp437_grid: *const SPCp437Grid,
|
||||
|
|
@ -220,7 +220,7 @@ pub unsafe extern "C" fn sp_cp437_grid_height(
|
|||
(*cp437_grid).0.height()
|
||||
}
|
||||
|
||||
/// Gets an unsafe reference to the data of the `SPCp437Grid` instance.
|
||||
/// Gets an unsafe reference to the data of the [SPCp437Grid] instance.
|
||||
///
|
||||
/// Will never return NULL.
|
||||
///
|
||||
|
|
@ -228,9 +228,9 @@ pub unsafe extern "C" fn sp_cp437_grid_height(
|
|||
///
|
||||
/// The caller has to make sure that:
|
||||
///
|
||||
/// - `cp437_grid` points to a valid `SPCp437Grid`
|
||||
/// - the returned memory range is never accessed after the passed `SPCp437Grid` has been freed
|
||||
/// - the returned memory range is never accessed concurrently, either via the `SPCp437Grid` or directly
|
||||
/// - `cp437_grid` points to a valid [SPCp437Grid]
|
||||
/// - the returned memory range is never accessed after the passed [SPCp437Grid] has been freed
|
||||
/// - the returned memory range is never accessed concurrently, either via the [SPCp437Grid] or directly
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn sp_cp437_grid_unsafe_data_ref(
|
||||
cp437_grid: *mut SPCp437Grid,
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
//! C functions for interacting with `SPPacket`s
|
||||
//! C functions for interacting with [SPPacket]s
|
||||
//!
|
||||
//! prefix `sp_packet_`
|
||||
|
||||
|
|
@ -9,7 +9,7 @@ use crate::SPCommand;
|
|||
/// The raw packet
|
||||
pub struct SPPacket(pub(crate) servicepoint::packet::Packet);
|
||||
|
||||
/// Turns a [SPCommand] into a `SPPacket`.
|
||||
/// Turns a [SPCommand] into a [SPPacket].
|
||||
/// The [SPCommand] gets consumed.
|
||||
///
|
||||
/// Will never return NULL.
|
||||
|
|
@ -20,7 +20,7 @@ pub struct SPPacket(pub(crate) servicepoint::packet::Packet);
|
|||
///
|
||||
/// - [SPCommand] points to a valid instance of [SPCommand]
|
||||
/// - [SPCommand] is not used concurrently or after this call
|
||||
/// - the returned `SPPacket` instance is freed in some way, either by using a consuming function or
|
||||
/// - the returned [SPPacket] instance is freed in some way, either by using a consuming function or
|
||||
/// by explicitly calling `sp_packet_free`.
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn sp_packet_from_command(
|
||||
|
|
@ -31,7 +31,7 @@ pub unsafe extern "C" fn sp_packet_from_command(
|
|||
Box::into_raw(Box::new(packet))
|
||||
}
|
||||
|
||||
/// Tries to load a `SPPacket` from the passed array with the specified length.
|
||||
/// Tries to load a [SPPacket] from the passed array with the specified length.
|
||||
///
|
||||
/// returns: NULL in case of an error, pointer to the allocated packet otherwise
|
||||
///
|
||||
|
|
@ -41,7 +41,7 @@ pub unsafe extern "C" fn sp_packet_from_command(
|
|||
///
|
||||
/// - `data` points to a valid memory region of at least `length` bytes
|
||||
/// - `data` is not written to concurrently
|
||||
/// - the returned `SPPacket` instance is freed in some way, either by using a consuming function or
|
||||
/// - the returned [SPPacket] instance is freed in some way, either by using a consuming function or
|
||||
/// by explicitly calling `sp_packet_free`.
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn sp_packet_try_load(
|
||||
|
|
@ -55,7 +55,7 @@ pub unsafe extern "C" fn sp_packet_try_load(
|
|||
}
|
||||
}
|
||||
|
||||
/// Clones a `SPPacket`.
|
||||
/// Clones a [SPPacket].
|
||||
///
|
||||
/// Will never return NULL.
|
||||
///
|
||||
|
|
@ -63,7 +63,7 @@ pub unsafe extern "C" fn sp_packet_try_load(
|
|||
///
|
||||
/// The caller has to make sure that:
|
||||
///
|
||||
/// - `packet` points to a valid `SPPacket`
|
||||
/// - `packet` points to a valid [SPPacket]
|
||||
/// - `packet` is not written to concurrently
|
||||
/// - the returned instance is freed in some way, either by using a consuming function or
|
||||
/// by explicitly calling `sp_packet_free`.
|
||||
|
|
@ -74,13 +74,13 @@ pub unsafe extern "C" fn sp_packet_clone(
|
|||
Box::into_raw(Box::new(SPPacket((*packet).0.clone())))
|
||||
}
|
||||
|
||||
/// Deallocates a `SPPacket`.
|
||||
/// Deallocates a [SPPacket].
|
||||
///
|
||||
/// # Safety
|
||||
///
|
||||
/// The caller has to make sure that:
|
||||
///
|
||||
/// - `packet` points to a valid `SPPacket`
|
||||
/// - `packet` points to a valid [SPPacket]
|
||||
/// - `packet` is not used concurrently or after this call
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn sp_packet_free(packet: *mut SPPacket) {
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
//! C functions for interacting with `SPPixelGrid`s
|
||||
//! C functions for interacting with [SPPixelGrid]s
|
||||
//!
|
||||
//! prefix `sp_pixel_grid_`
|
||||
|
||||
|
|
@ -18,14 +18,14 @@ use crate::byte_slice::SPByteSlice;
|
|||
/// ```
|
||||
pub struct SPPixelGrid(pub(crate) servicepoint::PixelGrid);
|
||||
|
||||
/// Creates a new `SPPixelGrid` with the specified dimensions.
|
||||
/// Creates a new [SPPixelGrid] with the specified dimensions.
|
||||
///
|
||||
/// # Arguments
|
||||
///
|
||||
/// - `width`: size in pixels in x-direction
|
||||
/// - `height`: size in pixels in y-direction
|
||||
///
|
||||
/// returns: `SPPixelGrid` initialized to all pixels off. Will never return NULL.
|
||||
/// returns: [SPPixelGrid] initialized to all pixels off. Will never return NULL.
|
||||
///
|
||||
/// # Panics
|
||||
///
|
||||
|
|
@ -47,14 +47,14 @@ pub unsafe extern "C" fn sp_pixel_grid_new(
|
|||
))))
|
||||
}
|
||||
|
||||
/// Loads a `SPPixelGrid` with the specified dimensions from the provided data.
|
||||
/// Loads a [SPPixelGrid] with the specified dimensions from the provided data.
|
||||
///
|
||||
/// # Arguments
|
||||
///
|
||||
/// - `width`: size in pixels in x-direction
|
||||
/// - `height`: size in pixels in y-direction
|
||||
///
|
||||
/// returns: `SPPixelGrid` that contains a copy of the provided data. Will never return NULL.
|
||||
/// returns: [SPPixelGrid] that contains a copy of the provided data. Will never return NULL.
|
||||
///
|
||||
/// # Panics
|
||||
///
|
||||
|
|
@ -81,7 +81,7 @@ pub unsafe extern "C" fn sp_pixel_grid_load(
|
|||
))))
|
||||
}
|
||||
|
||||
/// Clones a `SPPixelGrid`.
|
||||
/// Clones a [SPPixelGrid].
|
||||
///
|
||||
/// Will never return NULL.
|
||||
///
|
||||
|
|
@ -89,7 +89,7 @@ pub unsafe extern "C" fn sp_pixel_grid_load(
|
|||
///
|
||||
/// The caller has to make sure that:
|
||||
///
|
||||
/// - `pixel_grid` points to a valid `SPPixelGrid`
|
||||
/// - `pixel_grid` points to a valid [SPPixelGrid]
|
||||
/// - `pixel_grid` is not written to concurrently
|
||||
/// - the returned instance is freed in some way, either by using a consuming function or
|
||||
/// by explicitly calling `sp_pixel_grid_free`.
|
||||
|
|
@ -100,13 +100,13 @@ pub unsafe extern "C" fn sp_pixel_grid_clone(
|
|||
Box::into_raw(Box::new(SPPixelGrid((*pixel_grid).0.clone())))
|
||||
}
|
||||
|
||||
/// Deallocates a `SPPixelGrid`.
|
||||
/// Deallocates a [SPPixelGrid].
|
||||
///
|
||||
/// # Safety
|
||||
///
|
||||
/// The caller has to make sure that:
|
||||
///
|
||||
/// - `pixel_grid` points to a valid `SPPixelGrid`
|
||||
/// - `pixel_grid` points to a valid [SPPixelGrid]
|
||||
/// - `pixel_grid` is not used concurrently or after pixel_grid call
|
||||
/// - `pixel_grid` was not passed to another consuming function, e.g. to create a [SPCommand]
|
||||
#[no_mangle]
|
||||
|
|
@ -114,7 +114,7 @@ pub unsafe extern "C" fn sp_pixel_grid_free(pixel_grid: *mut SPPixelGrid) {
|
|||
_ = Box::from_raw(pixel_grid);
|
||||
}
|
||||
|
||||
/// Gets the current value at the specified position in the `SPPixelGrid`.
|
||||
/// Gets the current value at the specified position in the [SPPixelGrid].
|
||||
///
|
||||
/// # Arguments
|
||||
///
|
||||
|
|
@ -129,7 +129,7 @@ pub unsafe extern "C" fn sp_pixel_grid_free(pixel_grid: *mut SPPixelGrid) {
|
|||
///
|
||||
/// The caller has to make sure that:
|
||||
///
|
||||
/// - `pixel_grid` points to a valid `SPPixelGrid`
|
||||
/// - `pixel_grid` points to a valid [SPPixelGrid]
|
||||
/// - `pixel_grid` is not written to concurrently
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn sp_pixel_grid_get(
|
||||
|
|
@ -140,7 +140,7 @@ pub unsafe extern "C" fn sp_pixel_grid_get(
|
|||
(*pixel_grid).0.get(x, y)
|
||||
}
|
||||
|
||||
/// Sets the value of the specified position in the `SPPixelGrid`.
|
||||
/// Sets the value of the specified position in the [SPPixelGrid].
|
||||
///
|
||||
/// # Arguments
|
||||
///
|
||||
|
|
@ -158,7 +158,7 @@ pub unsafe extern "C" fn sp_pixel_grid_get(
|
|||
///
|
||||
/// The caller has to make sure that:
|
||||
///
|
||||
/// - `pixel_grid` points to a valid `SPPixelGrid`
|
||||
/// - `pixel_grid` points to a valid [SPPixelGrid]
|
||||
/// - `pixel_grid` is not written to or read from concurrently
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn sp_pixel_grid_set(
|
||||
|
|
@ -170,7 +170,7 @@ pub unsafe extern "C" fn sp_pixel_grid_set(
|
|||
(*pixel_grid).0.set(x, y, value);
|
||||
}
|
||||
|
||||
/// Sets the state of all pixels in the `SPPixelGrid`.
|
||||
/// Sets the state of all pixels in the [SPPixelGrid].
|
||||
///
|
||||
/// # Arguments
|
||||
///
|
||||
|
|
@ -181,7 +181,7 @@ pub unsafe extern "C" fn sp_pixel_grid_set(
|
|||
///
|
||||
/// The caller has to make sure that:
|
||||
///
|
||||
/// - `pixel_grid` points to a valid `SPPixelGrid`
|
||||
/// - `pixel_grid` points to a valid [SPPixelGrid]
|
||||
/// - `pixel_grid` is not written to or read from concurrently
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn sp_pixel_grid_fill(
|
||||
|
|
@ -191,7 +191,7 @@ pub unsafe extern "C" fn sp_pixel_grid_fill(
|
|||
(*pixel_grid).0.fill(value);
|
||||
}
|
||||
|
||||
/// Gets the width in pixels of the `SPPixelGrid` instance.
|
||||
/// Gets the width in pixels of the [SPPixelGrid] instance.
|
||||
///
|
||||
/// # Arguments
|
||||
///
|
||||
|
|
@ -201,7 +201,7 @@ pub unsafe extern "C" fn sp_pixel_grid_fill(
|
|||
///
|
||||
/// The caller has to make sure that:
|
||||
///
|
||||
/// - `pixel_grid` points to a valid `SPPixelGrid`
|
||||
/// - `pixel_grid` points to a valid [SPPixelGrid]
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn sp_pixel_grid_width(
|
||||
pixel_grid: *const SPPixelGrid,
|
||||
|
|
@ -209,7 +209,7 @@ pub unsafe extern "C" fn sp_pixel_grid_width(
|
|||
(*pixel_grid).0.width()
|
||||
}
|
||||
|
||||
/// Gets the height in pixels of the `SPPixelGrid` instance.
|
||||
/// Gets the height in pixels of the [SPPixelGrid] instance.
|
||||
///
|
||||
/// # Arguments
|
||||
///
|
||||
|
|
@ -219,7 +219,7 @@ pub unsafe extern "C" fn sp_pixel_grid_width(
|
|||
///
|
||||
/// The caller has to make sure that:
|
||||
///
|
||||
/// - `pixel_grid` points to a valid `SPPixelGrid`
|
||||
/// - `pixel_grid` points to a valid [SPPixelGrid]
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn sp_pixel_grid_height(
|
||||
pixel_grid: *const SPPixelGrid,
|
||||
|
|
@ -227,15 +227,15 @@ pub unsafe extern "C" fn sp_pixel_grid_height(
|
|||
(*pixel_grid).0.height()
|
||||
}
|
||||
|
||||
/// Gets an unsafe reference to the data of the `SPPixelGrid` instance.
|
||||
/// Gets an unsafe reference to the data of the [SPPixelGrid] instance.
|
||||
///
|
||||
/// ## Safety
|
||||
///
|
||||
/// The caller has to make sure that:
|
||||
///
|
||||
/// - `pixel_grid` points to a valid `SPPixelGrid`
|
||||
/// - the returned memory range is never accessed after the passed `SPPixelGrid` has been freed
|
||||
/// - the returned memory range is never accessed concurrently, either via the `SPPixelGrid` or directly
|
||||
/// - `pixel_grid` points to a valid [SPPixelGrid]
|
||||
/// - the returned memory range is never accessed after the passed [SPPixelGrid] has been freed
|
||||
/// - the returned memory range is never accessed concurrently, either via the [SPPixelGrid] or directly
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn sp_pixel_grid_unsafe_data_ref(
|
||||
pixel_grid: *mut SPPixelGrid,
|
||||
|
|
|
|||
Loading…
Reference in a new issue