GtefFileMetadata: Gtef 2 Reference Manual

## GtefFileMetadata GtefFileMetadata — File metadata |

## Functions

GtefFileMetadata * | gtef_file_metadata_new ()
GtefFile * | gtef_file_metadata_get_file ()
gchar * | gtef_file_metadata_get ()
void | gtef_file_metadata_set ()
gboolean | gtef_file_metadata_load ()
void | gtef_file_metadata_load_async ()
gboolean | gtef_file_metadata_load_finish ()
gboolean | gtef_file_metadata_save ()
void | gtef_file_metadata_save_async ()
gboolean | gtef_file_metadata_save_finish ()

## Properties

GtefFile * | file | Read / Write / Construct Only

## Types and Values

| GtefFileMetadata

## Object Hierarchy

        GObject
        ╰── GtefFileMetadata

## Includes

    #include <gtef/gtef.h>

## Description

A GtefFileMetadata object stores the metadata of a GtefFile. You need to call `gtef_metadata_manager_init()` and `gtef_metadata_manager_shutdown()` in your application, in case GVfs metadata are not supported.

The `gtef_file_metadata_get()` and `gtef_file_metadata_set()` functions don't load or save the metadata on disk. They only access the metadata stored in the GtefFileMetadata object memory. To load the metadata from disk, call `gtef_file_metadata_load()` or its async variant. Likewise, to save the metadata on disk, call `gtef_file_metadata_save()` or its async variant. When loading or saving metadata, the file at “location”, if non-`NULL`, must exist on the filesystem, otherwise an error is returned.

When the “location” changes, the metadata are still kept in the GtefFileMetadata object memory. But the metadata are not automatically saved for the new location.

## Functions

### gtef_file_metadata_new ()

    GtefFileMetadata *
    gtef_file_metadata_new (GtefFile *file);

#### Parameters

file | the GtefFile that the metadata will belong to. |

#### Returns

a new GtefFileMetadata object.

Since: 1.0

### gtef_file_metadata_get_file ()

    GtefFile *
    gtef_file_metadata_get_file (GtefFileMetadata *metadata);

#### Parameters

metadata | a GtefFileMetadata object. |

#### Returns

the GtefFile that the metadata belong to.

[transfer none]

Since: 1.0

### gtef_file_metadata_get ()

    gchar *
    gtef_file_metadata_get (GtefFileMetadata *metadata,
                            const gchar *key);

Gets the value of a metadata stored in the `metadata` object memory.

#### Parameters

metadata | a GtefFileMetadata. |
key | the name of the metadata. |

#### Returns

the value of the metadata, or `NULL` if the metadata doesn't exist. Free with `g_free()`.

[nullable]

Since: 1.0

### gtef_file_metadata_set ()

    void
    gtef_file_metadata_set (GtefFileMetadata *metadata,
                            const gchar *key,
                            const gchar *value);

Sets the value of a metadata. It's preferable that `key` starts with a namespace, to not get metadata conflicts between applications.

This function just stores the new metadata value in the `metadata` object memory.

#### Parameters

metadata | a GtefFileMetadata. |
key | the name of the metadata. |
value | the value of the metadata, or `NULL` to unset. | [nullable]

Since: 1.0

### gtef_file_metadata_load ()

    gboolean
    gtef_file_metadata_load (GtefFileMetadata *metadata,
                             GCancellable *cancellable,
                             GError **error);

Loads synchronously the metadata from “location”. The loaded metadata values can then be accessed with `gtef_file_metadata_get()`.

If the metadata are loaded successfully, this function deletes all previous metadata stored in the `metadata` object memory.

The file at “location”, if non-`NULL`, must exist on the filesystem, otherwise an error is returned.

If “location” is `NULL`, `FALSE` is simply returned.

#### Parameters

metadata | a GtefFileMetadata. |
cancellable | optional GCancellable object, `NULL` to ignore. | [nullable]
error | location to a `NULL` GError, or `NULL`. |

