GExiv2Metadata

GExiv2Metadata — Class to handle the various image metadata standards

Functions

GExiv2Metadata * gexiv2_metadata_new ()
void gexiv2_metadata_free ()
gboolean gexiv2_metadata_open_path ()
gboolean gexiv2_metadata_open_buf ()
gboolean gexiv2_metadata_open_stream ()
gboolean gexiv2_metadata_from_app1_segment ()
gboolean gexiv2_metadata_save_external ()
gboolean gexiv2_metadata_save_file ()
gboolean gexiv2_metadata_save_stream ()
gboolean gexiv2_metadata_has_tag ()
gboolean gexiv2_metadata_clear_tag ()
void gexiv2_metadata_clear ()
gboolean gexiv2_metadata_is_exif_tag ()
gboolean gexiv2_metadata_is_iptc_tag ()
gboolean gexiv2_metadata_is_xmp_tag ()
const gchar * gexiv2_metadata_get_tag_label ()
const gchar * gexiv2_metadata_get_tag_description ()
const gchar * gexiv2_metadata_get_tag_type ()
gboolean gexiv2_metadata_get_supports_exif ()
gboolean gexiv2_metadata_get_supports_iptc ()
gboolean gexiv2_metadata_get_supports_xmp ()
const gchar * gexiv2_metadata_get_mime_type ()
gint gexiv2_metadata_get_pixel_width ()
gint gexiv2_metadata_get_pixel_height ()
gchar * gexiv2_metadata_get_tag_string ()
gboolean gexiv2_metadata_set_tag_string ()
gboolean gexiv2_metadata_set_xmp_tag_struct ()
gchar * gexiv2_metadata_get_tag_interpreted_string ()
glong gexiv2_metadata_get_tag_long ()
gboolean gexiv2_metadata_set_tag_long ()
gchar ** gexiv2_metadata_get_tag_multiple ()
gboolean gexiv2_metadata_set_tag_multiple ()
GBytes * gexiv2_metadata_get_tag_raw ()
gboolean gexiv2_metadata_has_exif ()
void gexiv2_metadata_clear_exif ()
gchar ** gexiv2_metadata_get_exif_tags ()
gboolean gexiv2_metadata_get_exif_tag_rational ()
gboolean gexiv2_metadata_set_exif_tag_rational ()
gboolean gexiv2_metadata_get_exif_thumbnail ()
gboolean gexiv2_metadata_set_exif_thumbnail_from_file ()
void gexiv2_metadata_set_exif_thumbnail_from_buffer ()
void gexiv2_metadata_erase_exif_thumbnail ()
gboolean gexiv2_metadata_has_xmp ()
void gexiv2_metadata_clear_xmp ()
gchar * gexiv2_metadata_generate_xmp_packet ()
gchar * gexiv2_metadata_get_xmp_packet ()
gchar ** gexiv2_metadata_get_xmp_tags ()
gboolean gexiv2_metadata_register_xmp_namespace ()
gboolean gexiv2_metadata_unregister_xmp_namespace ()
void gexiv2_metadata_unregister_all_xmp_namespaces ()
gboolean gexiv2_metadata_has_iptc ()
void gexiv2_metadata_clear_iptc ()
gchar ** gexiv2_metadata_get_iptc_tags ()
GExiv2Orientation gexiv2_metadata_get_orientation ()
void gexiv2_metadata_set_orientation ()
gint gexiv2_metadata_get_metadata_pixel_width ()
gint gexiv2_metadata_get_metadata_pixel_height ()
void gexiv2_metadata_set_metadata_pixel_width ()
void gexiv2_metadata_set_metadata_pixel_height ()
gchar * gexiv2_metadata_get_comment ()
void gexiv2_metadata_set_comment ()
void gexiv2_metadata_clear_comment ()
gboolean gexiv2_metadata_get_exposure_time ()
gdouble gexiv2_metadata_get_fnumber ()
gdouble gexiv2_metadata_get_focal_length ()
gint gexiv2_metadata_get_iso_speed ()
gboolean gexiv2_metadata_get_gps_longitude ()
gboolean gexiv2_metadata_get_gps_latitude ()
gboolean gexiv2_metadata_get_gps_altitude ()
gboolean gexiv2_metadata_get_gps_info ()
gboolean gexiv2_metadata_set_gps_info ()
void gexiv2_metadata_delete_gps_info ()
GExiv2PreviewProperties ** gexiv2_metadata_get_preview_properties ()
GExiv2PreviewImage * gexiv2_metadata_get_preview_image ()
gboolean (*Stream_CanSeek) ()
gboolean (*Stream_CanRead) ()
gboolean (*Stream_CanWrite) ()
gint64 (*Stream_Length) ()
gint64 (*Stream_Position) ()
gint32 (*Stream_Read) ()
void (*Stream_Write) ()
void (*Stream_Seek) ()
void (*Stream_Flush) ()

