Add "preview properties" functions

Fixes #3

examples/preview_properties.rs

@@ -0,0 +1,49 @@
+//! Example of how to access preview image properties
+//!
+//! To run it, edit in a filename below, and try:
+//!   $ cargo run --example preview_properties.rs
+
+extern crate gexiv2_sys as gexiv2;
+extern crate libc;
+
+use std::ffi;
+use std::ptr;
+
+
+static FILE_PATH: &'static str = "/YOUR/FILE/PATH/GOES/HERE.jpg";
+
+
+fn get_file_metadata(path: &str) -> *mut gexiv2::GExiv2Metadata {
+    let mut err: *mut gexiv2::GError = ptr::null_mut();
+    let c_str_path = ffi::CString::new(path.as_bytes()).unwrap();
+    unsafe {
+        let metadata = gexiv2::gexiv2_metadata_new();
+        let ok = gexiv2::gexiv2_metadata_open_path(metadata, c_str_path.as_ptr(), &mut err);
+        if ok != 1 {
+            panic!("Couldn't open image at the given path ({:})", FILE_PATH);
+        }
+        metadata
+    }
+}
+
+
+fn main() {
+    unsafe {
+        let meta = get_file_metadata(FILE_PATH);
+        let all_preview_props = gexiv2::gexiv2_metadata_get_preview_properties(meta);
+
+        if all_preview_props.is_null() {
+            panic!("The given media file has no embedded preview images");
+        }
+
+        let mut cur_offset = 0;
+        while !(*all_preview_props.offset(cur_offset)).is_null() {
+            let preview_prop = *all_preview_props.offset(cur_offset);
+            let mime_type = ffi::CStr::from_ptr(
+                gexiv2::gexiv2_preview_properties_get_mime_type(preview_prop)
+            ).to_str();
+            println!("{:?}", mime_type);
+            cur_offset += 1;
+        }
+    }
+}

src/lib.rs

@@ -26,13 +26,19 @@
 
 extern crate libc;
 
-use self::libc::{c_char, c_double, c_int, c_long};
+use self::libc::{c_char, c_double, c_int, c_long, c_uint};
 
 /// An opaque structure that serves as a container for a media file's metadata.
 ///
 /// You can only create one via [`gexiv2_metadata_new()`](fn.gexiv2_metadata_new.html).
 pub enum GExiv2Metadata {}
 
+/// An opaque container structure for information about a media file preview image.
+///
+/// You can only get hold of one (or, rather, a null-terminated array of them) via
+/// [`gexiv2_metadata_get_preview_properties()`](fn.gexiv2_metadata_get_preview_properties.html).
+pub enum GExiv2PreviewProperties {}
+
 /// Container for information about recoverable runtime errors.
 #[repr(C)]
 #[derive(Clone, Copy, Debug, Eq, PartialEq)]
@@ -163,6 +169,14 @@ extern {
     pub fn gexiv2_metadata_set_exif_thumbnail_from_buffer(this: *mut GExiv2Metadata, buffer: *const u8, size: c_int);
     pub fn gexiv2_metadata_erase_exif_thumbnail(this: *mut GExiv2Metadata);
 
+    // Preview image properties.
+    pub fn gexiv2_metadata_get_preview_properties(this: *mut GExiv2Metadata) -> *mut *mut GExiv2PreviewProperties;
+    pub fn gexiv2_preview_properties_get_mime_type(this: *mut GExiv2PreviewProperties) -> *const c_char;
+    pub fn gexiv2_preview_properties_get_extension(this: *mut GExiv2PreviewProperties) -> *const c_char;
+    pub fn gexiv2_preview_properties_get_size(this: *mut GExiv2PreviewProperties) -> c_uint;
+    pub fn gexiv2_preview_properties_get_width(this: *mut GExiv2PreviewProperties) -> c_uint;
+    pub fn gexiv2_preview_properties_get_height(this: *mut GExiv2PreviewProperties) -> c_uint;
+
     // XMP namespace management.
     pub fn gexiv2_metadata_register_xmp_namespace(name: *const c_char, prefix: *const c_char) -> c_int;
     pub fn gexiv2_metadata_unregister_xmp_namespace(name: *const c_char) -> c_int;