[gexiv2] Add and update the GI annotations/documentation
- From: Jim Nelson <jnelson src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gexiv2] Add and update the GI annotations/documentation
- Date: Sat, 18 Jan 2014 00:00:12 +0000 (UTC)
commit bc90c1c79983d4cdb6dc4e076a83248d6de5d044
Author: Jim Nelson <jim yorba org>
Date: Fri Jan 17 15:58:45 2014 -0800
Add and update the GI annotations/documentation
Too many gexiv2 calls have been undocumented for too long, so
went through and documented all of them. Hopefully this will
assist with building gir (bug #712454) and documentation (bug #712462)
gexiv2/gexiv2-log.h | 54 ++++
gexiv2/gexiv2-metadata.h | 490 ++++++++++++++++++++++++++++++------
gexiv2/gexiv2-preview-image.h | 37 +++
gexiv2/gexiv2-preview-properties.h | 29 +++
gexiv2/gexiv2-startup.h | 10 +
gexiv2/gexiv2-version.m4 | 13 +
6 files changed, 552 insertions(+), 81 deletions(-)
---
diff --git a/gexiv2/gexiv2-log.h b/gexiv2/gexiv2-log.h
index 65f6cff..383a9a8 100644
--- a/gexiv2/gexiv2-log.h
+++ b/gexiv2/gexiv2-log.h
@@ -22,13 +22,67 @@ typedef enum {
GEXIV2_LOG_LEVEL_MUTE = 4
} GExiv2LogLevel;
+/**
+ * GExiv2LogHandler:
+ * @level: The #Gexiv2LogLevel for the particular message
+ * @msg: (in): The log message
+ *
+ * The log handler can be set by #gexiv2_log_set_handler. When set, the log handler will receive
+ * all log messages emitted by Exiv2 and gexiv2. It's up to the handler to decide where (and if)
+ * the images are displayed or stored.
+ */
typedef void (*GExiv2LogHandler)(GExiv2LogLevel level, const gchar *msg);
+/**
+ * gexiv2_log_get_level:
+ *
+ * Returns: The current #GExiv2LogLevel. Messages below this level will not be logged.
+ */
GExiv2LogLevel gexiv2_log_get_level(void);
+
+/**
+ * gexiv2_log_set_level:
+ * @level: The #GExiv2LogLevel gexiv2 should respect.
+ *
+ * Log messages below this level will not be logged.
+ */
void gexiv2_log_set_level(GExiv2LogLevel level);
+
+/**
+ * gexiv2_log_get_handler
+ *
+ * Returns: The current #GExiv2LogHandler, or the default if none set. See
+ * #gexiv2_log_get_default_handler.
+ */
GExiv2LogHandler gexiv2_log_get_handler(void);
+
+/**
+ * gexiv2_log_get_default_handler
+ *
+ * Returns: The default #GExiv2LogHandler, which uses Exiv2's built-in handler. Exiv2 will send the
+ * message to stderr.
+ */
GExiv2LogHandler gexiv2_log_get_default_handler(void);
+
+/**
+ * gexiv2_log_set_handler:
+ * @handler: A #GExiv2LogHandler callback to begin receiving log messages from Exiv2 and gexiv2
+ *
+ * This method is not thread-safe. It's best to set this before beginning to use gexiv2.
+ */
void gexiv2_log_set_handler(GExiv2LogHandler handler);
+
+/**
+ * gexiv2_log_use_glib_logging:
+ *
+ * When called, gexiv2 will install it's own #GExiv2LogHandler which redirects all Exiv2 and gexiv2
+ * log messages to GLib's logging calls (g_debug, g_message, g_warning, and g_critical for the
+ * respective #GExiv2LogLevel value). #GEXIV2_LOG_LEVEL_MUTE logs are dropped.
+ *
+ * One advantage to using this is that GLib's logging control and handlers can be used rather than
+ * gexiv2's ad hoc scheme. It also means an application can use GLib logging and have all its
+ * messages routed through the same calls.
+ */
void gexiv2_log_use_glib_logging(void);
G_END_DECLS
diff --git a/gexiv2/gexiv2-metadata.h b/gexiv2/gexiv2-metadata.h
index cf46e04..612cf31 100644
--- a/gexiv2/gexiv2-metadata.h
+++ b/gexiv2/gexiv2-metadata.h
@@ -41,6 +41,15 @@ G_BEGIN_DECLS
(G_TYPE_INSTANCE_GET_PRIVATE ((obj), GEXIV2_TYPE_METADATA, GExiv2MetadataPrivate))
+/**
+ * Gexiv2Orientation:
+ *
+ * The orientation of an image is defined as the location of it's x,y origin. More than rotation,
+ * orientation allows for every variation of rotation, flips, and mirroring to be described in
+ * 3 bits of data.
+ *
+ * A handy primer to Orientation can be found at http://jpegclub.org/exif_orientation.html
+ */
typedef enum {
GEXIV2_ORIENTATION_MIN = 0,
GEXIV2_ORIENTATION_UNSPECIFIED = 0,
@@ -60,6 +69,22 @@ typedef struct _GExiv2Metadata GExiv2Metadata;
typedef struct _GExiv2MetadataClass GExiv2MetadataClass;
typedef struct _GExiv2MetadataPrivate GExiv2MetadataPrivate;
+/**
+ * GExiv2Metadata:
+ *
+ * An object holding all the Exiv2 metadata. Previews, if present, are also available.
+ *
+ * As gexiv2 is only a wrapper around Exiv2, it's better to read its documentaiton to understand
+ * the full scope of what it offers: http://www.exiv2.org/
+ *
+ * In particular, rather than providing a getter/setter method pair for every metadata value
+ * available for images (of which there are thousands), Exiv2 uses a dotted addressing scheme.
+ * For example, to access a photo's EXIF Orientation field, the caller passes to Exiv2
+ * "Exif.Photo.Orientation". These <em>tags</em> (in Exiv2 parlance) are key to using Exiv2 (and
+ * therefore gexiv2) to its fullest.
+ *
+ * A full reference for all supported Exiv2 tags can be found at http://www.exiv2.org/metadata.html
+ */
struct _GExiv2Metadata
{
GObject parent_instance;
@@ -83,12 +108,20 @@ GType gexiv2_metadata_get_type (void);
* Returns: (transfer full): A fully constructed #GExiv2Metadata ready to be used
*/
GExiv2Metadata* gexiv2_metadata_new (void);
+
+/**
+ * gexiv2_metadata_free:
+ *
+ * Destroys the #GExiv2Metadata object and frees all associated memory.
+ */
void gexiv2_metadata_free (GExiv2Metadata *self);
/**
* gexiv2_metadata_open_path:
* @path: Path to the file you want to open
*
+ * The file must be an image format supported by Exiv2.
+ *
* Returns: Boolean success indicator
*/
gboolean gexiv2_metadata_open_path (GExiv2Metadata *self, const gchar
*path, GError **error);
@@ -98,161 +131,292 @@ gboolean gexiv2_metadata_open_path (GExiv2Metadata
*self, const gchar *path,
* @data: (array length=n_data): A buffer containing the data to be read
* @n_data: (skip): The length of the buffer
*
+ * The buffer must be an image format supported by Exiv2.
+ *
* Returns: Boolean success indicator
*/
gboolean gexiv2_metadata_open_buf (GExiv2Metadata *self, const guint8
*data, glong n_data, GError **error);
+/**
+ * gexiv2_metadata_open_stream:
+ * @cb: A #ManagedStreamCallbacks struct offering stream access.
+ *
+ * The stream must be an image format supported by Exiv2.
+ *
+ * Returns: Boolean success indicator
+ */
gboolean gexiv2_metadata_open_stream (GExiv2Metadata *self,
ManagedStreamCallbacks* cb, GError **error);
+/**
+ * gexiv2_metadata_from_app1_segment:
+ * @data: (array length=n_data): A buffer containing the data to be read
+ * @n_data: (skip): The length of the buffer
+ *
+ * Load only an EXIF buffer, typically stored in a JPEG's APP1 segment.
+ *
+ * Returns: Boolean success indicator.
+ */
gboolean gexiv2_metadata_from_app1_segment (GExiv2Metadata *self, const guint8 *data,
glong n_data, GError **error);
+/**
+ * gexiv2_metadata_save_file:
+ * @path: Path to the file you want to save to.
+ *
+ * Saves the metadata to the specified file by reading the file into memory,copying this object's
+ * metadata into the image, then writing the image back out.
+ *
+ * Returns: Boolean success indicator.
+ */
gboolean gexiv2_metadata_save_file (GExiv2Metadata *self, const gchar
*path, GError **error);
+/**
+ * gexiv2_metadata_save_stream:
+ * @cb: A #ManagedStreamCallbacks struct offering stream access.
+ *
+ * Saves the metadata to the stream by reading the stream into memory,copying this object's
+ * metadata into the image, then writing the image as a stream back out.
+ *
+ * Returns: Boolean success indicator.
+ */
gboolean gexiv2_metadata_save_stream (GExiv2Metadata *self,
ManagedStreamCallbacks* cb, GError **error);
+/**
+ * gexiv2_metadata_has_tag:
+ * @tag: Exiv2 tag
+ *
+ * The Exiv2 Tag Reference can be found at http://exiv2.org/metadata.html
+ *
+ * Returns: TRUE if the tag is present.
+ */
gboolean gexiv2_metadata_has_tag (GExiv2Metadata *self, const gchar*
tag);
+
+/**
+ * gexiv2_metadata_clear_tag:
+ * @tag: Exiv2 tag
+ *
+ * Removes the Exiv2 tag from the metadata object.
+ *
+ * The Exiv2 Tag Reference can be found at http://exiv2.org/metadata.html
+ *
+ * Returns: TRUE if the tag was present.
+ */
gboolean gexiv2_metadata_clear_tag (GExiv2Metadata *self, const gchar*
tag);
-void gexiv2_metadata_clear (GExiv2Metadata *self);
-const gchar* gexiv2_metadata_get_mime_type (GExiv2Metadata *self);
+/**
+ * gexiv2_metadata_clear:
+ *
+ * Removes all tags for all domains (EXIF, IPTC, and XMP).
+ */
+void gexiv2_metadata_clear (GExiv2Metadata *self);
-gboolean gexiv2_metadata_get_supports_exif (GExiv2Metadata *self);
-gboolean gexiv2_metadata_get_supports_xmp (GExiv2Metadata *self);
-gboolean gexiv2_metadata_get_supports_iptc (GExiv2Metadata *self);
+/**
+ * gexiv2_metadata_is_exif_tag:
+ * @tag: An Exiv2 tag
+ *
+ * The Exiv2 Tag Reference can be found at http://exiv2.org/metadata.html
+ *
+ * Returns: TRUE if the Exiv2 tag is for the EXIF domain.
+ */
+gboolean gexiv2_metadata_is_exif_tag (const gchar* tag);
-GExiv2Orientation gexiv2_metadata_get_orientation (GExiv2Metadata *self);
-void gexiv2_metadata_set_orientation (GExiv2Metadata *self, GExiv2Orientation
orientation);
+/**
+ * gexiv2_metadata_is_iptc_tag:
+ * @tag: An Exiv2 tag
+ *
+ * The Exiv2 Tag Reference can be found at http://exiv2.org/metadata.html
+ *
+ * Returns: TRUE if the Exiv2 tag is for the IPTC domain.
+ */
+gboolean gexiv2_metadata_is_iptc_tag (const gchar* tag);
-gint gexiv2_metadata_get_pixel_width (GExiv2Metadata *self);
-gint gexiv2_metadata_get_pixel_height (GExiv2Metadata *self);
+/**
+ * gexiv2_metadata_is_xmp_tag:
+ * @tag: An Exiv2 tag
+ *
+ * The Exiv2 Tag Reference can be found at http://exiv2.org/metadata.html
+ *
+ * Returns: TRUE if the Exiv2 tag is for the XMP domain.
+ */
+gboolean gexiv2_metadata_is_xmp_tag (const gchar* tag);
/**
- * gexiv2_metadata_get_comment:
+ * gexiv2_metadata_get_tag_label:
+ * @tag: An Exiv2 tag
+ *
+ * The Exiv2 Tag Reference can be found at http://exiv2.org/metadata.html
*
- * Returns: (transfer full) (allow-none): The photo's comment
+ * Returns: (transfer none) (allow-none): The tag's label
*/
-gchar* gexiv2_metadata_get_comment (GExiv2Metadata *self);
-void gexiv2_metadata_set_comment (GExiv2Metadata *self, const gchar*
comment);
-void gexiv2_metadata_clear_comment (GExiv2Metadata *self);
+const gchar* gexiv2_metadata_get_tag_label (const gchar *tag);
/**
- * gexiv2_metadata_get_tag_string:
- * @tag: The name of the tag who's value you want
+ * gexiv2_metadata_get_tag_description:
+ * @tag: An Exiv2 tag
*
- * Returns: (transfer full) (allow-none): The tag's value as a string
+ * The Exiv2 Tag Reference can be found at http://exiv2.org/metadata.html
+ *
+ * Returns: (transfer none) (allow-none): The tag's description
*/
-gchar* gexiv2_metadata_get_tag_string (GExiv2Metadata *self, const gchar* tag);
+const gchar* gexiv2_metadata_get_tag_description (const gchar *tag);
/**
- * gexiv2_metadata_get_tag_interpreted_string:
- * @tag: The name of the tag who's value you want
+ * gexiv2_metadata_get_tag_type:
+ * @tag: An Exiv2 tag
*
- * Returns: (transfer full) (allow-none): The tag's interpreted value as a string
+ * The names of the various Exiv2 tag types can be found at Exiv2::TypeId,
+ * http://exiv2.org/doc/namespaceExiv2.html#5153319711f35fe81cbc13f4b852450c
+ *
+ * The Exiv2 Tag Reference can be found at http://exiv2.org/metadata.html
+ *
+ * Returns: (transfer none) (allow-none): The tag's type name.
*/
-gchar* gexiv2_metadata_get_tag_interpreted_string (GExiv2Metadata *self, const gchar* tag);
-gboolean gexiv2_metadata_set_tag_string (GExiv2Metadata *self, const gchar* tag,
const gchar* value);
+const gchar* gexiv2_metadata_get_tag_type (const gchar *tag);
-glong gexiv2_metadata_get_tag_long (GExiv2Metadata *self, const gchar* tag);
-gboolean gexiv2_metadata_set_tag_long (GExiv2Metadata *self, const gchar* tag,
glong value);
+/**
+ * gexiv2_metadata_get_supports_exif:
+ *
+ * Returns: TRUE if the loaded image type supports writing EXIF metadata.
+ */
+gboolean gexiv2_metadata_get_supports_exif (GExiv2Metadata *self);
+/**
+ * gexiv2_metadata_get_supports_iptc:
+ *
+ * Returns: TRUE if the loaded image type supports writing IPTC metadata.
+ */
+gboolean gexiv2_metadata_get_supports_iptc (GExiv2Metadata *self);
/**
- * gexiv2_metadata_get_tag_multiple:
- * @tag: The name of the tag to get
+ * gexiv2_metadata_get_supports_xmp:
*
- * Returns: (transfer full) (allow-none) (array zero-terminated=1): The multiple values of that tag
+ * Returns: TRUE if the loaded image type supports writing XMP metadata.
*/
-gchar** gexiv2_metadata_get_tag_multiple (GExiv2Metadata *self, const gchar*
tag);
+gboolean gexiv2_metadata_get_supports_xmp (GExiv2Metadata *self);
/**
- * gexiv2_metadata_set_tag_multiple:
- * @values: (array zero-terminated=1): An array of tags that you want to set
+ * gexiv2_get_mime_type:
*
- * Returns: (transfer full): Boolean success value
+ * Returns: (transfer none): The MIME type of the loaded image, NULL if not loaded or unknown.
*/
-gboolean gexiv2_metadata_set_tag_multiple (GExiv2Metadata *self, const gchar* tag,
const gchar** values);
+const gchar* gexiv2_metadata_get_mime_type (GExiv2Metadata *self);
/**
- * gexiv2_metadata_get_exposure_time:
- * @nom: (out): The numerator
- * @den: (out): The denominator
+ * gexiv2_metadata_get_pixel_width:
*
- * Returns the exposure time in seconds (shutter speed, <em>not</em> date-time of exposure) as a
- * rational. See https://en.wikipedia.org/wiki/Shutter_speed for more information.
+ * Returns: The <em>actual</em> unoriented display width in pixels of the loaded image. This may be
+ * different than the width reported by various metadata tags, i.e. "Exif.Photo.PixelXDimension".
+ */
+gint gexiv2_metadata_get_pixel_width (GExiv2Metadata *self);
+
+/**
+ * gexiv2_metadata_get_pixel_height:
*
- * Returns: (skip): Boolean success value
+ * Returns: The <em>actual</em> unoriented display height in pixels of the loaded image. This may
+ * be different than the height reported by various metadata tags, i.e. "Exif.Photo.PixelYDimension".
*/
-gboolean gexiv2_metadata_get_exposure_time (GExiv2Metadata *self, gint *nom, gint *den);
+gint gexiv2_metadata_get_pixel_height (GExiv2Metadata *self);
/**
- * gexiv2_metadata_get_fnumber:
+ * gexiv2_metadata_get_tag_string:
+ * @tag: Exiv2 tag name
*
- * See https://en.wikipedia.org/wiki/F-number for more information.
+ * The Exiv2 Tag Reference can be found at http://exiv2.org/metadata.html
*
- * Returns: The exposure Fnumber as a gdouble, or -1.0 if tag is not present or invalid.
+ * Returns: (transfer full) (allow-none): The tag's value as a string
*/
-gdouble gexiv2_metadata_get_fnumber (GExiv2Metadata *self);
+gchar* gexiv2_metadata_get_tag_string (GExiv2Metadata *self, const gchar* tag);
/**
- * gexiv2_metadata_get_focal_length:
+ * gexiv2_metadata_set_tag_string:
+ * @tag: Exiv2 tag name
+ * @value: The value to set or replace the existing value
*
- * See https://en.wikipedia.org/wiki/Flange_focal_distance for more information.
+ * The Exiv2 Tag Reference can be found at http://exiv2.org/metadata.html
*
- * Returns: The focal length as a gdouble, or -1.0 if tag is not present or invalid.
+ * Returns: TRUE on success
*/
-gdouble gexiv2_metadata_get_focal_length (GExiv2Metadata *self);
+gboolean gexiv2_metadata_set_tag_string (GExiv2Metadata *self, const gchar* tag,
const gchar* value);
/**
- * gexiv2_metadata_get_iso_speed:
+ * gexiv2_metadata_get_tag_interpreted_string:
+ * @tag: Exiv2 tag name
*
- * See https://en.wikipedia.org/wiki/Iso_speed for more information.
+ * An interpreted string is one fit for user display. It may display units or use formatting
+ * appropriate to the type of data the tag holds.
*
- * Returns: The ISO speed rating as a gint, or 0 if tag is not present or invalid.
+ * The Exiv2 Tag Reference can be found at http://exiv2.org/metadata.html
+ *
+ * Returns: (transfer full) (allow-none): The tag's interpreted value as a string
*/
-gint gexiv2_metadata_get_iso_speed (GExiv2Metadata *self);
-
-/* static functions */
-
-gboolean gexiv2_metadata_is_xmp_tag (const gchar* tag);
-gboolean gexiv2_metadata_is_exif_tag (const gchar* tag);
-gboolean gexiv2_metadata_is_iptc_tag (const gchar* tag);
+gchar* gexiv2_metadata_get_tag_interpreted_string (GExiv2Metadata *self, const gchar* tag);
/**
- * gexiv2_metadata_get_tag_label:
- * @tag: Name of the tag who's label you want
+ * gexiv2_metadata_get_tag_long:
+ * @tag: Exiv2 tag name
*
- * Returns: (transfer none) (allow-none): The tag's label
+ * The Exiv2 Tag Reference can be found at http://exiv2.org/metadata.html
+ *
+ * Returns: The tag's value as a glong
*/
-const gchar* gexiv2_metadata_get_tag_label (const gchar *tag);
+glong gexiv2_metadata_get_tag_long (GExiv2Metadata *self, const gchar* tag);
/**
- * gexiv2_metadata_get_tag_description:
- * @tag: Name of the tag who's label you want
+ * gexiv2_metadata_set_tag_long:
+ * @tag: Exiv2 tag name
+ * @value: The value to set or replace the existing value
*
- * Returns: (transfer none) (allow-none): The tag's description
+ * The Exiv2 Tag Reference can be found at http://exiv2.org/metadata.html
+ *
+ * Returns: TRUE on success
*/
-const gchar* gexiv2_metadata_get_tag_description (const gchar *tag);
+gboolean gexiv2_metadata_set_tag_long (GExiv2Metadata *self, const gchar* tag,
glong value);
+
/**
- * gexiv2_metadata_get_tag_type:
- * @tag: Name of the tag who's type you want
+ * gexiv2_metadata_get_tag_multiple:
+ * @tag: Exiv2 tag name
*
- * Returns: (transfer none) (allow-none): The tag's type
+ * The Exiv2 Tag Reference can be found at http://exiv2.org/metadata.html
+ *
+ * Returns: (transfer full) (allow-none) (array zero-terminated=1): The multiple string values of
+ * the tag
*/
-const gchar* gexiv2_metadata_get_tag_type (const gchar *tag);
+gchar** gexiv2_metadata_get_tag_multiple (GExiv2Metadata *self, const gchar*
tag);
+/**
+ * gexiv2_metadata_set_tag_multiple:
+ * @tag: Exiv2 tag name
+ * @values: (array zero-terminated=1): An array of values to set or replace the existing value(s)
+ *
+ * The Exiv2 Tag Reference can be found at http://exiv2.org/metadata.html
+ *
+ * Returns: (transfer full): Boolean success value
+ */
+gboolean gexiv2_metadata_set_tag_multiple (GExiv2Metadata *self, const gchar* tag,
const gchar** values);
/**
* EXIF functions
*/
+/**
+ * gexiv2_metadata_has_exif:
+ *
+ * Returns: TRUE if EXIF metadata is present in the loaded image
+ */
gboolean gexiv2_metadata_has_exif (GExiv2Metadata *self);
+
+/**
+ * gexiv2_metadata_clear_exif:
+ *
+ * Clears all EXIF metadata from the loaded image.
+ */
void gexiv2_metadata_clear_exif (GExiv2Metadata *self);
/**
* gexiv2_metadata_get_exif_tags:
*
- * Returns: (transfer full) (array zero-terminated=1): A list of the available EXIF tags
+ * Returns: (transfer full) (array zero-terminated=1): A list of the available EXIF tags in the
+ * loaded image
*/
gchar** gexiv2_metadata_get_exif_tags (GExiv2Metadata *self);
@@ -265,6 +429,15 @@ gchar** gexiv2_metadata_get_exif_tags (GExiv2Metadata
*self);
* Returns: (skip): Boolean success value
*/
gboolean gexiv2_metadata_get_exif_tag_rational (GExiv2Metadata *self, const gchar* tag, gint*
nom, gint* den);
+
+/**
+ * gexiv2_metadata_set_exif_tag_rational:
+ * @tag: (in): The Exiv2 tag
+ * @nom: Rational numerator
+ * @den: Rational denominator
+ *
+ * Returns: (skip): Boolean success value
+ */
gboolean gexiv2_metadata_set_exif_tag_rational (GExiv2Metadata *self, const gchar* tag, gint
nom, gint den);
/**
@@ -275,6 +448,15 @@ gboolean gexiv2_metadata_set_exif_tag_rational (GExiv2Metadata *self, const gch
* Returns: (skip): Boolean success value
*/
gboolean gexiv2_metadata_get_exif_thumbnail (GExiv2Metadata *self, guint8** buffer, gint*
size);
+
+/**
+ * gexiv2_metadata_set_exif_thumbnail_from_file:
+ * @path: (in): Path of image file
+ *
+ * Sets or replaces the EXIF thumbnail with the image in the file
+ *
+ * Returns: Boolean success value
+ */
gboolean gexiv2_metadata_set_exif_thumbnail_from_file (GExiv2Metadata *self, const gchar
*path, GError **error);
/**
@@ -283,6 +465,12 @@ gboolean gexiv2_metadata_set_exif_thumbnail_from_file (GExiv2Metadata *self, co
* @size: (skip): Size of the thumbnail's buffer
*/
void gexiv2_metadata_set_exif_thumbnail_from_buffer (GExiv2Metadata *self, const guint8
*buffer, gint size);
+
+/**
+ * gexiv2_metadata_erase_exif_thumbnail:
+ *
+ * Removes the EXIF thumbnail from the loaded image.
+ */
void gexiv2_metadata_erase_exif_thumbnail (GExiv2Metadata *self);
@@ -290,7 +478,18 @@ void gexiv2_metadata_erase_exif_thumbnail (GExiv2Metadata *self);
* XMP functions
*/
+/**
+ * gexiv2_metadata_has_xmp:
+ *
+ * Returns: TRUE if XMP metadata is present in the loaded image
+ */
gboolean gexiv2_metadata_has_xmp (GExiv2Metadata *self);
+
+/**
+ * gexiv2_metadata_clear_xmp:
+ *
+ * Clears all XMP metadata from the loaded image.
+ */
void gexiv2_metadata_clear_xmp (GExiv2Metadata *self);
/**
@@ -309,8 +508,8 @@ gchar** gexiv2_metadata_get_xmp_tags (GExiv2Metadata
*self);
/**
* gexiv2_metadata_register_xmp_namespace:
- * @name: XMP URI name (should end in /)
- * @prefix: XMP namespace prefix
+ * @name: (in): XMP URI name (should end in /)
+ * @prefix: (in): XMP namespace prefix
*
* Returns: (skip): Boolean success value
*/
@@ -318,17 +517,31 @@ gboolean gexiv2_metadata_register_xmp_namespace (const gchar* name, const
/**
* gexiv2_metadata_unregister_xmp_namespace:
- * @name: XMP URI name (should end in /)
+ * @name: (in): XMP URI name (should end in /)
*
* Returns: (skip): Boolean success value
*/
gboolean gexiv2_metadata_unregister_xmp_namespace (const gchar* name);
+/**
+ * gexiv2_metadata_unregister_all_xmp_namespaces:
+ */
void gexiv2_metadata_unregister_all_xmp_namespaces (void);
/* IPTC functions */
+/**
+ * gexiv2_metadata_has_iptc:
+ *
+ * Returns: TRUE if IPTC metadata is present in the loaded image
+ */
gboolean gexiv2_metadata_has_iptc (GExiv2Metadata *self);
+
+/**
+ * gexiv2_metadata_clear_iptc:
+ *
+ * Clears all IPTC metadata from the loaded image.
+ */
void gexiv2_metadata_clear_iptc (GExiv2Metadata *self);
/**
@@ -338,12 +551,106 @@ void gexiv2_metadata_clear_iptc
(GExiv2Metadata *self);
*/
gchar** gexiv2_metadata_get_iptc_tags (GExiv2Metadata *self);
+/**
+ * Composite getters/setters and helpful functions.
+ */
/**
- * GPS functions
+ * gexiv2_metadata_get_orientation:
+ *
+ * Returns: The EXIF Orientation field.
*/
+GExiv2Orientation gexiv2_metadata_get_orientation (GExiv2Metadata *self);
-void gexiv2_metadata_delete_gps_info (GExiv2Metadata *self);
+/**
+ * gexiv2_metadata_set_orientation:
+ * @orientation: The new #Gexiv2Orientation for the image.
+ *
+ * The orientation must be valid and cannot be #GEXIV2_ORIENTATION_UNSPECIFIED.
+ */
+void gexiv2_metadata_set_orientation (GExiv2Metadata *self, GExiv2Orientation
orientation);
+
+/**
+ * gexiv2_metadata_get_comment:
+ *
+ * A composite accessor that uses the first available metadata field from a list of well-known
+ * locations to find the photo's comment (or description). These fields are:
+ *
+ * Exif.Image.ImageDescription
+ * Exif.Photo.UserComment
+ * Exif.Image.XPComment
+ * Iptc.Application2.Caption
+ *
+ * Note that Exif.Image.ImageDescription is <em>not</em> technically a description field and is
+ * described in the EXIF specification as "the title of the image". Also, it does not support
+ * two-byte character codes for encoding. However, it's still used here for legacy reasons.
+ *
+ * For fine-grained control, it's recommened to use Exiv2 tags directly rather than this method,
+ * which is more useful for quick or casual use.
+ *
+ * Returns: (transfer full) (allow-none): The photo's comment field.
+ */
+gchar* gexiv2_metadata_get_comment (GExiv2Metadata *self);
+
+/**
+ * gexiv2_metadata_set_comment:
+ * @comment: Comment string to set
+ *
+ * This is a composite setter that will set a number of fields to the supplied value. See
+ * #gexiv2_metadata_get_comment for more informtion.
+ */
+void gexiv2_metadata_set_comment (GExiv2Metadata *self, const gchar*
comment);
+
+/**
+ * gexiv2_metadata_clear_comment:
+ *
+ * This is a composite clear method that will clear a number of fields. See
+ * #gexiv2_metadata_get_comment for more informtion.
+ */
+void gexiv2_metadata_clear_comment (GExiv2Metadata *self);
+
+/**
+ * gexiv2_metadata_get_exposure_time:
+ * @nom: (out): The numerator
+ * @den: (out): The denominator
+ *
+ * Returns the exposure time in seconds (shutter speed, <em>not</em> date-time of exposure) as a
+ * rational. See https://en.wikipedia.org/wiki/Shutter_speed for more information.
+ *
+ * Returns: (skip): Boolean success value
+ */
+gboolean gexiv2_metadata_get_exposure_time (GExiv2Metadata *self, gint *nom, gint *den);
+
+/**
+ * gexiv2_metadata_get_fnumber:
+ *
+ * See https://en.wikipedia.org/wiki/F-number for more information.
+ *
+ * Returns: The exposure Fnumber as a gdouble, or -1.0 if tag is not present or invalid.
+ */
+gdouble gexiv2_metadata_get_fnumber (GExiv2Metadata *self);
+
+/**
+ * gexiv2_metadata_get_focal_length:
+ *
+ * See https://en.wikipedia.org/wiki/Flange_focal_distance for more information.
+ *
+ * Returns: The focal length as a gdouble, or -1.0 if tag is not present or invalid.
+ */
+gdouble gexiv2_metadata_get_focal_length (GExiv2Metadata *self);
+
+/**
+ * gexiv2_metadata_get_iso_speed:
+ *
+ * See https://en.wikipedia.org/wiki/Iso_speed for more information.
+ *
+ * Returns: The ISO speed rating as a gint, or 0 if tag is not present or invalid.
+ */
+gint gexiv2_metadata_get_iso_speed (GExiv2Metadata *self);
+
+/**
+ * GPS functions
+ */
/**
* gexiv2_metadata_get_gps_longitude:
@@ -371,16 +678,30 @@ gboolean gexiv2_metadata_get_gps_altitude
(GExiv2Metadata *self, gdouble *alt
/**
* gexiv2_metadata_get_gps_info:
- * @longitude: (out): Variable to store the longitude value
- * @latitude: (out): Variable to store the latitude value
- * @altitude: (out): Variable to store the altitude value
+ * @longitude: (out): Storage for longitude value
+ * @latitude: (out): Storage for latitude value
+ * @altitude: (out): Storage for altitude value
*
* Returns: (skip): Boolean success value.
*/
gboolean gexiv2_metadata_get_gps_info (GExiv2Metadata *self,
gdouble *longitude, gdouble *latitude, gdouble *altitude);
+/**
+ * gexiv2_metadata_set_gps_info:
+ * @longitude: Longitude value to set or replace current value
+ * @latitude: Latitude value to set or replace current value
+ * @altitude: Altitude value to set or replace current value
+ *
+ * Returns: (skip): Boolean success value.
+ */
gboolean gexiv2_metadata_set_gps_info (GExiv2Metadata *self,
gdouble longitude, gdouble latitude, gdouble altitude);
+/**
+ * gexiv2_metadata_delete_gps_info:
+ *
+ * Removes all GPS metadata from the loaded image
+ */
+void gexiv2_metadata_delete_gps_info (GExiv2Metadata *self);
/**
* Preview Manager
@@ -389,7 +710,13 @@ gboolean gexiv2_metadata_set_gps_info
(GExiv2Metadata *self, gdouble longitu
/**
* gexiv2_metadata_get_preview_properties:
*
- * Returns: (transfer none) (allow-none) (array zero-terminated=1): A #GExiv2PreviewProperties instance
+ * An image may have stored one or more previews, often of different qualities, sometimes of
+ * different image formats than the containing image. This call returns the properties of all
+ * previews Exiv2 finds within the loaded image. Use #gexiv2_metadata_get_preview_image to
+ * load a particular preview into memory.
+ *
+ * Returns: (transfer none) (allow-none) (array zero-terminated=1): An array of
+ * #GExiv2PreviewProperties instances, one for each preview present in the loaded image.
*/
GExiv2PreviewProperties** gexiv2_metadata_get_preview_properties (GExiv2Metadata *self);
@@ -397,7 +724,8 @@ GExiv2PreviewProperties** gexiv2_metadata_get_preview_properties (GExiv2Metadata
* gexiv2_metadata_get_preview_image:
* @props: A #GExiv2PreviewProperties instance
*
- * Returns: (transfer full): A #GExiv2PreviewImage instance
+ * Returns: (transfer full): A #GExiv2PreviewImage instance for the particular
+ * #GExiv2PreviewProperties.
*/
GExiv2PreviewImage* gexiv2_metadata_get_preview_image (GExiv2Metadata *self,
GExiv2PreviewProperties *props);
diff --git a/gexiv2/gexiv2-preview-image.h b/gexiv2/gexiv2-preview-image.h
index 0c2f70e..ff4d271 100644
--- a/gexiv2/gexiv2-preview-image.h
+++ b/gexiv2/gexiv2-preview-image.h
@@ -57,6 +57,12 @@ struct _GExiv2PreviewImageClass
/* basic functions */
GType gexiv2_preview_image_get_type (void);
+
+/**
+ * gexiv2_preview_image_free:
+ *
+ * Releases the preview image and all associated memory.
+ */
void gexiv2_preview_image_free (GExiv2PreviewImage *self);
@@ -69,10 +75,41 @@ void gexiv2_preview_image_free
(GExiv2PreviewImage *self);
* Returns: (transfer none) (array length=size): The raw image data
*/
const guint8* gexiv2_preview_image_get_data (GExiv2PreviewImage *self, guint32 *size);
+
+/**
+ * gexiv2_preview_image_get_mime_type:
+ *
+ * Returns: (transfer-none): The preview image's MIME type.
+ */
const gchar* gexiv2_preview_image_get_mime_type (GExiv2PreviewImage *self);
+
+/**
+ * gexiv2_preview_image_get_extension:
+ *
+ * Returns: (transfer-none): The preview image's recommended file extension.
+ */
const gchar* gexiv2_preview_image_get_extension (GExiv2PreviewImage *self);
+
+/**
+ * gexiv2_preview_image_get_width:
+ *
+ * Returns: The preview image's display width in pixels.
+ */
guint32 gexiv2_preview_image_get_width (GExiv2PreviewImage *self);
+
+/**
+ * gexiv2_preview_image_get_height:
+ *
+ * Returns: The preview image's display height in pixels.
+ */
guint32 gexiv2_preview_image_get_height (GExiv2PreviewImage *self);
+
+/**
+ * gexiv2_preview_image_write_file:
+ * @path: (in): The file path to write the preview image to.
+ *
+ * Returns: The number of bytes written to the file.
+ */
glong gexiv2_preview_image_write_file (GExiv2PreviewImage *self, const
gchar *path);
diff --git a/gexiv2/gexiv2-preview-properties.h b/gexiv2/gexiv2-preview-properties.h
index 85d7b7d..f3a339f 100644
--- a/gexiv2/gexiv2-preview-properties.h
+++ b/gexiv2/gexiv2-preview-properties.h
@@ -61,10 +61,39 @@ GType gexiv2_preview_properties_get_type
(void);
/* preview properties */
+/**
+ * gexiv2_preview_properties_get_mime_type:
+ *
+ * Returns: (transfer-none): The preview image's MIME type.
+ */
const gchar* gexiv2_preview_properties_get_mime_type (GExiv2PreviewProperties *self);
+
+/**
+ * gexiv2_preview_properties_get_extension:
+ *
+ * Returns: (transfer-none): The recommended file extension for the preview image.
+ */
const gchar* gexiv2_preview_properties_get_extension (GExiv2PreviewProperties *self);
+
+/**
+ * gexiv2_preview_properties_get_size:
+ *
+ * Returns: The preview image size in bytes.
+ */
guint32 gexiv2_preview_properties_get_size
(GExiv2PreviewProperties *self);
+
+/**
+ * gexiv2_preview_properties_get_width:
+ *
+ * Returns: The preview image's display width in pixels.
+ */
guint32 gexiv2_preview_properties_get_width
(GExiv2PreviewProperties *self);
+
+/**
+ * gexiv2_preview_properties_get_height:
+ *
+ * Returns: The preview image's display height in pixels.
+ */
guint32 gexiv2_preview_properties_get_height (GExiv2PreviewProperties
*self);
diff --git a/gexiv2/gexiv2-startup.h b/gexiv2/gexiv2-startup.h
index 67c6db9..7ba73b1 100644
--- a/gexiv2/gexiv2-startup.h
+++ b/gexiv2/gexiv2-startup.h
@@ -14,6 +14,16 @@
G_BEGIN_DECLS
+/**
+ * gexiv2_initialize:
+ *
+ * gexiv2 requires initialization before its methods are used. In particular, this call must be
+ * made in a thread-safe fashion. Best practice is to call from the application's main thread and
+ * not to use any gexiv2 code until it has returned.
+ *
+ * Returns: TRUE if initialized. If FALSE, gexiv2 should not be used (unable to initialize
+ * properly).
+ */
gboolean gexiv2_initialize(void);
G_END_DECLS
diff --git a/gexiv2/gexiv2-version.m4 b/gexiv2/gexiv2-version.m4
index 1b12828..02d02b9 100644
--- a/gexiv2/gexiv2-version.m4
+++ b/gexiv2/gexiv2-version.m4
@@ -15,12 +15,25 @@ G_BEGIN_DECLS
`#'define GEXIV2_MINOR_VERSION _VERSION_MINOR_
`#'define GEXIV2_MICRO_VERSION _VERSION_MICRO_
+/**
+ * GEXIV2_CHECK_VERSION:
+ *
+ * Returns: TRUE if the gexiv2 library version is greater than or equal to the supplied version
+ * requirement.
+ */
#define GEXIV2_CHECK_VERSION(major, minor, micro) \
(GEXIV2_MAJOR_VERSION > (major) || \
(GEXIV2_MAJOR_VERSION == (major) && GEXIV2_MINOR_VERSION > (minor)) || \
(GEXIV2_MAJOR_VERSION == (major) && GEXIV2_MINOR_VERSION == (minor) && \
GEXIV2_MICRO_VERSION >= (micro)))
+/**
+ * gexiv2_get_version:
+ *
+ * Returns: The gexiv2 library's version number as a formatted decimal XXYYZZ, where XX is the
+ * major version, YY is the minor version, and ZZ is the micro version. For example, version
+ * 0.6.1 will be returned as 000601.
+ */
gint gexiv2_get_version (void);
G_END_DECLS
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