Types and Values

Object Hierarchy

    GObject
    ╰── GExiv2Metadata

Description

GExiv2Metadata is a generic object that provides everything from simple aggregated accessors to common data such as image comments up to fine-grained access to specific tags of a specific format, be it EXIF, IPTC or XMP

Functions

gexiv2_metadata_new ()

GExiv2Metadata *
gexiv2_metadata_new (void);

Returns

A fully constructed GExiv2Metadata ready to be used.

[transfer full]

gexiv2_metadata_free ()

void
gexiv2_metadata_free (GExiv2Metadata *self);

gexiv2_metadata_free has been deprecated since version 0.10.3 and should not be used in newly-written code.

Use g_object_unref() instead.

Destroys the GExiv2Metadata object and frees all associated memory.

Parameters

self

An instance of GExiv2Metadata

 

gexiv2_metadata_open_path ()

gboolean
gexiv2_metadata_open_path (GExiv2Metadata *self,
                           const gchar *path,
                           GError **error);

The file must be an image format supported by Exiv2.

Parameters

self

An instance of GExiv2Metadata

 

path

Path to the file you want to open

 

error

A return location for a GError or NULL.

[allow-none]

Returns

Boolean success indicator

gexiv2_metadata_open_buf ()

gboolean
gexiv2_metadata_open_buf (GExiv2Metadata *self,
                          const guint8 *data,
                          glong n_data,
                          GError **error);

The buffer must be an image format supported by Exiv2.

Parameters

self

An instance of GExiv2Metadata

 

data

A buffer containing the data to be read.

[array length=n_data]

n_data

The length of the buffer.

[skip]

error

A return location for a GError or NULL.

[allow-none]

Returns

Boolean success indicator

gexiv2_metadata_open_stream ()

gboolean
gexiv2_metadata_open_stream (GExiv2Metadata *self,
                             ManagedStreamCallbacks *cb,
                             GError **error);

The stream must be an image format supported by Exiv2.

[skip]

Parameters

self

An instance of GExiv2Metadata

 

cb

A ManagedStreamCallbacks struct offering stream access.

 

error

A return location for a GError or NULL.

[allow-none]

Returns

Boolean success indicator

gexiv2_metadata_from_app1_segment ()

gboolean
gexiv2_metadata_from_app1_segment (GExiv2Metadata *self,
                                   const guint8 *data,
                                   glong n_data,
                                   GError **error);

Load only an EXIF buffer, typically stored in a JPEG's APP1 segment.

Parameters

self

An instance of GExiv2Metadata

 

data

A buffer containing the data to be read.

[array length=n_data]

n_data

The length of the buffer.

[skip]

error

A return location for a GError or NULL.

[allow-none]

Returns

Boolean success indicator.

gexiv2_metadata_save_external ()

gboolean
gexiv2_metadata_save_external (GExiv2Metadata *self,
                               const gchar *path,
                               GError **error);

Saves the metadata to the specified using an XMP sidecar file.

Parameters

self

An instance of GExiv2Metadata

 

path

Path to the file you want to save to.

 

error

A return location for a GError or NULL.

[allow-none]

Returns

Boolean success indicator.

Since: 0.10.6

gexiv2_metadata_save_file ()

gboolean
gexiv2_metadata_save_file (GExiv2Metadata *self,
                           const gchar *path,
                           GError **error);

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.

Parameters

self

An instance of GExiv2Metadata

 

path

Path to the file you want to save to.

 

error

A return location for a GError or NULL.

[allow-none]

Returns

Boolean success indicator.

gexiv2_metadata_save_stream ()

gboolean
gexiv2_metadata_save_stream (GExiv2Metadata *self,
                             ManagedStreamCallbacks *cb,
                             GError **error);

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.

[skip]

Parameters

self

An instance of GExiv2Metadata

 

cb

A ManagedStreamCallbacks struct offering stream access.

 

error

A return location for a GError or NULL.

[allow-none]

Returns

Boolean success indicator.

gexiv2_metadata_has_tag ()

gboolean
gexiv2_metadata_has_tag (GExiv2Metadata *self,
                         const gchar *tag);

The Exiv2 Tag Reference can be found at http://exiv2.org/metadata.html

Parameters

self

An instance of GExiv2Metadata

 

tag

Exiv2 tag

 

Returns

TRUE if the tag is present.

gexiv2_metadata_clear_tag ()

gboolean
gexiv2_metadata_clear_tag (GExiv2Metadata *self,
                           const gchar *tag);

Removes the Exiv2 tag from the metadata object.

The Exiv2 Tag Reference can be found at http://exiv2.org/metadata.html

Parameters

self

An instance of GExiv2Metadata

 

tag

Exiv2 tag

 

Returns

TRUE if the tag was present.

gexiv2_metadata_clear ()

void
gexiv2_metadata_clear (GExiv2Metadata *self);

Removes all tags for all domains (EXIF, IPTC, and XMP).

