Add convenience method to context for showing a notification

Renaming of glib packages

.travis.yml

@@ -0,0 +1,20 @@
+language: rust
+rust:
+- nightly
+- beta
+- stable
+before_script:
+- |
+  pip install 'travis-cargo<0.2' --user &&
+  export PATH=$HOME/.local/bin:$PATH
+script:
+- |
+  travis-cargo build &&
+  travis-cargo test &&
+  travis-cargo --only stable doc
+after_success:
+- travis-cargo --only stable doc-upload
+env:
+  global:
+  - TRAVIS_CARGO_NIGHTLY_FEATURE=""
+  - secure: IjahTjjwmuvig/wTDMwxpk1F3Ywi2d0r17+JmOXHPdbfSfhi4puiTzsOgMjBhFtosTwcvlBeFwwFeTtl9KFNG165xm9Fqbhcez9sx+hS+EWZR/MBPFhKorJlgva0nuH8L1cxDUP+mDkcV/BdXCDeT7ml+y/FqEDAI4N0lwEsVMk=

Cargo.toml

@@ -1,7 +1,7 @@
 [package]
 
 name = "libnotify"
-version = "0.0.2"
+version = "0.2.0"
 authors = ["Mika Attila <radiantstatue@gmail.com>"]
 license = "MIT"
 description = "Rust bindings to libnotify"
@@ -11,5 +11,6 @@ documentation = "http://crumblingstatue.github.io/doc/libnotify/libnotify/"
 keywords = ["libnotify", "notification"]
 
 [dependencies]
-libnotify-sys = "*"
+libnotify-sys = "0.2.0"
-glib-2_0-sys = "*"
+glib-2-0-sys = "0.46.0"
+gtypes = "0.1.2"

README.md

@@ -1,2 +1,4 @@
+[![Build Status](https://travis-ci.org/crumblingstatue/rust-libnotify.svg)](https://travis-ci.org/crumblingstatue/rust-libnotify)
+
 # libnotify-rs
 Rust binding to libnotify

examples/show.rs

@@ -1,9 +1,11 @@
 extern crate libnotify;
 
 fn main() {
-    let notify = libnotify::Context::new("hello").unwrap();
+    // Create a libnotify context
-    let n = notify.new_notification("This is the summary.",
+    let notify = libnotify::Context::new("myapp").unwrap();
-                                    Some("This is the optional body text."),
+    // Create a new notification and show it
-                                    None).unwrap();
+    let n = notify.new_notification("Summary", Some("Optional Body"), None).unwrap();
     n.show().unwrap();
+    // You can also use the .show() convenience method on the context
+    notify.show("I am another notification", None, None).unwrap();
 }

src/lib.rs

@@ -1,27 +1,92 @@
-extern crate "libnotify-sys" as sys;
+//! Rustic bindings to [libnotify](https://developer.gnome.org/libnotify/)
-extern crate "glib-2_0-sys" as glib;
+//!
+//! ```rust
+//! extern crate libnotify;
+//!
+//! fn main() {
+//!     // Create a libnotify context
+//!     let notify = libnotify::Context::new("myapp").unwrap();
+//!     // Create a new notification and show it
+//!     let n = notify.new_notification("Summary",
+//!                                     Some("Optional Body"),
+//!                                     None).unwrap();
+//!     n.show().unwrap();
+//!     // You can also use the .show() convenience method on the context
+//!     notify.show("I am another notification", None, None).unwrap();
+//! }
+//!
+//! ```
 
-use std::ffi::CString;
+#![warn(missing_docs)]
+
+extern crate libnotify_sys as sys;
+extern crate glib_2_0_sys as glib;
+extern crate gtypes;
+
+use std::ffi::{self, CStr, CString};
 use std::marker::PhantomData;
+use std::fmt;
+use std::error::Error;
 
-use glib::types::{
+use gtypes::{TRUE, FALSE};
-    TRUE,
-    FALSE
-};
 
 /// Error that can happen on context creation
 #[derive(Debug)]
 pub enum ContextCreationError {
-    /// Context already exists
+    /// Context already exists.
     AlreadyExists,
-    InitFailure,
+    /// Failed to initialize libnotify.
-    NulError
+    InitError,
+    /// A nul byte was found in the provided string.
+    NulError(ffi::NulError),
+}
+
+impl fmt::Display for ContextCreationError {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        use ContextCreationError::*;
+        match *self {
+            AlreadyExists => write!(f, "A Libnotify context already exists."),
+            InitError => write!(f, "Failed to initialize libnotify."),
+            NulError(ref e) => write!(f, "{}", e),
+        }
+    }
+}
+
+impl From<ffi::NulError> for ContextCreationError {
+    fn from(src: ffi::NulError) -> Self {
+        ContextCreationError::NulError(src)
+    }
 }
 
 #[derive(Debug)]
+/// An error that can happen when attempting to create a notification.
 pub enum NotificationCreationError {
-    NulError,
+    /// A nul byte was found in the provided string.
-    Unknown
+    NulError(ffi::NulError),
+    /// An unknown error happened.
+    Unknown,
+}
+
+impl fmt::Display for NotificationCreationError {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        use NotificationCreationError::*;
+        match *self {
+            NulError(ref e) => write!(f, "{}", e),
+            Unknown => write!(f, "Unknown error"),
+        }
+    }
+}
+
+impl From<ffi::NulError> for NotificationCreationError {
+    fn from(src: ffi::NulError) -> Self {
+        NotificationCreationError::NulError(src)
+    }
+}
+
+impl Error for NotificationCreationError {
+    fn description(&self) -> &str {
+        "notification creation error"
+    }
 }
 
 /// The context which within libnotify operates.
