gc_abi 0.3.0

Gridcore Plugin Safe ABI Bindings
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
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124

use crate::GCLogLevel;
use crate::GCPluginConfig;
use crate::error::GCPluginABIError;
use crate::raw;
use crate::{GCAbiConversion, GCDatapointID, GCDatapointValue};
use std::ffi::CStr;

pub struct GCCoreExportedFunctions {
    pub log_system: raw::GCSystemLogCoreExport,
    pub log_audit: raw::GCSystemLogAuditCoreExport,
    pub release_datapoint_value: raw::GCReleaseDatapointValueCoreExport,
    pub get_last_datapoint_value: raw::GCGetLastDatapointValueCoreExport,
    pub publish_datapoint_value: raw::GCPublishDatapointValueCoreExport,
    pub store_datapoint_value: raw::GCStoreDatapointValueCoreExport,
}

/// Zero cost abstraction over the GCPluginInterface
/// Safety:
/// All the function calls are valid as long as the underlying GCPluginInterface pointer is valid
#[repr(transparent)]
pub struct GCPluginInterface(gc_abi_sys::sGCPluginInterface);

impl GCPluginInterface {
    /// Create a new GCPluginInterface
    ///
    /// # Safety
    /// The caller is responsible for ensuring the ctx and config are valid for the lifetime of the GCPluginInterface
    pub unsafe fn new<T>(config: GCPluginConfig, ctx: *const T, exports: GCCoreExportedFunctions, log_level: GCLogLevel) -> Self {
        GCPluginInterface(gc_abi_sys::sGCPluginInterface {
            config: config.into_c(),
            ctx: ctx as *mut std::ffi::c_void,
            logSystemCallback: exports.log_system,
            logLevel: log_level.into_c(),
            logAuditCallback: exports.log_audit,
            releaseDatapointValueCallback: exports.release_datapoint_value,
            getLastDatapointValueCallback: exports.get_last_datapoint_value,
            publishDatapointValueCallback: exports.publish_datapoint_value,
            storeDatapointValueCallback: exports.store_datapoint_value,
        })
    }

    /// Publishes a datapoint value
    #[inline]
    pub fn publish_datapoint(&self, datapoint_value: &GCDatapointValue) -> bool {
        // Safety:
        // Calling FFI functions is inherently unsafe, the gateway core guarantees that callbacks are always valid
        unsafe {
            let ptr = datapoint_value as *const GCDatapointValue;
            self.0.publishDatapointValueCallback.unwrap_unchecked()(self.0.ctx, ptr as *mut gc_abi_sys::sGCDatapointValue)
        }
    }

    /// Stores a datapoint value in the timeseries database
    #[inline]
    pub fn store_datapoint(&self, datapoint_value: &GCDatapointValue) {
        // Safety:
        // Calling FFI functions is inherently unsafe, the gateway core guarantees that callbacks are always valid
        unsafe {
            let ptr = datapoint_value as *const GCDatapointValue;
            self.0.storeDatapointValueCallback.unwrap_unchecked()(self.0.ctx, ptr as *mut gc_abi_sys::sGCDatapointValue)
        }
    }

    /// Returns the configuration of the plugin
    #[inline]
    pub fn get_config(&self) -> &GCPluginConfig {
        GCPluginConfig::from_c_ref(&self.0.config)
    }

    /// Retrieve the last value of a datapoint from the realtime database
    ///
    /// # Safety
    /// The caller is responsible for freeing the memory of the returned value and also it has to ensure the pointer is not null
    #[inline]
    pub unsafe fn get_last_datapoint_value(&self, datapoint_id: GCDatapointID) -> *const GCDatapointValue {
        unsafe {
            let ptr: gc_abi_sys::GCDatapointValue = self.0.getLastDatapointValueCallback.unwrap()(self.0.ctx, datapoint_id);
            ptr as *const GCDatapointValue
        }
    }

    /// Log a message
    #[inline]
    pub fn log(&self, level: gc_abi_sys::eGCLogLevel, message: &CStr) {
        // Safety:
        // The pointer is guaranteed to be valid by the gateway core
        unsafe { self.0.logSystemCallback.unwrap_unchecked()(self.0.ctx, level, message.as_ptr()) }
    }

    /// Log a message audit
    #[inline]
    pub fn log_audit(&self, message: &CStr) {
        // Safety:
        // The pointer is guaranteed to be valid by the gateway core
        unsafe { self.0.logAuditCallback.unwrap_unchecked()(self.0.ctx, message.as_ptr()) }
    }

    /// Get the C log level of the plugin
    #[inline]
    pub fn get_raw_log_level(&self) -> gc_abi_sys::eGCLogLevel {
        self.0.logLevel
    }

    /// Get the log level of the plugin
    #[inline]
    pub fn get_log_level(&self) -> Result<GCLogLevel, GCPluginABIError> {
        GCLogLevel::from_c(self.get_raw_log_level())
    }
}

unsafe impl GCAbiConversion for GCPluginInterface {
    type CType = gc_abi_sys::sGCPluginInterface;

    fn from_c(c_type: Self::CType) -> Self {
        GCPluginInterface(c_type)
    }

    fn into_c(self) -> Self::CType {
        self.0
    }
}

unsafe impl Send for GCPluginInterface {}
unsafe impl Sync for GCPluginInterface {}