Generic image metadata handling: gexiv2 Reference Manual

Generic image metadata handling

Generic image metadata handling — Class to handle the various image metadata standards

Functions

GExiv2Metadata *	gexiv2_metadata_new ()
void	gexiv2_metadata_free ()
gboolean	gexiv2_metadata_try_has_tag ()
gboolean	gexiv2_metadata_try_clear_tag ()
void	gexiv2_metadata_clear ()
const gchar *	gexiv2_metadata_try_get_tag_label ()
const gchar *	gexiv2_metadata_try_get_tag_description ()
const gchar *	gexiv2_metadata_try_get_tag_type ()
gboolean	gexiv2_metadata_try_tag_supports_multiple_values ()
const gchar *	gexiv2_metadata_get_mime_type ()
gint	gexiv2_metadata_get_pixel_width ()
gint	gexiv2_metadata_get_pixel_height ()
gchar *	gexiv2_metadata_try_get_tag_string ()
gboolean	gexiv2_metadata_try_set_tag_string ()
gchar *	gexiv2_metadata_try_get_tag_interpreted_string ()
glong	gexiv2_metadata_try_get_tag_long ()
gboolean	gexiv2_metadata_try_set_tag_long ()
gchar **	gexiv2_metadata_try_get_tag_multiple ()
gboolean	gexiv2_metadata_try_set_tag_multiple ()
GBytes *	gexiv2_metadata_try_get_tag_raw ()
gboolean	gexiv2_metadata_has_tag ()
gboolean	gexiv2_metadata_clear_tag ()
const gchar *	gexiv2_metadata_get_tag_label ()
const gchar *	gexiv2_metadata_get_tag_description ()
const gchar *	gexiv2_metadata_get_tag_type ()
gchar *	gexiv2_metadata_get_tag_string ()
gboolean	gexiv2_metadata_set_tag_string ()
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 ()

Types and Values

enum	GExiv2Orientation
enum	GExiv2StructureType
struct	GExiv2Metadata
enum	GExiv2ByteOrder

Object Hierarchy

    GEnum
    ├── GExiv2ByteOrder
    ├── GExiv2Orientation
    ╰── GExiv2StructureType
    GObject
    ╰── GExiv2Metadata

Includes

#include <gexiv2/gexiv2.h>

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_try_has_tag ()

gboolean
gexiv2_metadata_try_has_tag (GExiv2Metadata *self,
                             const gchar *tag,
                             GError **error);

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

Parameters

self	An instance of GExiv2Metadata
tag	Exiv2 tag
error	A return location for a GError or `NULL`.	[allow-none]

Returns

TRUE if the tag is present.

Since: 0.14.0

gexiv2_metadata_try_clear_tag ()

gboolean
gexiv2_metadata_try_clear_tag (GExiv2Metadata *self,
                               const gchar *tag,
                               GError **error);

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
error	A return location for a GError or `NULL`.	[allow-none]

Returns

TRUE if the tag was present.

Since: 0.14.0

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_try_get_tag_label ()

const gchar *
gexiv2_metadata_try_get_tag_label (const gchar *tag,
                                   GError **error);

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

Parameters

tag	An Exiv2 tag
error	A return location for a GError or `NULL`.	[allow-none]

Returns

The tag's label.

[transfer none][allow-none]

Since: 0.12.2

gexiv2_metadata_try_get_tag_description ()

const gchar *
gexiv2_metadata_try_get_tag_description
                               (const gchar *tag,
                                GError **error);

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

Parameters

tag	An Exiv2 tag
error	A return location for a GError or `NULL`.	[allow-none]

Returns

The tag's description.

[transfer none][allow-none]

Since: 0.12.2

gexiv2_metadata_try_get_tag_type ()

const gchar *
gexiv2_metadata_try_get_tag_type (const gchar *tag,
                                  GError **error);

The names of the various Exiv2 tag types can be found at Exiv2::TypeId,

http://exiv2.org/doc/namespaceExiv2.html#a5153319711f35fe81cbc13f4b852450c

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

Parameters

tag	An Exiv2 tag
error	A return location for a GError or `NULL`.	[allow-none]

