diff --git a/build.rs b/build.rs index 07cef5f..5341a97 100644 --- a/build.rs +++ b/build.rs @@ -2,7 +2,9 @@ use std::env; use std::path::PathBuf; fn main() { - let library = pkg_config::Config::new().probe("libnotify").unwrap(); + let library = pkg_config::Config::new() + .probe("libnotify") + .expect("Cannot locate libnotify. Is it installed?"); let paths = library .include_paths @@ -17,7 +19,8 @@ fn main() { .generate() .expect("Unable to generate bindings"); - let out_path = PathBuf::from(env::var("OUT_DIR").unwrap()); + let out_path = + PathBuf::from(env::var("OUT_DIR").expect("Out $OUT_DIR not set. Perhaps a bindgen error?")); bindings .write_to_file(out_path.join("bindings.rs")) diff --git a/src/api/functions.rs b/src/api/functions.rs index c314b74..3b73133 100644 --- a/src/api/functions.rs +++ b/src/api/functions.rs @@ -12,6 +12,9 @@ use super::libnotify::*; /// Initialized libnotify. This must be called before any other functions. /// /// Starting from 0.8, if the provided app_name is NULL, libnotify will try to figure it out from the running application. Before it was not allowed, and was causing libnotify not to be initialized. +/// +/// # Errors +/// This function can return LibnotifyError::{InitError, NulError} pub fn init<'a, T>(app_name: T) -> Result<(), LibnotifyError> where T: Into>, @@ -163,6 +166,9 @@ pub fn get_server_info() -> Option { */ /// Sets the application name +/// +/// # Errors +/// This function can return LibnotifyError::NulError pub fn set_app_name(app_name: &str) -> Result<(), LibnotifyError> { let app_name_c = std::ffi::CString::new(app_name)?; unsafe { notify_set_app_name(app_name_c.as_ptr()) }; @@ -174,6 +180,9 @@ pub fn set_app_name(app_name: &str) -> Result<(), LibnotifyError> { /// Available since: 0.8.4 /// /// app_icon is icon name or path to an image +/// +/// # Errors +/// This function can return LibnotifyError::NulError pub fn set_app_icon(app_icon: &str) -> Result<(), LibnotifyError> { let app_icon_c = std::ffi::CString::new(app_icon)?; unsafe { notify_set_app_icon(app_icon_c.as_ptr()) }; diff --git a/src/api/notification.rs b/src/api/notification.rs index be4e6a5..a1e6831 100644 --- a/src/api/notification.rs +++ b/src/api/notification.rs @@ -65,11 +65,7 @@ impl<'a> Notification { /// Create new notification. /// /// # Errors - /// This function will return an error if the supplied bytes contain an - /// internal 0 byte. The [`NulError`](https://doc.rust-lang.org/stable/alloc/ffi/c_str/struct.NulError.html) returned will contain the bytes as well as - /// the position of the nul byte. - /// - /// On libnotify fail it will return Err(&str.into). May change in the future. + /// This function can return LibnotifyError::{NewNotificationError, NulError} pub fn new(summary: &str, body: T, icon: Y) -> Result where T: Into>, @@ -105,6 +101,9 @@ impl<'a> Notification { /// `label` – label for user /// /// `callback` - any closure that accepts &str as an argument, where &str is action name. + /// + /// # Errors + /// This function can return LibnotifyError::NulError pub fn add_action( &mut self, action: &str, @@ -147,6 +146,9 @@ impl<'a> Notification { } /// Synchronously tells the notification server to hide the notification on the screen + /// + /// # Errors + /// This function can return LibnotifyError::{AllocationError, GerrorError} pub fn close(&self) -> Result<(), LibnotifyError> { let mut gerror = std::ptr::null_mut() as *mut GError; @@ -194,6 +196,9 @@ impl<'a> Notification { /// `set_app_icon()`. /// /// Available since: 0.8.4 + /// + /// # Errors + /// This function can return LibnotifyError::{NulError} pub fn set_app_icon(&mut self, app_icon: &str) -> Result<(), LibnotifyError> { let app_icon_c = std::ffi::CString::new(app_icon)?; unsafe { notify_notification_set_app_icon(self.inner, app_icon_c.as_ptr()) }; @@ -206,6 +211,9 @@ impl<'a> Notification { /// If this function is not called, the application name will be set from the value used in init() or overridden with set_app_name(). /// /// Available since: 0.7.3 + /// + /// # Errors + /// This function can return LibnotifyError::{NulError} pub fn set_app_name(&mut self, app_name: &str) -> Result<(), LibnotifyError> { let app_name_c = std::ffi::CString::new(app_name)?; unsafe { notify_notification_set_app_name(self.inner, app_name_c.as_ptr()) }; @@ -216,6 +224,9 @@ impl<'a> Notification { /// Sets the category of this notification. /// /// This can be used by the notification server to filter or display the data in a certain way + /// + /// # Errors + /// This function can return LibnotifyError::{NulError} pub fn set_category(&mut self, category: &str) -> Result<(), LibnotifyError> { let category_c = std::ffi::CString::new(category)?; unsafe { notify_notification_set_category(self.inner, category_c.as_ptr()) }; @@ -226,6 +237,9 @@ impl<'a> Notification { /// Sets a hint for key with value value /// /// Available since: 0.6 + /// + /// # Errors + /// This function can return LibnotifyError::{NulError, AllocationError} pub fn set_hint(&mut self, key: &str, value: HintValue) -> Result<(), LibnotifyError> { let key_c = std::ffi::CString::new(key)?; @@ -274,6 +288,9 @@ impl<'a> Notification { } /// Tells the notification server to display the notification on the screen + /// + /// # Errors + /// This function can return LibnotifyError::{GerrorError, AllocationError} pub fn show(&self) -> Result<(), LibnotifyError> { let mut gerror = std::ptr::null_mut() as *mut GError; @@ -303,12 +320,15 @@ impl<'a> Notification { /// Updates the notification text and icon. /// /// This won’t send the update out and display it on the screen. For that, you will need to call `show()`. + /// + /// # Errors + /// This function can return LibnotifyError::{NulError} pub fn update<'b, F, I>( &mut self, summary: &str, body: F, icon: I, - ) -> Result<(), std::ffi::NulError> + ) -> Result<(), LibnotifyError> where F: Into>, I: Into>, diff --git a/src/lib.rs b/src/lib.rs index 6638a4a..255dc50 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -17,6 +17,9 @@ #![allow(non_snake_case)] #![warn(missing_docs)] +#[cfg(not(target_os = "linux"))] +compile_error!("Libnotify-rs only supports linux"); + /// Basic libnotify rust wrapper pub mod api; /// Higher level abstraction over api diff --git a/src/wrappers/builder.rs b/src/wrappers/builder.rs index b5e5fda..d5e9421 100644 --- a/src/wrappers/builder.rs +++ b/src/wrappers/builder.rs @@ -15,6 +15,10 @@ pub struct NotificationBuilder<'a> { impl<'a> NotificationBuilder<'a> { /// Create new NotificationBuilder, with given context. + /// + /// # Errors + /// + /// This function can return LibnotifyError::{NewNotificationError, NulError} pub fn new( summary: &str, body: T, @@ -34,6 +38,9 @@ impl<'a> NotificationBuilder<'a> { } /// Sets app name for this specific notification. + /// + /// # Errors + /// This function can return LibnotifyError::{NulError} pub fn set_app_name>>( mut self, app_name: T, @@ -46,6 +53,9 @@ impl<'a> NotificationBuilder<'a> { } /// Sets app icon fot this specific notification. + /// + /// # Errors + /// This function can return LibnotifyError::{NulError} pub fn set_app_icon>>( mut self, app_icon: T, @@ -58,6 +68,9 @@ impl<'a> NotificationBuilder<'a> { } /// Sets category for this specific notification + /// + /// # Errors + /// This function can return LibnotifyError::{NulError} pub fn set_category>>( mut self, category: T, @@ -70,6 +83,8 @@ impl<'a> NotificationBuilder<'a> { } /// Set hint for this specific notification + /// # Errors + /// This function can return LibnotifyError::{NulError, AllocationError} pub fn set_hint(mut self, key: &str, value: HintValue) -> Result { self.notification.set_hint(key, value)?; Ok(self) @@ -94,12 +109,15 @@ impl<'a> NotificationBuilder<'a> { } /// Add callback + /// + /// # Errors + /// This function can return LibnotifyError::NulError pub fn add_action( mut self, action: &str, label: &str, callback: F, - ) -> Result> + ) -> Result where F: Fn(&str) + 'static, { @@ -110,13 +128,21 @@ impl<'a> NotificationBuilder<'a> { /// Show notification /// /// Uses `&self` borrow, so you can use this object later, after showing. - pub fn show(&self) -> Result<(), Box> { + /// + /// # Errors + /// This function can return LibnotifyError::{GerrorError, AllocationError} + pub fn show(&self) -> Result<(), LibnotifyError> { self.notification.show()?; Ok(()) } /// Close notification synchronously. - pub fn close(&self) -> Result<(), Box> { + /// + /// Uses `&self` borrow, so you can use this object later, after closing. + /// + /// # Errors + /// This function can return LibnotifyError::{GerrorError, AllocationError} + pub fn close(&self) -> Result<(), LibnotifyError> { self.notification.close()?; Ok(()) }