servicepoint-binding-c/src/packet.rs

//! C functions for interacting with [Packet]s
//!
//! prefix `sp_packet_`
//!
//!
//! The raw packet

use crate::SPByteSlice;
use servicepoint::{Header, Packet, TypedCommand};
use std::ptr::NonNull;

/// Turns a [TypedCommand] into a [Packet].
/// The [TypedCommand] gets consumed.
///
/// Returns NULL in case of an error.
///
/// # Panics
///
/// - when `command` is NULL
///
/// # Safety
///
/// The caller has to make sure that:
///
/// - [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(
    command: NonNull<TypedCommand>,
) -> *mut Packet {
    let command = unsafe { *Box::from_raw(command.as_ptr()) };
    if let Ok(packet) = command.try_into() {
        Box::leak(Box::new(packet))
    } else {
        std::ptr::null_mut()
    }
}

/// 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
///
/// # Panics
///
/// - when `data` is NULL
///
/// # Safety
///
/// The caller has to make sure that:
///
/// - `data` points to a valid memory region of at least `length` bytes
/// - `data` is not written to concurrently
/// - 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 {
    let data = unsafe { data.as_slice() };
    match servicepoint::Packet::try_from(data) {
        Err(_) => std::ptr::null_mut(),
        Ok(packet) => Box::into_raw(Box::new(packet)),
    }
}

/// Creates a raw [Packet] from parts.
///
/// # Arguments
///
/// - `command_code` specifies which command this packet contains
/// - `a`, `b`, `c` and `d` are command-specific header values
/// - `payload` is the optional data that is part of the command
/// - `payload_len` is the size of the payload
///
/// returns: new instance. Will never return null.
///
/// # Panics
///
/// - when `payload` is null, but `payload_len` is not zero
/// - when `payload_len` is zero, but `payload` is nonnull
///
/// # Safety
///
/// The caller has to make sure that:
///
/// - `payload` points to a valid memory region of at least `payload_len` bytes
/// - `payload` is not written to concurrently
/// - 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(
    header: Header,
    payload: *const SPByteSlice,
) -> NonNull<Packet> {
    let payload = if payload.is_null() {
        vec![]
    } else {
        let payload = unsafe { (*payload).as_slice() };
        Vec::from(payload)
    };

    let packet = Box::new(Packet { header, payload });
    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>,
) -> NonNull<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>,
) -> SPByteSlice {
    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>,
    data: SPByteSlice,
) {
    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_serialize_to(
    packet: NonNull<Packet>,
    buffer: SPByteSlice,
) {
    unsafe {
        packet.as_ref().serialize_to(buffer.as_slice_mut());
    }
}

/// Clones a [Packet].
///
/// Will never return NULL.
///
/// # Panics
///
/// - when `packet` is NULL
///
/// # Safety
///
/// The caller has to make sure that:
///
/// - `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`.
#[no_mangle]
pub unsafe extern "C" fn sp_packet_clone(
    packet: NonNull<Packet>,
) -> NonNull<Packet> {
    let result = Box::new(unsafe { packet.as_ref().clone() });
    NonNull::from(Box::leak(result))
}

/// Deallocates a [Packet].
///
/// # Panics
///
/// - when `packet` is NULL
///
/// # Safety
///
/// The caller has to make sure that:
///
/// - `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>) {
    _ = unsafe { Box::from_raw(packet.as_ptr()) }
}