GExiv2Metadata: gexiv2 Reference Manual

## 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

enum | GExiv2Orientation
enum | GExiv2StructureType
enum | GExiv2XmpFormatFlags
struct | GExiv2Metadata
enum | WrapperSeekOrigin
| ManagedStreamCallbacks

## 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. If Exif.Photo.FNumber does not exist, it will fall back to calculating the FNumber from Exif.Photo.ApertureValue (if available);

#### 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 {
    	GObject parent_instance;
    };

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]