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 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557
//! The KPAL plugin crate provides tools to write your own KPAL plugins. //! //! See the examples folder for ideas on how to implement the datatypes and methods defined in this //! library. mod constants; mod errors; mod ffi; mod strings; use std::{ cell::{Ref, RefCell}, cmp::PartialEq, error::Error, ffi::{CStr, CString, FromBytesWithNulError}, fmt, slice, }; use libc::{c_char, c_double, c_int, c_uchar, c_uint, size_t}; pub use multi_map::{multimap, MultiMap}; pub use { constants::*, errors::error_codes, errors::{PluginUninitializedError, ERRORS}, ffi::*, strings::copy_string, }; /// The set of functions that must be implemented by a plugin. pub trait PluginAPI<E: Error + PluginError + 'static> where Self: Sized, { /// Returns a new instance of the plugin. No initialization of the hardware is performed. fn new() -> Result<Self, E>; /// Initialzes the plugin by performing any hardware initialization. fn init(&mut self) -> Result<(), E>; /// Returns the attributes of the plugin. fn attributes(&self) -> &Attributes<Self, E>; /// Returns the number of attributes of the plugin. fn attribute_count(&self) -> usize { self.attributes().borrow().iter().count() } /// Returns the attribute IDs. fn attribute_ids(&self) -> Vec<usize> { self.attributes() .borrow() .iter() .map(|(id, _)| *id) .collect() } /// Returns the name of an attribute. /// /// If the attribute that corresponds to the `id` does not exist, then an error is /// returned. Otherwise, the name is returned as a C-compatible `&CStr`. /// /// # Arguments /// /// * `id` - the numeric ID of the attribute fn attribute_name(&self, id: usize) -> Result<Ref<CString>, E> { log::debug!("Received request for the name of attribute: {}", id); let attributes = self.attributes().borrow(); match attributes.get(&id) { Some(_) => Ok(Ref::map(attributes, |a| { &a.get(&id) .expect("Attribute does not exist. This should never happen.") .name })), None => Err(E::new(error_codes::ATTRIBUTE_DOES_NOT_EXIST)), } } /// Indicates whether an attribute may be set before initialization. /// /// # Arguments /// /// # `id` - the numeric ID of the attribute fn attribute_pre_init(&self, id: usize) -> Result<bool, E> { log::debug!( "Received request for attribute pre-initialzation status: {}", id ); let attributes = self.attributes(); let attributes = attributes.borrow(); let attribute = attributes .get(&id) .ok_or_else(|| E::new(error_codes::ATTRIBUTE_DOES_NOT_EXIST))?; match attribute.callbacks_init { Callbacks::Update => Ok(true), _ => Ok(false), } } /// Returns the value of an attribute. /// /// If the attribute that corresponds to the `id` does not exist, then an error is /// returned. Otherwise, the value is returnd as a C-compatible tagged enum. /// /// # Arguments /// /// * `id` - the numeric ID of the attribute /// * `phase` - the lifecycle phase of the plugin that determines which callbacks to use fn attribute_value(&self, id: usize, phase: Phase) -> Result<Val, E> { log::debug!("Received request for the value of attribute: {}", id); let attributes = self.attributes(); let mut attributes = attributes.borrow_mut(); let attribute = attributes .get_mut(&id) .ok_or_else(|| E::new(error_codes::ATTRIBUTE_DOES_NOT_EXIST))?; let get = if phase == constants::INIT_PHASE { match attribute.callbacks_init { Callbacks::Constant => return Ok(attribute.value.as_val()), Callbacks::Update => return Ok(attribute.value.as_val()), Callbacks::Get(get) => get, Callbacks::GetAndSet(get, _) => get, } } else if phase == constants::RUN_PHASE { match attribute.callbacks_run { Callbacks::Constant => return Ok(attribute.value.as_val()), Callbacks::Update => return Ok(attribute.value.as_val()), Callbacks::Get(get) => get, Callbacks::GetAndSet(get, _) => get, } } else { return Err(E::new(error_codes::LIFECYCLE_PHASE_ERR)); }; let value = get(&self, &attribute.value).map_err(|err| { log::error!("Callback error {{ id: {:?}, error: {:?} }}", id, err); E::new(error_codes::CALLBACK_ERR) })?; // Update the attribute's cached value. attribute.value = value; Ok(attribute.value.as_val()) } /// Sets the value of the attribute given by the id. /// /// If the attribute that corresponds to the `id` does not exist, or if the attribute cannot be /// set, then an error is returned. /// /// # Arguments /// /// * `id` - the numeric ID of the attribute /// * `val` - a reference to a Val instance /// * `phase` - the lifecycle phase of the plugin that determines which callbacks to use fn attribute_set_value(&self, id: usize, val: &Val, phase: Phase) -> Result<(), E> { log::debug!("Received request to set the value of attribute: {}", id); let attributes = self.attributes(); let mut attributes = attributes.borrow_mut(); let attribute = attributes .get_mut(&id) .ok_or_else(|| E::new(error_codes::ATTRIBUTE_DOES_NOT_EXIST))?; let option_set = if phase == constants::INIT_PHASE { match attribute.callbacks_init { Callbacks::Update => None, Callbacks::GetAndSet(_, set) => Some(set), _ => return Err(E::new(error_codes::ATTRIBUTE_IS_NOT_SETTABLE)), } } else if phase == constants::RUN_PHASE { match attribute.callbacks_run { Callbacks::Update => None, Callbacks::GetAndSet(_, set) => Some(set), _ => return Err(E::new(error_codes::ATTRIBUTE_IS_NOT_SETTABLE)), } } else { return Err(E::new(error_codes::LIFECYCLE_PHASE_ERR)); }; if let Some(set) = option_set { // This MUST be updated each time a new variant is added to the Value and Val enums. let result = match (&attribute.value, &val) { (Value::Int(_), Val::Int(_)) | (Value::Double(_), Val::Double(_)) | (Value::String(_), Val::String(_, _)) | (Value::Uint(_), Val::Uint(_)) => set(&self, &attribute.value, val), _ => Err(E::new(error_codes::ATTRIBUTE_TYPE_MISMATCH)), }; result.map_err(|err| { log::error!("Callback error {{ id: {:?}, error: {:?} }}", id, err); E::new(error_codes::CALLBACK_ERR) })?; }; // Update the attribute's cached value. attribute.value = val.to_value().map_err(|err| { log::error!( "Could not update plugin attribute's cached value: {{ id: {:?}, error: {:?} }}", id, err ); E::new(error_codes::UPDATE_CACHED_VALUE_ERR) })?; Ok(()) } } /// The set of functions that must be implemented by a plugin library's main error type. pub trait PluginError: std::error::Error { /// Initializes and returns a new instace of the error type. /// /// # Arguments /// /// * `error_code` - One of the integer error codes recognized by KPAL. fn new(error_code: c_int) -> Self; /// Returns the error code of the instance. fn error_code(&self) -> c_int; } /// A Plugin combines the data that determines its state and with its functionality. /// /// This struct holds a raw pointer to a data struct that is created by the plugin library. In /// addition, it contains the vtable of function pointers defined by the C API and implemented /// within the plugin library. /// /// # Safety /// /// The plugin implements the `Send` trait because after creation the plugin is moved into the /// thread that is dedicated to the plugin that it manages. Once it is moved, it will only ever be /// owned and used by this single thread by design. #[derive(Clone, Debug)] #[repr(C)] pub struct Plugin { /// A pointer to a struct containing the state of the plugin. pub plugin_data: *mut PluginData, /// The table of function pointers that define part of the plugin API. pub vtable: VTable, } impl Drop for Plugin { /// Frees the memory allocated to the plugin data. fn drop(&mut self) { (self.vtable.plugin_free)(self.plugin_data); } } unsafe impl Send for Plugin {} /// An opaque struct that contains the state of an individual plugin. /// /// The daemon does not actually work directly with structs provided by a plugin library. Instead, /// they are hidden behind pointers to opaque structs of this type. The kpal-plugin FFI code takes /// care of casting the pointers back into the appropriate type inside the library code. /// /// # Notes /// /// In Rust, an opaque struct is defined as a struct with a field that is a zero-length array of /// unsigned 8-bit integers. It is used to hide the plugin's state, forcing all interactions /// with the data through the functions in the vtable instead. #[derive(Debug)] #[repr(C)] pub struct PluginData { _private: [u8; 0], } /// A table of function pointers that comprise the plugin API for the foreign function interface. /// /// By default, functions in the VTable return a number that represents a status code that maps /// onto a particular reason for an error. All functions should use the same mapping between status /// code and reason. /// /// Functions that return values that do not represent status codes have names that end in the /// characters '_ns' that stand for "no status." #[derive(Clone, Debug)] #[repr(C)] pub struct VTable { /// Frees the memory associated with a plugin's data. pub plugin_free: extern "C" fn(*mut PluginData), /// Initializes a plugin. /// /// This method is distinct from the `kpal_plugin_new` FFI call in that it actually /// communicates with the hardware, whereas `kpal_plugin_new` is used merely to create the /// plugin data structures. pub plugin_init: unsafe extern "C" fn(*mut PluginData) -> c_int, /// Returns an error message associated with a Plugin error code. pub error_message_ns: extern "C" fn(c_int) -> *const c_uchar, /// Returns the number of attributes of the plugin. pub attribute_count: unsafe extern "C" fn(plugin_data: *const PluginData, count: *mut size_t) -> c_int, /// Returns the attribute IDs in a buffer provided by the caller. pub attribute_ids: unsafe extern "C" fn(plugin_data: *const PluginData, ids: *mut size_t, size_t) -> c_int, /// Writes the name of an attribute to a buffer that is provided by the caller. pub attribute_name: unsafe extern "C" fn( plugin_data: *const PluginData, id: size_t, buffer: *mut c_uchar, length: size_t, ) -> c_int, /// Indicates whether an attribute may be set before initialization. pub attribute_pre_init: unsafe extern "C" fn( plugin_data: *const PluginData, id: size_t, pre_init: *mut c_char, ) -> c_int, /// Writes the value of an attribute to a Value instance that is provided by the caller. pub attribute_value: unsafe extern "C" fn( plugin_data: *const PluginData, id: size_t, value: *mut Val, phase: Phase, ) -> c_int, /// Sets the value of an attribute. pub set_attribute_value: unsafe extern "C" fn( plugin_data: *mut PluginData, id: size_t, value: *const Val, phase: Phase, ) -> c_int, } /// The type signature of the function that returns a new plugin instance. pub type KpalPluginInit = unsafe extern "C" fn(*mut Plugin) -> c_int; /// The type signature of the function that initializes a library. pub type KpalLibraryInit = unsafe extern "C" fn() -> c_int; /// The type signature of the collection of attributes that is owned by the plugin. pub type Attributes<T, E> = RefCell<MultiMap<usize, &'static str, Attribute<T, E>>>; /// A single piece of information that partly determines the state of a plugin. #[derive(Debug)] #[repr(C)] pub struct Attribute<T, E: Error + PluginError> { /// The name of the attribute. pub name: CString, /// The value of the attribute. /// /// This field may be used to cache values retrieved from the hardware. This is the initial /// value of non-constant attributes. pub value: Value, /// The callback functions that are fired when the attribute is either read or set during the /// init phase of the plugin. pub callbacks_init: Callbacks<T, E>, /// The callback functions that are fired when the attribute is either read or set during the /// run phase of the plugin. pub callbacks_run: Callbacks<T, E>, } /// An owned value of an attribute. /// /// Unlike the `Val` enum, these are intended to be owned by an instance of a PluginData struct and /// do not pass through the FFI. #[derive(Clone, Debug, PartialEq)] #[repr(C)] pub enum Value { Int(c_int), Double(c_double), String(CString), Uint(c_uint), } impl Value { /// Returns a reference type to a Value. /// /// as_val creates a new Val instance from a Value. Value variants that contain datatypes that /// implement Copy are copied into the new Val instance. For complex datatypes that are not /// Copy, pointers to the data are embedded inside the Val instance instead. /// /// This method is used to generate datatypes that represent attribute values and that may pass /// through the FFI. pub fn as_val(&self) -> Val { match self { Value::Int(value) => Val::Int(*value), Value::Double(value) => Val::Double(*value), Value::String(value) => { let slice = value.as_bytes_with_nul(); Val::String(slice.as_ptr(), slice.len()) } Value::Uint(value) => Val::Uint(*value), } } } /// A wrapper type for transporting Values through the plugin API. /// /// Unlike the `Value` enum, this type is intended to be sent through the FFI. Because of this, the /// enum variants can only contain C-compatible datatypes. #[derive(Clone, Debug, PartialEq)] #[repr(C)] pub enum Val { Int(c_int), Double(c_double), String(*const c_uchar, size_t), Uint(c_uint), } impl Val { /// Clones the data inside a Val into a new Value type. /// /// This method is used to convert Vals, which pass through the FFI, into owned Value /// datatypes. Wrapped data that is not Copy is necessarily cloned when the new Value instance /// is created. pub fn to_value(&self) -> Result<Value, ValueConversionError> { match self { Val::Int(value) => Ok(Value::Int(*value)), Val::Double(value) => Ok(Value::Double(*value)), Val::String(p_value, length) => { let slice = unsafe { slice::from_raw_parts(*p_value, *length) }; let c_string = CStr::from_bytes_with_nul(slice)?.to_owned(); Ok(Value::String(c_string)) } Val::Uint(value) => Ok(Value::Uint(*value)), } } } /// Callback functions that communicate with the hardware when an attribute is read or set. /// /// The purpose of a callback is two-fold: it performs the actual communication with the hardware /// and/or it modifies the plugin's cached attribute data. /// /// If the attribute is constant and never changes its original value, then the `Constant` variant /// should be used. If the attribute's value changes without user input (e.g. a sensor reading) but /// cannot be set, then use the `Get` variant. Otherwise, for attributes that can be both read and /// set, use the `GetAndSet` variant. /// /// The Update variant is used to set only the cached value of attributes. Attributes that are /// Update always return their cached value when the attribute's value is read. #[repr(C)] pub enum Callbacks<T, E: Error + PluginError> { Constant, Get(fn(plugin: &T, cached: &Value) -> Result<Value, E>), GetAndSet( fn(plugin: &T, cached: &Value) -> Result<Value, E>, fn(plugin: &T, cached: &Value, value: &Val) -> Result<(), E>, ), Update, } impl<T, E: Error + PluginError> fmt::Debug for Callbacks<T, E> { fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { use Callbacks::*; match *self { Constant => write!(f, "Constant"), Get(get) => write!(f, "Get Callback: {:x}", get as usize), GetAndSet(get, set) => write!( f, "Get Callback: {:x}, Set Callback: {:x}", get as usize, set as usize ), Update => write!(f, "Update"), } } } /// Creates the required symbols for a plugin library. /// /// Any plugin library must call this macro exactly once to generate the symbols that are required /// by the daemon. #[macro_export] macro_rules! declare_plugin { ($plugin_type:ty, $plugin_err_type:ty) => { /// Initializes the library. /// /// This function is called only once by the daemon. It is called when a library is first /// loaded into memory. #[no_mangle] pub extern "C" fn kpal_library_init() -> c_int { env_logger::init(); PLUGIN_OK } /// Returns a new Plugin instance containing the plugin data and the function vtable. /// /// The plugin is used by the daemon to communicate with it. It contains an opaque pointer /// to the plugin data and a vtable. The vtable is a struct of function pointers to the /// methods in the plugin API. /// /// # Safety /// /// This function is unsafe because it dereferences a null pointer and assigns data to a /// variable of the type `MaybeUnit`. #[no_mangle] pub unsafe extern "C" fn kpal_plugin_new(plugin: *mut Plugin) -> c_int { let plugin_data = match <$plugin_type>::new() { Ok(plugin_data) => plugin_data, Err(e) => { log::error!("Failed to initialize the plugin: {:?}", e); return PLUGIN_INIT_ERR; } }; let plugin_data: Box<$plugin_type> = Box::new(plugin_data); let plugin_data = Box::into_raw(plugin_data) as *mut PluginData; let vtable = VTable { plugin_free, plugin_init: plugin_init::<$plugin_type, $plugin_err_type>, error_message_ns, attribute_count: attribute_count::<$plugin_type, $plugin_err_type>, attribute_ids: attribute_ids::<$plugin_type, $plugin_err_type>, attribute_name: attribute_name::<$plugin_type, $plugin_err_type>, attribute_pre_init: attribute_pre_init::<$plugin_type, $plugin_err_type>, attribute_value: attribute_value::<$plugin_type, $plugin_err_type>, set_attribute_value: set_attribute_value::<$plugin_type, $plugin_err_type>, }; plugin.write(Plugin { plugin_data, vtable, }); log::debug!("Created new plugin: {:?}", plugin); PLUGIN_OK } }; } /// An error type that represents a failure to convert a Val to a Value. #[derive(Debug)] pub struct ValueConversionError { side: FromBytesWithNulError, } impl Error for ValueConversionError { fn source(&self) -> Option<&(dyn Error + 'static)> { Some(&self.side) } } impl fmt::Display for ValueConversionError { fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { write!(f, "PluginError: {:?}", self) } } impl From<FromBytesWithNulError> for ValueConversionError { fn from(error: FromBytesWithNulError) -> Self { ValueConversionError { side: error } } }