Parameters

self

An instance of GExiv2Metadata

 

gexiv2_metadata_is_exif_tag ()

gboolean
gexiv2_metadata_is_exif_tag (const gchar *tag);

The Exiv2 Tag Reference can be found at http://exiv2.org/metadata.html

Parameters

tag

An Exiv2 tag

 

Returns

TRUE if the Exiv2 tag is for the EXIF domain.

gexiv2_metadata_is_iptc_tag ()

gboolean
gexiv2_metadata_is_iptc_tag (const gchar *tag);

The Exiv2 Tag Reference can be found at http://exiv2.org/metadata.html

Parameters

tag

An Exiv2 tag

 

Returns

TRUE if the Exiv2 tag is for the IPTC domain.

gexiv2_metadata_is_xmp_tag ()

gboolean
gexiv2_metadata_is_xmp_tag (const gchar *tag);

The Exiv2 Tag Reference can be found at http://exiv2.org/metadata.html

Parameters

tag

An Exiv2 tag

 

Returns

TRUE if the Exiv2 tag is for the XMP domain.

gexiv2_metadata_get_tag_label ()

const gchar *
gexiv2_metadata_get_tag_label (const gchar *tag);

The Exiv2 Tag Reference can be found at http://exiv2.org/metadata.html

Parameters

tag

An Exiv2 tag

 

Returns

The tag's label.

[transfer none][allow-none]

gexiv2_metadata_get_tag_description ()

const gchar *
gexiv2_metadata_get_tag_description (const gchar *tag);

The Exiv2 Tag Reference can be found at http://exiv2.org/metadata.html

Parameters

tag

An Exiv2 tag

 

Returns

The tag's description.

[transfer none][allow-none]

gexiv2_metadata_get_tag_type ()

const gchar *
gexiv2_metadata_get_tag_type (const gchar *tag);

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

Parameters

tag

An Exiv2 tag

 

Returns

The tag's type name.

[transfer none][allow-none]

gexiv2_metadata_get_supports_exif ()

gboolean
gexiv2_metadata_get_supports_exif (GExiv2Metadata *self);

Query self whether it supports writing EXIF metadata.

Parameters

self

An instance of GExiv2Metadata

 

Returns

TRUE if the loaded image type supports writing EXIF metadata.

gexiv2_metadata_get_supports_iptc ()

gboolean
gexiv2_metadata_get_supports_iptc (GExiv2Metadata *self);

Query self whether it supports writing IPTC metadata.

Parameters

self

An instance of GExiv2Metadata

 

Returns

TRUE if the loaded image type supports writing IPTC metadata.

gexiv2_metadata_get_supports_xmp ()

gboolean
gexiv2_metadata_get_supports_xmp (GExiv2Metadata *self);

Query self whether it supports writing XMP metadata.

Parameters

self

An instance of GExiv2Metadata

 

Returns

TRUE if the loaded image type supports writing XMP metadata.

gexiv2_metadata_get_mime_type ()

const gchar *
gexiv2_metadata_get_mime_type (GExiv2Metadata *self);

Query mime type of currently loaded image.

Parameters

self

An instance of GExiv2Metadata

 

Returns

The MIME type of the loaded image, NULL if not loaded or unknown.

[transfer none]

gexiv2_metadata_get_pixel_width ()

gint
gexiv2_metadata_get_pixel_width (GExiv2Metadata *self);

Get the actual unoriented display width in pixels of the loaded image. May be different than the width reported by various metadata tags, i.e. "Exif.Photo.PixelXDimension".

Parameters

self

An instance of GExiv2Metadata

 

Returns

Pixel width of current image

gexiv2_metadata_get_pixel_height ()

gint
gexiv2_metadata_get_pixel_height (GExiv2Metadata *self);

Get the actual 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".

Parameters

self

An instance of GExiv2Metadata

 

Returns

Pixel height of current image

gexiv2_metadata_get_tag_string ()

gchar *
gexiv2_metadata_get_tag_string (GExiv2Metadata *self,
                                const gchar *tag);

The Exiv2 Tag Reference can be found at http://exiv2.org/metadata.html

Parameters

self

An instance of GExiv2Metadata

 

tag

Exiv2 tag name

 

Returns

The tag's value as a string.

[transfer full][allow-none]

gexiv2_metadata_set_tag_string ()

gboolean
gexiv2_metadata_set_tag_string (GExiv2Metadata *self,
                                const gchar *tag,
                                const gchar *value);

The Exiv2 Tag Reference can be found at http://exiv2.org/metadata.html

Parameters

self

An instance of GExiv2Metadata

 

tag

Exiv2 tag name

 

value

The value to set or replace the existing value

 

Returns

TRUE on success

gexiv2_metadata_set_xmp_tag_struct ()

gboolean
gexiv2_metadata_set_xmp_tag_struct (GExiv2Metadata *self,
                                    const gchar *tag,
                                    GExiv2StructureType type);