Returns

The tag's type name.

[transfer none][allow-none]

Since: 0.12.2

gexiv2_metadata_try_tag_supports_multiple_values ()

gboolean
gexiv2_metadata_try_tag_supports_multiple_values
                               (GExiv2Metadata *self,
                                const gchar *tag,
                                GError **error);

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

Multiple value tags are Xmp tags of type "XmpAlt", "XmpBag", "XmpSeq" or "LangAlt", or Iptc tags marked as Repeatable (which can be of any Iptc type). There are no multiple value Exif tags.

Parameters

self	An instance of GExiv2Metadata
tag	An Exiv2 tag
error	A return location for a GError or `NULL`.	[allow-none]

Returns

Whether tag is capable of storing multiple values or not. If tag is undefined (i.e. not built-in and not added to self ), then error is set and FALSE is returned.

Since: 0.14.0

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_try_get_tag_string ()

gchar *
gexiv2_metadata_try_get_tag_string (GExiv2Metadata *self,
                                    const gchar *tag,
                                    GError **error);

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

Tags that support multiple values are returned as a single string, with elements separated by ", ".

Parameters

self	An instance of GExiv2Metadata
tag	Exiv2 tag name
error	A return location for a GError or `NULL`.	[allow-none]

Returns

The tag's value as a string.

[transfer full][allow-none]

Since: 0.12.2

gexiv2_metadata_try_set_tag_string ()

gboolean
gexiv2_metadata_try_set_tag_string (GExiv2Metadata *self,
                                    const gchar *tag,
                                    const gchar *value,
                                    GError **error);

If a tag supports multiple values, then value is added to any existing values. For single tags, value replaces the 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
error	A return location for a GError or `NULL`.	[allow-none]

Returns

TRUE on success

Since: 0.12.2

gexiv2_metadata_try_get_tag_interpreted_string ()

gchar *
gexiv2_metadata_try_get_tag_interpreted_string
                               (GExiv2Metadata *self,
                                const gchar *tag,
                                GError **error);

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.

Tags that support multiple values are returned as a single string, with elements separated by ", ".

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

Parameters

self	An instance of GExiv2Metadata
tag	Exiv2 tag name
error	A return location for a GError or `NULL`.	[allow-none]

Returns

The tag's interpreted value as a string.

[transfer full][allow-none]

Since: 0.12.2

gexiv2_metadata_try_get_tag_long ()

glong
gexiv2_metadata_try_get_tag_long (GExiv2Metadata *self,
                                  const gchar *tag,
                                  GError **error);

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

Parameters

self	An instance of GExiv2Metadata
tag	Exiv2 tag name
error	A return location for a GError or `NULL`.	[allow-none]

Returns

The tag's value as a glong

Since: 0.12.2

gexiv2_metadata_try_set_tag_long ()

gboolean
gexiv2_metadata_try_set_tag_long (GExiv2Metadata *self,
                                  const gchar *tag,
                                  glong value,
                                  GError **error);

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
error	A return location for a GError or `NULL`.	[allow-none]

Returns

TRUE on success

Since: 0.12.2

gexiv2_metadata_try_get_tag_multiple ()

gchar **
gexiv2_metadata_try_get_tag_multiple (GExiv2Metadata *self,
                                      const gchar *tag,
                                      GError **error);

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

Parameters

self	An instance of GExiv2Metadata
tag	Exiv2 tag name
error	A return location for a GError or `NULL`.	[allow-none]

Returns

The multiple string values of tag . Returns NULL if parameters are NULL or tag does not begin with recognised type of metadata ("Exif.", "Xmp." or "Iptc."). For a well formed tag , returns array[0] = NULL if tag is undefined or is not set in the current metadata.

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

Since: 0.12.2

gexiv2_metadata_try_set_tag_multiple ()

gboolean
gexiv2_metadata_try_set_tag_multiple (GExiv2Metadata *self,
                                      const gchar *tag,
                                      const gchar **values,
                                      GError **error);

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

All previous tag values are erased. For multiple value tags, each of the non NULL entries in values is stored. For single value tags, only the last non NULL value is assigned.

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]
error	A return location for a GError or `NULL`.	[allow-none]

