TeplFileMetadata: Tepl 3 Reference Manual

## TeplFileMetadata TeplFileMetadata — File metadata |

## Functions

TeplFileMetadata * | tepl_file_metadata_new ()
TeplFile * | tepl_file_metadata_get_file ()
gchar * | tepl_file_metadata_get ()
void | tepl_file_metadata_set ()
gboolean | tepl_file_metadata_load ()
void | tepl_file_metadata_load_async ()
gboolean | tepl_file_metadata_load_finish ()
gboolean | tepl_file_metadata_save ()
void | tepl_file_metadata_save_async ()
gboolean | tepl_file_metadata_save_finish ()

## Properties

TeplFile * | file | Read / Write / Construct Only

## Types and Values

| TeplFileMetadata

## Object Hierarchy

        GObject
        ╰── TeplFileMetadata

## Includes

    #include <tepl/tepl.h>

## Description

A TeplFileMetadata object stores the metadata of a TeplFile. You need to call `tepl_metadata_manager_init()` and `tepl_metadata_manager_shutdown()` in your application, in case GVfs metadata are not supported.

The `tepl_file_metadata_get()` and `tepl_file_metadata_set()` functions don't load or save the metadata on disk. They only access the metadata stored in the TeplFileMetadata object memory. To load the metadata from disk, call `tepl_file_metadata_load()` or its async variant. Likewise, to save the metadata on disk, call `tepl_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 TeplFileMetadata object memory. But the metadata are not automatically saved for the new location.

## Functions

### tepl_file_metadata_new ()

    TeplFileMetadata *
    tepl_file_metadata_new (TeplFile *file);

#### Parameters

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

#### Returns

a new TeplFileMetadata object.

Since: 1.0

### tepl_file_metadata_get_file ()

    TeplFile *
    tepl_file_metadata_get_file (TeplFileMetadata *metadata);

#### Parameters

metadata | a TeplFileMetadata object. |

#### Returns

the TeplFile that the metadata belong to.

[transfer none]

Since: 1.0

### tepl_file_metadata_get ()

    gchar *
    tepl_file_metadata_get (TeplFileMetadata *metadata,
                            const gchar *key);

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

#### Parameters

metadata | a TeplFileMetadata. |
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

### tepl_file_metadata_set ()

    void
    tepl_file_metadata_set (TeplFileMetadata *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 TeplFileMetadata. |
key | the name of the metadata. |
value | the value of the metadata, or `NULL` to unset. | [nullable]

Since: 1.0

### tepl_file_metadata_load ()

    gboolean
    tepl_file_metadata_load (TeplFileMetadata *metadata,
                             GCancellable *cancellable,
                             GError **error);

Loads synchronously the metadata from “location”. The loaded metadata values can then be accessed with `tepl_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 TeplFileMetadata. |
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

### tepl_file_metadata_load_async ()

    void
    tepl_file_metadata_load_async (TeplFileMetadata *metadata,
                                   gint io_priority,
                                   GCancellable *cancellable,
                                   GAsyncReadyCallback callback,
                                   gpointer user_data);

The asynchronous version of `tepl_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 TeplFileMetadata. |
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

### tepl_file_metadata_load_finish ()

    gboolean
    tepl_file_metadata_load_finish (TeplFileMetadata *metadata,
                                    GAsyncResult *result,
                                    GError **error);

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

#### Parameters

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

#### Returns

whether the metadata was loaded successfully.

Since: 1.0

### tepl_file_metadata_save ()

    gboolean
    tepl_file_metadata_save (TeplFileMetadata *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 TeplFileMetadata. |
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

### tepl_file_metadata_save_async ()

    void
    tepl_file_metadata_save_async (TeplFileMetadata *metadata,
                                   gint io_priority,
                                   GCancellable *cancellable,
                                   GAsyncReadyCallback callback,
                                   gpointer user_data);

The asynchronous version of `tepl_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 TeplFileMetadata. |
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

### tepl_file_metadata_save_finish ()

    gboolean
    tepl_file_metadata_save_finish (TeplFileMetadata *metadata,
                                    GAsyncResult *result,
                                    GError **error);

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

#### Parameters

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

#### Returns

whether the metadata was saved successfully.

Since: 1.0

## Types and Values

### TeplFileMetadata

    typedef struct _TeplFileMetadata TeplFileMetadata;

## Property Details

### The `“file”` property

      “file”                     TeplFile *

The TeplFile that the metadata belong to.

Flags: Read / Write / Construct Only

Since: 1.0