gexiv2_metadata_get_tag_interpreted_string ()

gchar *
gexiv2_metadata_get_tag_interpreted_string
                               (GExiv2Metadata *self,
                                const gchar *tag);

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.

The Exiv2 Tag Reference can be found at http://exiv2.org/metadata.html

Parameters

self

An instance of GExiv2Metadata

 

tag

Exiv2 tag name

 

Returns

The tag's interpreted value as a string.

[transfer full][allow-none]

gexiv2_metadata_get_tag_long ()

glong
gexiv2_metadata_get_tag_long (GExiv2Metadata *self,
                              const gchar *tag);

The Exiv2 Tag Reference can be found at http://exiv2.org/metadata.html

Parameters

self

An instance of GExiv2Metadata

 

tag

Exiv2 tag name

 

Returns

The tag's value as a glong

gexiv2_metadata_set_tag_long ()

gboolean
gexiv2_metadata_set_tag_long (GExiv2Metadata *self,
                              const gchar *tag,
                              glong value);

The Exiv2 Tag Reference can be found at http://exiv2.org/metadata.html

Parameters

self

An instance of GExiv2Metadata

 

tag

Exiv2 tag name

 

value

The value to set or replace the existing value

 

Returns

TRUE on success

gexiv2_metadata_get_tag_multiple ()

gchar **
gexiv2_metadata_get_tag_multiple (GExiv2Metadata *self,
                                  const gchar *tag);

The Exiv2 Tag Reference can be found at http://exiv2.org/metadata.html

Parameters

self

An instance of GExiv2Metadata

 

tag

Exiv2 tag name

 

Returns

The multiple string values of the tag.

[transfer full][allow-none][array zero-terminated=1]

gexiv2_metadata_set_tag_multiple ()

gboolean
gexiv2_metadata_set_tag_multiple (GExiv2Metadata *self,
                                  const gchar *tag,
                                  const gchar **values);

The Exiv2 Tag Reference can be found at http://exiv2.org/metadata.html

Parameters

self

An instance of GExiv2Metadata

 

tag

Exiv2 tag name

 

values

An array of values to set or replace the existing value(s).

[array zero-terminated=1]

Returns

Boolean success value

gexiv2_metadata_get_tag_raw ()

GBytes *
gexiv2_metadata_get_tag_raw (GExiv2Metadata *self,
                             const gchar *tag);

The Exiv2 Tag Reference can be found at http://exiv2.org/metadata.html

Parameters

self

An instance of GExiv2Metadata

 

tag

Exiv2 tag name

 

Returns

The tag's raw value as a byte array.

[transfer full][allow-none]

gexiv2_metadata_has_exif ()

gboolean
gexiv2_metadata_has_exif (GExiv2Metadata *self);

Parameters

self

An instance of GExiv2Metadata

 

Returns

TRUE if EXIF metadata is present in the loaded image

gexiv2_metadata_clear_exif ()

void
gexiv2_metadata_clear_exif (GExiv2Metadata *self);

Clears all EXIF metadata from the loaded image.

Parameters

self

An instance of GExiv2Metadata

 

gexiv2_metadata_get_exif_tags ()

gchar **
gexiv2_metadata_get_exif_tags (GExiv2Metadata *self);

Query self for a list of available EXIF tags

Parameters

self

An instance of GExiv2Metadata

 

Returns

A list of the available EXIF tags in the loaded image.

[transfer full][array zero-terminated=1]

gexiv2_metadata_get_exif_tag_rational ()

gboolean
gexiv2_metadata_get_exif_tag_rational (GExiv2Metadata *self,
                                       const gchar *tag,
                                       gint *nom,
                                       gint *den);

Fetch EXIF tag represented by a fraction. nom will contain the numerator, den the denominator of the fraction on successful return.

Parameters

self

An instance of GExiv2Metadata

 

tag

The tag you want the rational value for.

[in]

nom

The numerator.

[out]

den

The denominator.

[out]

Returns

Boolean success value.

[skip]

gexiv2_metadata_set_exif_tag_rational ()

gboolean
gexiv2_metadata_set_exif_tag_rational (GExiv2Metadata *self,
                                       const gchar *tag,
                                       gint nom,
                                       gint den);

Set EXIF tag represented by a fraction, with nom being the numerator, den the denominator of the fraction.

Parameters

self

An instance of GExiv2Metadata

 

tag

The Exiv2 tag.

[in]

nom

Rational numerator

 

den

Rational denominator

 

Returns

Boolean success value.

[skip]

gexiv2_metadata_get_exif_thumbnail ()

gboolean
gexiv2_metadata_get_exif_thumbnail (GExiv2Metadata *self,
                                    guint8 **buffer,
                                    gint *size);

Get the thumbnail stored in the EXIF data of self

Parameters

self

An instance of GExiv2Metadata

 

buffer