#### Returns

whether the metadata was loaded successfully.

Since: 1.0

### gtef_file_metadata_load_async ()

    void
    gtef_file_metadata_load_async (GtefFileMetadata *metadata,
                                   gint io_priority,
                                   GCancellable *cancellable,
                                   GAsyncReadyCallback callback,
                                   gpointer user_data);

The asynchronous version of `gtef_file_metadata_load()`.

If the metadata is loaded from the metadata manager (i.e. not with GVfs), this function loads the metadata synchronously. A future version might fix this.

See the GAsyncResult documentation to know how to use this function.

#### Parameters

metadata | a GtefFileMetadata. |
io_priority | the I/O priority of the request. E.g. `G_PRIORITY_LOW`, `G_PRIORITY_DEFAULT` or `G_PRIORITY_HIGH`. |
cancellable | optional GCancellable object, `NULL` to ignore. | [nullable]
callback | a GAsyncReadyCallback to call when the request is satisfied. | [scope async]
user_data | user data to pass to `callback` . |

Since: 1.0

### gtef_file_metadata_load_finish ()

    gboolean
    gtef_file_metadata_load_finish (GtefFileMetadata *metadata,
                                    GAsyncResult *result,
                                    GError **error);

Finishes the metadata loading started with `gtef_file_metadata_load_async()`.

#### Parameters

metadata | a GtefFileMetadata. |
result | a GAsyncResult. |
error | location to a `NULL` GError, or `NULL`. |

#### Returns

whether the metadata was loaded successfully.

Since: 1.0

### gtef_file_metadata_save ()

    gboolean
    gtef_file_metadata_save (GtefFileMetadata *metadata,
                             GCancellable *cancellable,
                             GError **error);

Saves synchronously the metadata for “location”.

The file at “location”, if non-`NULL`, must exist on the filesystem, otherwise an error is returned.

If “location” is `NULL`, `FALSE` is simply returned.

#### Parameters

metadata | a GtefFileMetadata. |
cancellable | optional GCancellable object, `NULL` to ignore. | [nullable]
error | location to a `NULL` GError, or `NULL`. |

#### Returns

whether the metadata was saved successfully.

Since: 1.0

### gtef_file_metadata_save_async ()

    void
    gtef_file_metadata_save_async (GtefFileMetadata *metadata,
                                   gint io_priority,
                                   GCancellable *cancellable,
                                   GAsyncReadyCallback callback,
                                   gpointer user_data);

The asynchronous version of `gtef_file_metadata_save()`.

If the metadata is saved with the metadata manager (i.e. not with GVfs), this function saves the metadata synchronously. A future version might fix this.

See the GAsyncResult documentation to know how to use this function.

#### Parameters

metadata | a GtefFileMetadata. |
io_priority | the I/O priority of the request. E.g. `G_PRIORITY_LOW`, `G_PRIORITY_DEFAULT` or `G_PRIORITY_HIGH`. |
cancellable | optional GCancellable object, `NULL` to ignore. | [nullable]
callback | a GAsyncReadyCallback to call when the request is satisfied. | [scope async]
user_data | user data to pass to `callback` . |

Since: 1.0

### gtef_file_metadata_save_finish ()

    gboolean
    gtef_file_metadata_save_finish (GtefFileMetadata *metadata,
                                    GAsyncResult *result,
                                    GError **error);

Finishes the metadata saving started with `gtef_file_metadata_save_async()`.

#### Parameters

metadata | a GtefFileMetadata. |
result | a GAsyncResult. |
error | location to a `NULL` GError, or `NULL`. |

#### Returns

whether the metadata was saved successfully.

Since: 1.0

## Types and Values

### GtefFileMetadata

    typedef struct _GtefFileMetadata GtefFileMetadata;

## Property Details

### The `“file”` property

      “file”                     GtefFile *

The GtefFile that the metadata belong to.

Flags: Read / Write / Construct Only

Since: 1.0