TeplMetadata: Tepl 5 Reference Manual

## TeplMetadata TeplMetadata — File metadata |

## Functions

TeplMetadata * | tepl_metadata_new ()
gchar * | tepl_metadata_get ()
void | tepl_metadata_set ()

## Types and Values

struct | TeplMetadata

## Object Hierarchy

        GObject
        ╰── TeplMetadata

## Includes

    #include <tepl/tepl.h>

## Description

A TeplMetadata object contains a set of file metadata as key/value pairs.

The `tepl_metadata_get()` and `tepl_metadata_set()` functions don't load or save the metadata on disk, they only access the metadata stored in the TeplMetadata object memory.

TeplMetadata is intended to be used alongside TeplMetadataManager to load and store the metadata on disk.

### Values requirements

Values must be nul-terminated UTF-8 strings.

### Keys requirements

Keys must be non-empty strings containing only:

- ASCII alphanumeric characters (see `g_ascii_isalnum()`);

- `'-'` characters (dashes);

- or `'_'` characters (underscores).

Additionally, it's preferable that keys start with a namespace, to not get metadata conflicts between the application and libraries.

Examples of valid metadata keys:

- `"gedit-spell-checking-language"`

- `"gCSVedit_column_delimiter"`

- `"tepl-character-encoding"`

## Functions

### tepl_metadata_new ()

    TeplMetadata *
    tepl_metadata_new (void);

#### Returns

a new, empty TeplMetadata object.

Since: 5.0

### tepl_metadata_get ()

    gchar *
    tepl_metadata_get (TeplMetadata *metadata,
                       const gchar *key);

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

`key` must follow the requirements explained in the class description.

#### Parameters

metadata | a TeplMetadata. |
key | a key. |

#### Returns

the associated value (a UTF-8 string), or `NULL`. Free with `g_free()` when no longer needed.

[transfer full][nullable]

Since: 5.0

### tepl_metadata_set ()

    void
    tepl_metadata_set (TeplMetadata *metadata,
                       const gchar *key,
                       const gchar *value);

Sets or unsets `key` . This function just stores the new metadata value in the `metadata` object memory.

`key` must follow the requirements explained in the class description.

#### Parameters

metadata | a TeplMetadata. |
key | a key. |
value | a nul-terminated UTF-8 string, or `NULL` to unset the key. | [nullable]

Since: 5.0

## Types and Values

### struct TeplMetadata

    struct TeplMetadata;