Where to store the thumbnail data.

[out][array length=size][transfer full]

size

Size of the thumbnail's buffer.

[skip]

Returns

Boolean success value.

[skip]

gexiv2_metadata_set_exif_thumbnail_from_file ()

gboolean
gexiv2_metadata_set_exif_thumbnail_from_file
                               (GExiv2Metadata *self,
                                const gchar *path,
                                GError **error);

Sets or replaces the EXIF thumbnail with the image in the file

Parameters

self

An instance of GExiv2Metadata

 

path

Path of image file.

[in]

error

A return location for a GError or NULL.

[allow-none]

Returns

Boolean success value

gexiv2_metadata_set_exif_thumbnail_from_buffer ()

void
gexiv2_metadata_set_exif_thumbnail_from_buffer
                               (GExiv2Metadata *self,
                                const guint8 *buffer,
                                gint size);

Parameters

self

An instance of GExiv2Metadata

 

buffer

A buffer containing thumbnail data.

[array length=size]

size

Size of the thumbnail's buffer.

[skip]

gexiv2_metadata_erase_exif_thumbnail ()

void
gexiv2_metadata_erase_exif_thumbnail (GExiv2Metadata *self);

Removes the EXIF thumbnail from the loaded image.

Parameters

self

An instance of GExiv2Metadata

 

gexiv2_metadata_has_xmp ()

gboolean
gexiv2_metadata_has_xmp (GExiv2Metadata *self);

Parameters

self

An instance of GExiv2Metadata

 

Returns

TRUE if XMP metadata is present in the loaded image

gexiv2_metadata_clear_xmp ()

void
gexiv2_metadata_clear_xmp (GExiv2Metadata *self);

Clears all XMP metadata from the loaded image.

Parameters

self

An instance of GExiv2Metadata

 

gexiv2_metadata_generate_xmp_packet ()

gchar *
gexiv2_metadata_generate_xmp_packet (GExiv2Metadata *self,
                                     GExiv2XmpFormatFlags xmp_format_flags,
                                     guint32 padding);

Encode the XMP packet as a NULL-terminated string.

Parameters

self

An instance of GExiv2Metadata

 

xmp_format_flags

One of GExiv2XmpFormatFlags

 

padding

The padding (FIXME: Add documentation)

 

Returns

Encode the XMP packet and return as a NULL-terminated string.

[transfer full][allow-none]

gexiv2_metadata_get_xmp_packet ()

gchar *
gexiv2_metadata_get_xmp_packet (GExiv2Metadata *self);

Parameters

self

An instance of GExiv2Metadata

 

Returns

The currently-encoded XMP packet (see gexiv2_metadata_generate_xmp_packet).

[transfer full][allow-none]

gexiv2_metadata_get_xmp_tags ()

gchar **
gexiv2_metadata_get_xmp_tags (GExiv2Metadata *self);

Parameters

self

An instance of GExiv2Metadata

 

Returns

A list of the available XMP tags.

[transfer full][array zero-terminated=1]

gexiv2_metadata_register_xmp_namespace ()

gboolean
gexiv2_metadata_register_xmp_namespace
                               (const gchar *name,
                                const gchar *prefix);

Parameters

name

XMP URI name (should end in /).

[in]

prefix

XMP namespace prefix.

[in]

Returns

Boolean success value.

[skip]

gexiv2_metadata_unregister_xmp_namespace ()

gboolean
gexiv2_metadata_unregister_xmp_namespace
                               (const gchar *name);

Parameters

name

XMP URI name (should end in /).

[in]

Returns

Boolean success value.

[skip]

gexiv2_metadata_unregister_all_xmp_namespaces ()

void
gexiv2_metadata_unregister_all_xmp_namespaces
                               (void);

gexiv2_metadata_has_iptc ()

gboolean
gexiv2_metadata_has_iptc (GExiv2Metadata *self);

Parameters

self

An instance of GExiv2Metadata

 

Returns

TRUE if IPTC metadata is present in the loaded image

gexiv2_metadata_clear_iptc ()

void
gexiv2_metadata_clear_iptc (GExiv2Metadata *self);

Clears all IPTC metadata from the loaded image.

Parameters

self

An instance of GExiv2Metadata

 

gexiv2_metadata_get_iptc_tags ()

gchar **
gexiv2_metadata_get_iptc_tags (GExiv2Metadata *self);

Query self for a list of available IPTC tags

Parameters

self

An instance of GExiv2Metadata

 

Returns

A list of the available IPTC tags.

[transfer full][array zero-terminated=1]

gexiv2_metadata_get_orientation ()

GExiv2Orientation
gexiv2_metadata_get_orientation (GExiv2Metadata *self);

The EXIF Orientation field

Parameters

self

An instance of GExiv2Metadata

 

Returns

A GExiv2Orientation value representing the EXIF orientation value.

gexiv2_metadata_set_orientation ()

