fswtch 0.1.8

Rust bindings and helpers for writing FreeSWITCH modules
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85

use std::ptr::NonNull;

use crate::{FALSE, GENERR, Result, SUCCESS, Status, SwitchError, status_to_result, sys};

pub struct Stream {
    raw: NonNull<sys::switch_stream_handle_t>,
}

impl Stream {
    /// Wraps a FreeSWITCH stream pointer for the duration of an API callback.
    ///
    /// # Safety
    ///
    /// `raw` must point to a live FreeSWITCH stream handle and remain valid while this wrapper is
    /// used.
    pub unsafe fn from_raw(raw: *mut sys::switch_stream_handle_t) -> Option<Self> {
        NonNull::new(raw).map(|raw| Self { raw })
    }

    pub fn as_ptr(&self) -> *mut sys::switch_stream_handle_t {
        self.raw.as_ptr()
    }

    pub fn write_bytes(&mut self, bytes: &[u8]) -> Result<()> {
        let raw = self.raw.as_ptr();
        // SAFETY: `self.raw` is guaranteed valid by `Stream::from_raw`'s caller contract.
        let Some(write) = (unsafe { &*raw }).raw_write_function else {
            return Err(SwitchError(GENERR));
        };

        // SAFETY: FreeSWITCH's stream writer accepts the stream handle and a byte buffer valid for
        // the duration of the call.
        let status = unsafe { write(raw, bytes.as_ptr().cast_mut(), bytes.len()) };
        status_to_result(status)
    }

    pub fn write_str(&mut self, text: &str) -> Result<()> {
        self.write_bytes(text.as_bytes())
    }
}

/// Writes a string response to a raw FreeSWITCH stream handle.
///
/// # Safety
///
/// `raw` must point to a live FreeSWITCH stream handle and remain valid for the duration of this
/// call.
// SAFETY: The caller must provide a live FreeSWITCH stream handle for the full call duration.
pub unsafe fn write_stream_response(raw: *mut sys::switch_stream_handle_t, text: &str) -> Status {
    // SAFETY: Forwarded from `write_stream_response`'s caller.
    let Some(mut stream) = (unsafe { Stream::from_raw(raw) }) else {
        return FALSE;
    };

    match stream.write_str(text) {
        Ok(()) => SUCCESS,
        Err(error) => error.0,
    }
}

#[derive(Copy, Clone)]
pub struct ApiStream {
    raw: *mut sys::switch_stream_handle_t,
}

impl ApiStream {
    /// Wraps a FreeSWITCH stream pointer for the duration of an API callback.
    ///
    /// # Safety
    ///
    /// `raw` must point to a live FreeSWITCH stream handle and remain valid while this wrapper is
    /// used.
    pub unsafe fn from_raw(raw: *mut sys::switch_stream_handle_t) -> Self {
        Self { raw }
    }

    pub fn as_ptr(self) -> *mut sys::switch_stream_handle_t {
        self.raw
    }

    pub fn write(self, text: &str) -> Status {
        // SAFETY: `ApiStream` is constructed from a live callback stream by `ApiStream::from_raw`.
        unsafe { write_stream_response(self.raw, text) }
    }
}