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

| ManagedStreamCallbacks
enum | WrapperSeekOrigin

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