void
gexiv2_metadata_set_orientation (GExiv2Metadata *self,
                                 GExiv2Orientation orientation);

The orientation must be valid and cannot be GEXIV2_ORIENTATION_UNSPECIFIED.

Parameters

self

An instance of GExiv2Metadata

 

orientation

The new GExiv2Orientation for the image.

 

gexiv2_metadata_get_metadata_pixel_width ()

gint
gexiv2_metadata_get_metadata_pixel_width
                               (GExiv2Metadata *self);

Composite accessor to query the pixel with stored in the metadata. This might differ from the width of image that is available through gexiv2_metadata_get_pixel_width()

Parameters

self

An instance of GExiv2Metadata

 

Returns

Width of images in pixels as stored in the metadata

gexiv2_metadata_get_metadata_pixel_height ()

gint
gexiv2_metadata_get_metadata_pixel_height
                               (GExiv2Metadata *self);

Composite accessor to query the pixel with stored in the metadata. This might differ from the height of image that is available through gexiv2_metadata_get_pixel_height()

Parameters

self

An instance of GExiv2Metadata

 

Returns

Height of images in pixels as stored in the metadata

gexiv2_metadata_set_metadata_pixel_width ()

void
gexiv2_metadata_set_metadata_pixel_width
                               (GExiv2Metadata *self,
                                gint width);

Composite setter to update the image's metadata with width

Parameters

self

An instance of GExiv2Metadata

 

width

The width of the image as it should be put into the metadata.

 

gexiv2_metadata_set_metadata_pixel_height ()

void
gexiv2_metadata_set_metadata_pixel_height
                               (GExiv2Metadata *self,
                                gint height);

Update the image's metadata with height

Parameters

self

An instance of GExiv2Metadata

 

height

The width of the image as it should be put into the metadata.

 

gexiv2_metadata_get_comment ()

gchar *
gexiv2_metadata_get_comment (GExiv2Metadata *self);

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).

MWG guidelines refer to these as Description: a textual description of a resource's content.

These fields are:

  • Exif.Image.ImageDescription (MWG Guidelines)

  • Exif.Photo.UserComment

  • Exif.Image.XPComment

  • Iptc.Application2.Caption (MWG Guidelines)

  • Xmp.dc.description (MWG Guidelines)

  • Xmp.acdsee.notes (Commonly requested, read only)

Note that in the EXIF specification Exif.Image.ImageDescription is described 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 recommended to use Exiv2 tags directly rather than this method, which is more useful for quick or casual use.

Parameters

self

An instance of GExiv2Metadata

 

Returns

The photo's comment field.

[transfer full][allow-none]

gexiv2_metadata_set_comment ()

void
gexiv2_metadata_set_comment (GExiv2Metadata *self,
                             const gchar *comment);

This is a composite setter that will set a number of fields to the supplied value. See gexiv2_metadata_get_comment for more information.

Parameters

self

An instance of GExiv2Metadata

 

comment

Comment string to set. Must not be NULL

 

gexiv2_metadata_clear_comment ()

void
gexiv2_metadata_clear_comment (GExiv2Metadata *self);

This is a composite clear method that will clear a number of fields. See gexiv2_metadata_get_comment for more information.

Parameters

self

An instance of GExiv2Metadata

 

gexiv2_metadata_get_exposure_time ()

gboolean
gexiv2_metadata_get_exposure_time (GExiv2Metadata *self,
                                   gint *nom,
                                   gint *den);

Returns the exposure time in seconds (shutter speed, not date-time of exposure) as a rational. See https://en.wikipedia.org/wiki/Shutter_speed for more information.

Parameters

self

An instance of GExiv2Metadata

 

nom

The numerator.

[out]

den

The denominator.

[out]

Returns

Boolean success value.

[skip]

gexiv2_metadata_get_fnumber ()

gdouble
gexiv2_metadata_get_fnumber (GExiv2Metadata *self);

See https://en.wikipedia.org/wiki/F-number for more information.

Parameters

self

An instance of GExiv2Metadata

 

Returns

The exposure Fnumber as a gdouble, or -1.0 if tag is not present or invalid.

gexiv2_metadata_get_focal_length ()

gdouble
gexiv2_metadata_get_focal_length (GExiv2Metadata *self);

See https://en.wikipedia.org/wiki/Flange_focal_distance for more information.

Parameters

self

An instance of GExiv2Metadata

 

Returns

The focal length as a gdouble, or -1.0 if tag is not present or invalid.

gexiv2_metadata_get_iso_speed ()

gint
gexiv2_metadata_get_iso_speed (GExiv2Metadata *self);

See https://en.wikipedia.org/wiki/Iso_speed for more information.

Parameters

self

An instance of GExiv2Metadata

 

Returns

The ISO speed rating as a gint, or 0 if tag is not present or invalid.

gexiv2_metadata_get_gps_longitude ()