Returns

Boolean success value

Since: 0.12.2

gexiv2_metadata_try_get_tag_raw ()

GBytes *
gexiv2_metadata_try_get_tag_raw (GExiv2Metadata *self,
                                 const gchar *tag,
                                 GError **error);

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

Tags that support multiple values may be returned as a single byte array, with records separated by 4x INFORMATION SEPARATOR FOUR (ASCII 0x1c)

Parameters

self	An instance of GExiv2Metadata
tag	Exiv2 tag name
error	A return location for a GError or `NULL`.	[allow-none]

Returns

The tag's raw value as a byte array.

[transfer full][allow-none]

Since: 0.12.2

gexiv2_metadata_has_tag ()

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

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

Use gexiv2_metadata_try_has_tag() instead.

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

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

Use gexiv2_metadata_try_clear_tag() instead.

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_get_tag_label ()

const gchar *
gexiv2_metadata_get_tag_label (const gchar *tag);

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

Use gexiv2_metadata_try_get_tag_label() instead.

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

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

Use gexiv2_metadata_try_get_tag_description() instead.

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

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

Use gexiv2_metadata_try_get_tag_type() instead.

The names of the various Exiv2 tag types can be found at Exiv2::TypeId,

http://exiv2.org/doc/namespaceExiv2.html#a5153319711f35fe81cbc13f4b852450c

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_tag_string ()

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

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

Use gexiv2_metadata_try_get_tag_string() instead.

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

Tags that support multiple values are returned as a single string, with elements separated by ", ".

In case of error, a GLib warning will be logged. Use instead gexiv2_metadata_try_get_tag_string() if you want to avoid this and control if and how the error is outputted.

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

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

Use gexiv2_metadata_try_set_tag_string() instead.

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

If a tag supports multiple values, then value is added to any existing values. For single value tags, value replaces the value.

In case of error, a GLib warning will be logged. Use instead gexiv2_metadata_try_set_tag_string() if you want to avoid this and control if and how the error is outputted.

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_interpreted_string ()

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

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

Use gexiv2_metadata_try_get_tag_interpreted_string() instead.

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.

Tags that support multiple values are returned as a single string, with elements separated by ", ".

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

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

Use gexiv2_metadata_try_get_tag_long() instead.

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

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

Use gexiv2_metadata_try_set_tag_long() instead.

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

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

Use gexiv2_metadata_try_get_tag_multiple() instead.

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

In case of error, a GLib warning will be logged. Use instead gexiv2_metadata_try_get_tag_multiple() if you want to avoid this and control if and how the error is outputted.

Parameters

self	An instance of GExiv2Metadata
tag	Exiv2 tag name

Returns

The multiple string values of the tag. Returns NULL if parameters are NULL or tag does not begin with recognised type of metadata ("Exif.", "Xmp." or "Iptc."). For a well formed tag , returns array[0] = NULL if tag is undefined or is not set in the current metadata. (Note: xmpText/langAlt bug is fixed in gexiv2_metadata_try_get_tag_multiple()).

[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);

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

Use gexiv2_metadata_try_set_tag_multiple() instead.

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

All previous tag values are erased. For multiple value tags, each of the non NULL entries in values is stored. For single value tags, only the last non NULL value is assigned.

In case of error, a GLib warning will be logged. Use instead gexiv2_metadata_try_set_tag_multiple() if you want to avoid this and control if and how the error is outputted.

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

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

Use gexiv2_metadata_try_get_tag_raw() instead.

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

Tags that support multiple values may bereturned as a single byte array, with records separated by 4x INFORMATION SEPARATOR FOUR (ASCII 0x1c)

Parameters

self	An instance of GExiv2Metadata
tag	Exiv2 tag name

Returns

The tag's raw value as a byte array.

[transfer full][allow-none]

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

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

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 GExiv2ByteOrder

Options to control the byte order of binary EXIF data exports

Members

GEXIV2_BYTE_ORDER_LITTLE	Use little-endian byte order
GEXIV2_BYTE_ORDER_BIG	Use big-endian byte order