@@ -40,12 +105,9 @@ impl Context {
             if sys::notify_is_initted() == TRUE {
                 return Err(ContextCreationError::AlreadyExists);
             }
-            let app_name = match CString::new(app_name) {
+            let app_name = try!(CString::new(app_name));
-                Ok(name) => name,
-                Err(_) => return Err(ContextCreationError::NulError)
-            };
             if sys::notify_init(app_name.as_ptr()) == FALSE {
-                return Err(ContextCreationError::InitFailure);
+                return Err(ContextCreationError::InitError);
             }
         }
         Ok(Context)
@@ -57,47 +119,53 @@ impl Context {
     /// - summary: Required summary text
     /// - body: Optional body text
     /// - icon: Optional icon theme icon name or filename
-    pub fn new_notification(&self, summary: &str,
+    pub fn new_notification(&self,
-                                   body: Option<&str>,
+                            summary: &str,
-                                   icon: Option<&str>)
+                            body: Option<&str>,
-        -> Result<Notification, NotificationCreationError> {
+                            icon: Option<&str>)
-        let summary = match CString::new(summary) {
+                            -> Result<Notification, NotificationCreationError> {
-            Ok(cstr) => cstr,
+        let summary = try!(CString::new(summary));
-            Err(_) => return Err(NotificationCreationError::NulError)
-        };
         let body = match body {
-            Some(body) => match CString::new(body) {
+            Some(body) => Some(try!(CString::new(body))),
-                Ok(cstr) => Some(cstr),
+            None => None,
-                Err(_) => return Err(NotificationCreationError::NulError)
-            },
-            None => None
         };
         let body_ptr = match body {
             Some(body) => body.as_ptr(),
-            None => std::ptr::null()
+            None => std::ptr::null(),
         };
         let icon = match icon {
-            Some(icon) => match CString::new(icon) {
+            Some(icon) => Some(try!(CString::new(icon))),
-                Ok(cstr) => Some(cstr),
+            None => None,
-                Err(_) => return Err(NotificationCreationError::NulError)
-            },
-            None => None
         };
         let icon_ptr = match icon {
             Some(icon) => icon.as_ptr(),
-            None => std::ptr::null()
+            None => std::ptr::null(),
         };
         unsafe {
-            let n = sys::notify_notification_new(summary.as_ptr(),
+            let n = sys::notify_notification_new(summary.as_ptr(), body_ptr, icon_ptr);
-                                                 body_ptr,
-                                                 icon_ptr);
             if n.is_null() {
                 return Err(NotificationCreationError::Unknown);
             }
 
-            Ok(Notification{handle: n, _phantom: PhantomData})
+            Ok(Notification {
+                handle: n,
+                _phantom: PhantomData,
+            })
         }
     }
+    /// Show a notification.
+    ///
+    /// This is a convenience method that creates a new notification,
+    /// and shows it in one step.
+    pub fn show(&self,
+                summary: &str,
+                body: Option<&str>,
+                icon: Option<&str>)
+                -> Result<(), Box<Error>> {
+        let notif = try!(self.new_notification(summary, body, icon));
+        try!(notif.show());
+        Ok(())
+    }
 }
 
 impl Drop for Context {
@@ -111,21 +179,42 @@ impl Drop for Context {
 /// A passive pop-up notification
 pub struct Notification<'a> {
     handle: *mut sys::NotifyNotification,
-    _phantom: PhantomData<&'a Context>
+    _phantom: PhantomData<&'a Context>,
 }
 
 impl<'a> Notification<'a> {
     /// Tells the notification server to display the notification
     /// on the screen.
-    pub fn show(&'a self) -> Result<(), ()> {
+    pub fn show(&'a self) -> Result<(), NotificationShowError> {
         unsafe {
             let mut err: *mut glib::GError = std::ptr::null_mut();
             sys::notify_notification_show(self.handle, &mut err);
             if !err.is_null() {
+                let result = Err(NotificationShowError {
+                    message: CStr::from_ptr((*err).message).to_string_lossy().into_owned(),
+                });
                 glib::g_error_free(err);
-                return Err(())
+                return result;
             }
-            return Ok(())
+            Ok(())
         }
     }
 }
+
+/// An error that can happen when attempting to show a notification.
+#[derive(Debug)]
+pub struct NotificationShowError {
+    message: String,
+}
+
+impl fmt::Display for NotificationShowError {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        write!(f, "Error showing notification: {}", self.message)
+    }
+}
+
+impl Error for NotificationShowError {
+    fn description(&self) -> &str {
+        "notification show error"
+    }
+}