gboolean
gexiv2_metadata_get_gps_longitude (GExiv2Metadata *self,
                                   gdouble *longitude);

Query the longitude stored in the GPS tags of self

Parameters

self

An instance of GExiv2Metadata

 

longitude

Variable to store the longitude value.

[out]

Returns

Boolean success value.

[skip]

gexiv2_metadata_get_gps_latitude ()

gboolean
gexiv2_metadata_get_gps_latitude (GExiv2Metadata *self,
                                  gdouble *latitude);

Query the latitude stored in the GPS tags of self

Parameters

self

An instance of GExiv2Metadata

 

latitude

Variable to store the latitude value.

[out]

Returns

Boolean success value.

[skip]

gexiv2_metadata_get_gps_altitude ()

gboolean
gexiv2_metadata_get_gps_altitude (GExiv2Metadata *self,
                                  gdouble *altitude);

Convenience function to query the altitude stored in the GPS tags of the image

Parameters

self

An instance of GExiv2Metadata

 

altitude

Variable to store the altitude value.

[out]

Returns

Boolean success value.

[skip]

gexiv2_metadata_get_gps_info ()

gboolean
gexiv2_metadata_get_gps_info (GExiv2Metadata *self,
                              gdouble *longitude,
                              gdouble *latitude,
                              gdouble *altitude);

Convenience function to query all available GPS information at once.

Parameters

self

An instance of GExiv2Metadata

 

longitude

Storage for longitude value.

[out]

latitude

Storage for latitude value.

[out]

altitude

Storage for altitude value.

[out]

Returns

Boolean success value.

[skip]

gexiv2_metadata_set_gps_info ()

gboolean
gexiv2_metadata_set_gps_info (GExiv2Metadata *self,
                              gdouble longitude,
                              gdouble latitude,
                              gdouble altitude);

Convenience function to query all available GPS information at once.

Parameters

self

An instance of GExiv2Metadata

 

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

Boolean success value.

[skip]

gexiv2_metadata_delete_gps_info ()

void
gexiv2_metadata_delete_gps_info (GExiv2Metadata *self);

Removes all GPS metadata from the loaded image

Parameters

self

An instance of GExiv2Metadata

 

gexiv2_metadata_get_preview_properties ()

GExiv2PreviewProperties **
gexiv2_metadata_get_preview_properties
                               (GExiv2Metadata *self);

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.

Parameters

self

An instance of GExiv2Metadata

 

Returns

An array of GExiv2PreviewProperties instances, one for each preview present in the loaded image.

[transfer none][allow-none][array zero-terminated=1]

gexiv2_metadata_get_preview_image ()

GExiv2PreviewImage *
gexiv2_metadata_get_preview_image (GExiv2Metadata *self,
                                   GExiv2PreviewProperties *props);

Parameters

self

An instance of GExiv2Metadata

 

props

A GExiv2PreviewProperties instance

 

Returns

A GExiv2PreviewImage instance for the particular GExiv2PreviewProperties.

[transfer full]

Stream_CanSeek ()

gboolean
(*Stream_CanSeek) (void *handle);

Function that returns the seekability of the stream

Parameters

handle

Opaque storage for the native handle this function will operate on

 

Returns

TRUE if the stream object can be seeked

Stream_CanRead ()

gboolean
(*Stream_CanRead) (void *handle);

Function that returns the readability of the stream

Parameters

handle

Opaque storage for the native handle this function will operate on

 

Returns

TRUE if the stream object can be read from.

Stream_CanWrite ()

gboolean
(*Stream_CanWrite) (void *handle);

Function that returns the readability of the stream

Parameters

handle

Opaque storage for the native handle this function will operate on

 

Returns

TRUE if the stream object can be written to.

Stream_Length ()

gint64
(*Stream_Length) (void *handle);

Function to query the length of the stream

Parameters

handle

Opaque storage for the native handle this function will operate on

 

Returns

The length of the stream

Stream_Position ()

gint64
(*Stream_Position) (void *handle);

Function to query the current position in the stream

Parameters

handle

Opaque storage for the native handle this function will operate on

 

Returns

The current position

Stream_Read ()

gint32
(*Stream_Read) (void *handle,
                void *buffer,
                gint32 offset,
                gint32 count);

Function to read data from the stream

Parameters

handle

Opaque storage for the native handle this function will operate on

 

buffer

Destination data to read into

 

offset

Offset in buffer where data should be written to

 

count

Number of bytes to read

 

Returns

The number of bytes read, 0 on EOF or -1 on error.

Stream_Write ()

void
(*Stream_Write) (void *handle,
                 void *buffer,
                 gint32 offset,
                 gint32 count);

Function to write data to the stream

Parameters

handle

Opaque storage for the native handle this function will operate on

 

buffer

Source data to put into the stream

 

offset

Offset in buffer where data should be read from

 

count

Number of bytes to write

 

Returns

The number of bytes written or -1 on error.

Stream_Seek ()

