Reading and writing metadata

Reading and writing metadata — How to read and write metadata from files and memory

Functions

gboolean gexiv2_metadata_open_path ()
gboolean gexiv2_metadata_open_buf ()
gboolean gexiv2_metadata_from_stream ()
gboolean gexiv2_metadata_from_app1_segment ()
gboolean gexiv2_metadata_save_external ()
gboolean gexiv2_metadata_save_file ()
gboolean gexiv2_metadata_open_stream ()
gboolean gexiv2_metadata_save_stream ()
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

Description

Functions

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

gboolean
gexiv2_metadata_from_stream (GExiv2Metadata *self,
                             GInputStream *stream,
                             GError **error);

gexiv2_metadata_from_stream is deprecated and should not be used in newly-written code.

This function does not work and will be removed in a future release.


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


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

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]

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