fre-rs 0.4.0

Safe, ergonomic Rust abstraction over the AIR Native Extension (ANE) C API (`fre-sys`) for native-side development.
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
86
87
88
89
90
91
92

//! 
//! Asynchronous event dispatching utilities for cross-thread scenarios,
//! providing a safe interface for interacting with the Flash Runtime.
//! 


use super::*;


/// A handle for dispatching events that may become invalid under the same
/// conditions as [`Context`].
///
/// In asynchronous scenarios, its validity is difficult to predict.
/// Therefore, all APIs on this type are safe to call, but their execution
/// results cannot be guaranteed or reliably observed.
/// 
#[derive(Debug, Clone, Copy)]
pub struct EventDispatcher (pub(crate) crate::context::ContextHandle);
impl EventDispatcher {

    /// Attempts to dispatch a event to the associated `ExtensionContext`.
    ///
    /// If the underlying context has already been disposed, this call has no effect.
    /// 
    pub fn dispatch (self, event: Event) {
        let r = unsafe {FREDispatchStatusEventAsync(self.0.as_ptr(), event.code.as_ptr(), event.level.as_ptr())};
        debug_assert!(r.is_ok());
    }

    /// Sends a debug message as a event through the associated `ExtensionContext`.
    /// 
    /// If the underlying context has already been disposed, this call has no effect.
    /// 
    pub fn debug (self, message: impl AsRef<str>) {
        let s = message.as_ref();
        let code = match UCStr::try_from(s) {
            Ok(s) => s,
            Err(e) => format!(
                "String contains an unexpected NUL byte at index {} (length: {})\n{}",
                e.nul_position(),
                s.len(),
                std::backtrace::Backtrace::capture(),
            ).try_into().unwrap(),
        };
        let evt = Event { level: EventLevel::Debug, code };
        self.dispatch(evt);
    }
}
unsafe impl Send for EventDispatcher {}


/// `flash.events.StatusEvent`
/// 
#[derive(Debug, Clone)]
pub struct Event {
    pub code: UCStr,
    pub level: EventLevel,
}
impl Event {
    pub fn new (code: UCStr, level: Option<EventLevel>) -> Self {
        let level = level.unwrap_or_default();
        Self { code, level }
    }
}


#[derive(Debug, Clone)]
pub enum EventLevel {
    Status,
    Warning,
    Error,
    Debug,
    Custom(UCStr)
}
impl EventLevel {
    pub fn as_ptr (&self) -> FREStr {
        const STATUS: FREStr = c"status".as_ptr() as FREStr;
        const WARNING: FREStr = c"warning".as_ptr() as FREStr;
        const ERROR: FREStr = c"error".as_ptr() as FREStr;
        const DEBUG: FREStr = c"debug".as_ptr() as FREStr;
        match self {
            Self::Status => STATUS,
            Self::Warning => WARNING,
            Self::Error => ERROR,
            Self::Debug => DEBUG,
            Self::Custom(s) => s.as_ptr(),
        }
    }
}
impl Default for EventLevel {
    fn default() -> Self {Self::Status}
}