void
(*Stream_Seek) (void *handle,
                gint64 offset,
                WrapperSeekOrigin origin);

Change the read or write position in the current stream

Parameters

handle

Opaque storage for the native handle this function will operate on

 

offset

Position in the stream, relative to origin

 

origin

Determines meaning of offset, being relative to current position, start or end of the stream.

 

Stream_Flush ()

void
(*Stream_Flush) (void *handle);

Schedule writing buffered data to the stream's real storage.

Parameters

handle

Opaque storage for the native handle this function will operate on

 

Types and Values

enum 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

Members

GEXIV2_ORIENTATION_MIN

   

GEXIV2_ORIENTATION_UNSPECIFIED

The orientation of the image is unknown

 

GEXIV2_ORIENTATION_NORMAL

The orientation of the image is without any rotation.

 

GEXIV2_ORIENTATION_HFLIP

The image is flipped on its horizontal axis

 

GEXIV2_ORIENTATION_ROT_180

The image is rotated by 180 degrees

 

GEXIV2_ORIENTATION_VFLIP

The Image is flipped on its vertical axis

 

GEXIV2_ORIENTATION_ROT_90_HFLIP

The image is rotated by 90 degrees clockwise and flipped on its horizontal axis

 

GEXIV2_ORIENTATION_ROT_90

The image is rotated by 90 degrees clockwise

 

GEXIV2_ORIENTATION_ROT_90_VFLIP

The image is rotated by 90 degrees clockwise and flipped on its vertical axis

 

GEXIV2_ORIENTATION_ROT_270

The image is rotated 270 degrees clockwise

 

GEXIV2_ORIENTATION_MAX

   

enum GExiv2StructureType

Used in gexiv2_metadata_set_xmp_tag_struct() to determine the array type

Members

GEXIV2_STRUCTURE_XA_NONE

Structure is not an array

 

GEXIV2_STRUCTURE_XA_ALT

A list of alternative values

 

GEXIV2_STRUCTURE_XA_BAG

An unordered list of values

 

GEXIV2_STRUCTURE_XA_SEQ

An ordered list of values

 

GEXIV2_STRUCTURE_XA_LANG

Not supported. For completeness only

 

enum GExiv2XmpFormatFlags

Options to control the format of the serialized XMP packet Taken from: exiv2/src/xmp.hpp

Members

GEXIV2_OMIT_PACKET_WRAPPER

Omit the XML packet wrapper.

 

GEXIV2_READ_ONLY_PACKET

Default is a writeable packet.

 

GEXIV2_USE_COMPACT_FORMAT

Use a compact form of RDF.

 

GEXIV2_INCLUDE_THUMBNAIL_PAD

Include a padding allowance for a thumbnail image.

 

GEXIV2_EXACT_PACKET_LENGTH

The padding parameter is the overall packet length.

 

GEXIV2_WRITE_ALIAS_COMMENTS

Show aliases as XML comments.

 

GEXIV2_OMIT_ALL_FORMATTING

Omit all formatting whitespace.

 

struct GExiv2Metadata

struct 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 documentation 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 tags (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

enum WrapperSeekOrigin

Seek positions for Stream_Seek

Members

Begin

Seeking offset is relative to the beginning of the stream

 

Current

Seeking offset is relative to the current offset in the stream

 

End

Seeking offset is relative to the end of the stream

 

ManagedStreamCallbacks

typedef struct {
    void *handle;
    Stream_CanSeek CanSeek;
    Stream_CanRead CanRead;
    Stream_CanWrite CanWrite;
    Stream_Length Length;
    Stream_Position Position;
    Stream_Read Read;
    Stream_Write Write;
    Stream_Seek Seek;
    Stream_Flush Flush;
} ManagedStreamCallbacks;

ManagedStreamCallbacks is a set of callbacks that describe a stream that can be passed to gexiv2_metadata_open_stream() to read image meta-data from arbitrary data sources that can be mapped to this set of callbacks.

At least CanSeek and CanRead need to return TRUE and the relevant call-backs must not be NULL to be any useful.

Members

void *handle;

Storage for the native handle to be used with this stream

 

Stream_CanSeek CanSeek;

Pointer to a function that describes the seekability of handle

 

Stream_CanRead CanRead;

Pointer to a function that describes the readability of handle

 

Stream_CanWrite CanWrite;

Pointer to a function that describes the writability of handle

 

Stream_Length Length;

Pointer to a function that gets the length of handle

 

Stream_Position Position;

Pointer to a function that gives the current location inside handle

 

Stream_Read Read;

Read bytes from the stream

 

Stream_Write Write;

Function pointer to write to the stream. Can be NULL if CanWrite returns FALSE.

[nullable]

Stream_Seek Seek;

Function pointer to seek in the stream.

 

Stream_Flush Flush;

Function pointer schedule writing of all cached data to disk. Can be NULL if CanWrite returns FALSE.

[nullable]