TeplMetadataManager: Tepl 5 Reference Manual

## TeplMetadataManager TeplMetadataManager — To store file metadata on disk |

## Functions

TeplMetadataManager * | tepl_metadata_manager_get_singleton ()
void | tepl_metadata_manager_trim ()
gboolean | tepl_metadata_manager_load_from_disk ()
gboolean | tepl_metadata_manager_save_to_disk ()
void | tepl_metadata_manager_copy_from ()
void | tepl_metadata_manager_merge_into ()

## Types and Values

struct | TeplMetadataManager

## Object Hierarchy

        GObject
        ╰── TeplMetadataManager

## Includes

    #include <tepl/tepl.h>

## Description

TeplMetadataManager permits to store file metadata on disk. It serves both as an easier replacement for GVfs metadata, and to have metadata support on platforms that don't support GVfs metadata.

For the GFile where the metadata are stored (see the `tepl_metadata_manager_load_from_disk()` and `tepl_metadata_manager_save_to_disk()` functions), the following applies:

- A good place to store the metadata is in a sub-directory of the user data directory. See `g_get_user_data_dir()`.

- The GFile must be different for each process. It is advised for your application to rely on GApplication process uniqueness. TeplMetadataManager doesn't support concurrent accesses to the same GFile from different processes. Which means that metadata cannot be shared between applications.

### High-level API

TeplMetadataManager and TeplMetadata are integrated in the Tepl framework, see:

- tepl_application_handle_metadata().

- the metadata API of TeplBuffer.

## Functions

### tepl_metadata_manager_get_singleton ()

    TeplMetadataManager *
    tepl_metadata_manager_get_singleton (void);

#### Returns

the TeplMetadataManager singleton instance.

[transfer none]

Since: 5.0

### tepl_metadata_manager_trim ()

    void
    tepl_metadata_manager_trim (TeplMetadataManager *manager,
                                gint max_number_of_locations);

The purpose of having a maximum size is to avoid that the file on disk grows indefinitely.

`max_number_of_locations` is the maximum number of GFile locations for which metadata are kept. This function discards the least recently accessed metadata if needed.

If `max_number_of_locations` is -1, a default internal value is used that should fit most applications' needs.

#### Parameters

manager | the TeplMetadataManager. |
max_number_of_locations | the maximum size, or -1 for the default value. |

Since: 5.0

### tepl_metadata_manager_load_from_disk ()

    gboolean
    tepl_metadata_manager_load_from_disk (TeplMetadataManager *manager,
                                          GFile *from_file,
                                          GError **error);

Loads synchronously all the metadata from `from_file` into `manager` .

A good moment to call this function is on application startup, see the “startup” signal.

#### Parameters

manager | the TeplMetadataManager. |
from_file | the GFile to load metadata from. |
error | location to a `NULL` GError, or `NULL`. |

#### Returns

whether the operation was successful.

Since: 5.0

### tepl_metadata_manager_save_to_disk ()

    gboolean
    tepl_metadata_manager_save_to_disk (TeplMetadataManager *manager,
                                        GFile *to_file,
                                        gboolean trim,
                                        GError **error);

Saves synchronously all the metadata from `manager` to `to_file` . The parent directories of `to_file` are created if needed.

A good moment to call this function is on application shutdown, see the “shutdown” signal.

#### Parameters

manager | the TeplMetadataManager. |
to_file | the GFile to save metadata to. |
trim | if `TRUE`, `tepl_metadata_manager_trim()` is called with -1. |
error | location to a `NULL` GError, or `NULL`. |

#### Returns

whether the operation was successful.

Since: 5.0

### tepl_metadata_manager_copy_from ()

    void
    tepl_metadata_manager_copy_from (TeplMetadataManager *from_manager,
                                     GFile *for_location,
                                     TeplMetadata *to_metadata);

Copies the metadata stored in `from_manager` for `for_location` into `to_metadata` .

If `to_metadata` already contains a key that is also present in `from_manager` , the value in `to_metadata` is overwritten.

If `to_metadata` already contains a key that is not present in `from_manager` , the key/value pair is kept in `to_metadata` , it is not erased.

#### Parameters

from_manager | the TeplMetadataManager. |
for_location | a GFile. |
to_metadata | a TeplMetadata. |

Since: 5.0

### tepl_metadata_manager_merge_into ()

    void
    tepl_metadata_manager_merge_into (TeplMetadataManager *into_manager,
                                      GFile *for_location,
                                      TeplMetadata *from_metadata);

Merges the metadata from `from_metadata` into `into_manager` for `for_location` .

If a key from `from_metadata` has been set to `NULL`, the key/value pair is removed from `into_manager` . In other words that key/value pair will not be saved at all when calling `tepl_metadata_manager_save_to_disk()`.

If `into_manager` already contains a key that is not present in `from_metadata` , the key/value pair is kept in `into_manager` , it is not erased.

#### Parameters

into_manager | the TeplMetadataManager. |
for_location | a GFile. |
from_metadata | a TeplMetadata. |

Since: 5.0

## Types and Values

### struct TeplMetadataManager

    struct TeplMetadataManager;