servicepoint/servicepoint-binding-c
Watch
0
2
Fork
You've already forked servicepoint-binding-c
 0
Code Issues 1 Pull requests 1 Projects Releases 2 Packages Wiki Activity Actions

wip fix documentation

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

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_`
//!
@ -9,10 +9,10 @@ use crate::SPByteSlice;
use servicepoint::{Header, Packet, TypedCommand};
use std::ptr::NonNull;
/// Turns a [SPCommand] into a [SPPacket].
/// The [SPCommand] gets consumed.
/// Turns a [TypedCommand] into a [Packet].
/// The [TypedCommand] gets consumed.
///
/// Will never return NULL.
/// Returns NULL in case of an error.
///
/// # Panics
///
@ -22,9 +22,9 @@ use std::ptr::NonNull;
///
/// The caller has to make sure that:
///
/// - [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
/// - [TypedCommand] points to a valid instance of [TypedCommand]
/// - [TypedCommand] is not used concurrently or after this call
/// - the returned [Packet] 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(
@ -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
///
@ -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` 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`.
#[no_mangle]
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
///
@ -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` 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].
#[no_mangle]
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))
}
/// 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]
pub unsafe extern "C" fn sp_packet_get_header(
packet: NonNull<Packet>,
@ -110,6 +113,9 @@ pub unsafe extern "C" fn sp_packet_get_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]
pub unsafe extern "C" fn sp_packet_get_payload(
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) }
}
/// Sets the payload of the provided packet to the provided data.
///
/// This makes previous payload pointers invalid.
#[no_mangle]
pub unsafe extern "C" fn sp_packet_set_payload(
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() }
}
/// Serialize the packet into the provided buffer.
///
/// # Panics
///
/// - if the buffer is not big enough to hold header+payload.
#[no_mangle]
pub unsafe extern "C" fn sp_packet_write_to(
pub unsafe extern "C" fn sp_packet_serialize_to(
packet: NonNull<Packet>,
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.
///
@ -147,7 +161,7 @@ pub unsafe extern "C" fn sp_packet_write_to(
///
/// 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
/// - the returned instance is freed in some way, either by using a consuming function or
/// by explicitly calling `sp_packet_free`.
@ -159,7 +173,7 @@ pub unsafe extern "C" fn sp_packet_clone(
NonNull::from(Box::leak(result))
}
/// Deallocates a [SPPacket].
/// Deallocates a [Packet].
///
/// # Panics
///
@ -169,7 +183,7 @@ pub unsafe extern "C" fn sp_packet_clone(
///
/// 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
#[no_mangle]
pub unsafe extern "C" fn sp_packet_free(packet: NonNull<Packet>) {