## PtConfig

PtConfig — Configuration for ASR plugins

## Functions

PtConfig * | pt_config_new ()
gboolean | pt_config_is_valid ()
gboolean | pt_config_is_installed ()
gboolean | pt_config_apply ()
GFile * | pt_config_get_file ()
void | pt_config_set_file ()
gchar * | pt_config_get_name ()
gboolean | pt_config_set_name ()
gchar * | pt_config_get_base_folder ()
gboolean | pt_config_set_base_folder ()
gchar * | pt_config_get_plugin ()
gchar * | pt_config_get_lang_code ()
gchar * | pt_config_get_lang_name ()
gchar * | pt_config_get_key ()

## Properties

GFile * | file | Read / Write / Construct Only
gboolean | is-installed | Read
gboolean | is-valid | Read
char * | name | Read

## Types and Values

struct | PtConfig
enum | PtError

## Object Hierarchy

        GObject
        ╰── PtConfig

## Includes

    #include <parlatype/pt-config.h>

## Description

A PtConfig represents a configuration for a GStreamer ASR plugin. Configuration files are written in .ini-like style. Each file holds one configuration that is used to instantiate a PtConfig.

Its main use is to be applied to a GStreamer plugin.

PtConfig is used for reading configurations in, not for writing them. To add your own configuration, edit it yourself. Learn more about the file format in the description of GKeyFile in general and in `pt_config_is_valid()` in particular.

To delete a configuration, get its “file” property, delete the file and unref the config object.

## Functions

### pt_config_new ()

    PtConfig *
    pt_config_new (GFile *file);

Returns a new configuration instance for the given file. The configuration is immediately checked for formal validity. This can be queried with `pt_config_is_valid()` or the property “is-valid”. The property doesn’t change anymore.

If the configuration is not valid, all methods are no-operations and return FALSE or NULL.

After use `g_object_unref()` it.

#### Parameters

file | a file with configuration settings in .ini-like format. | [not nullable]

#### Returns

a new PtConfig.

[transfer full]

Since: 3.0

### pt_config_is_valid ()

    gboolean
    pt_config_is_valid (PtConfig *config);

Checks if a configuration is formally valid:

- It has a version string of the form 1.x (major.minor). Major versions higher than 1 are not understood by this version of libparlatype. Minor numbers are supposed to be compatible and are checked only for existence

- It has the following groups: [Model], [Files]. A [Parameters] group is optional.

- [Model] has the following keys: Name, Plugin, BaseFolder, Language.

- [Files] has at least one key.

- All keys have non-empty values, except BaseFolder, which might be empty.

What is not tested:

- Optional (URL) or unknown groups or keys

- Order of groups and keys.

- If BaseFolder is set.

- If the language code exists.

- If files and paths in [Files] are formally valid (relative paths with a slash as separator, e.g. subdir/subdir/file.name)

- If files and paths exist on the file system.

- If the plugin is installed.

- If the plugin supports given parameters.

#### Parameters

config | the configuration to test |

#### Returns

TRUE for a formally valid configuration, otherwise FALSE

Since: 3.0

### pt_config_is_installed ()

    gboolean
    pt_config_is_installed (PtConfig *config);

Checks whether the model is installed, that means the base folder exists and all files listed in the configuration are located inside the base folder.

#### Parameters

config | a configuration instance |

#### Returns

TRUE for an installed model, otherwise FALSE

Since: 3.0

### pt_config_apply ()

    gboolean
    pt_config_apply (PtConfig *config,
                     GObject *plugin,
                     GError **error);

Applies a configuration to a GStreamer plugin.

#### Parameters

config | a configuration instance |
plugin | the GStreamer ASR plugin |
error | return location for an error, or NULL. | [nullable]

#### Returns

TRUE on success, FALSE if a parameter could not be set

Since: 3.0

### pt_config_get_file ()

    GFile *
    pt_config_get_file (PtConfig *config);

The GFile that storing the configuration.

#### Parameters

config | a configuration instance |

#### Returns

the file this object is based on.

[transfer none]

Since: 3.0

### pt_config_set_file ()

    void
    pt_config_set_file (PtConfig *config,
                        GFile *file);

Sets a new file, invalidating all fields and reevaluating status.

#### Parameters

config | a configuration instance |
file | the new file |

Since: 3.0

### pt_config_get_name ()

    gchar *
    pt_config_get_name (PtConfig *config);

The human-visible name to identify a configuration.

#### Parameters

config | a configuration instance |

#### Returns

the configuration’s name as a string.

[transfer none]

Since: 3.0

### pt_config_set_name ()

    gboolean
    pt_config_set_name (PtConfig *config,
                        gchar *name);

Sets the human-visible name of a configuration. It doesn’t have to be unique. This saves the new name immediately to the configuration file.

#### Parameters

config | a configuration instance |
name | the new name |

#### Returns

TRUE on success, otherwise FALSE

Since: 3.0

### pt_config_get_base_folder ()

    gchar *
    pt_config_get_base_folder (PtConfig *config);

Gets the configuration’s base folder. If the model is not installed, the base folder is not set and the return value is NULL. Another reason for returning NULL is an invalid configuration, check “is-valid” for that.

#### Parameters

config | a configuration instance |

#### Returns

the configuaration’s base folder as a string or NULL.

[transfer none]

Since: 3.0

### pt_config_set_base_folder ()

    gboolean
    pt_config_set_base_folder (PtConfig *config,
                               gchar *name);

Sets the configuration’s base folder.

#### Parameters

config | a configuration instance |
name | the new base folder |

#### Returns

TRUE on success, otherwise FALSE

Since: 3.0

### pt_config_get_plugin ()

    gchar *
    pt_config_get_plugin (PtConfig *config);

Gets the name of the GStreamer plugin the configuration is intended for. It has to be exactly the string GStreamer uses to instantiate the plugin.

#### Parameters

config | a configuration instance |

#### Returns

the plugin’s name as a string

Since: 3.0

### pt_config_get_lang_code ()

    gchar *
    pt_config_get_lang_code (PtConfig *config);

Gets the language the model was made for. It’s the ISO 639-1 code (2 letters) if available, otherwise ISO 639-2 (3 letters).

#### Parameters

config | a configuration instance |

#### Returns

the language code as a string.

[transfer none]

Since: 3.0

### pt_config_get_lang_name ()

    gchar *
    pt_config_get_lang_name (PtConfig *config);

Gets the localized name of the language the model was made for.

#### Parameters

config | a configuration instance |

#### Returns

the language code as a string.

[transfer none]

Since: 3.0

### pt_config_get_key ()

    gchar *
    pt_config_get_key (PtConfig *config,
                       gchar *key);

Get other optional keys in the [Model] group. All keys are assumed to be strings. If the key is not set, NULL is returned.

#### Parameters

config | a configuration instance |
key | the name of a key in the [Model] group |

#### Returns

the key’s value as a string or NULL.

[transfer full]

Since: 3.0

## Types and Values

### struct PtConfig

    struct PtConfig;

PtConfig contains only private fields and should not be directly accessed.

### enum PtError

Error codes for Parlatype in the PT_ERROR domain.

#### Members

PT_ERROR_PLUGIN_MISSING_PROPERTY | The plugin doesn’t have a property. |
PT_ERROR_PLUGIN_NOT_WRITABLE | The plugin’s property is not writable. |
PT_ERROR_PLUGIN_WRONG_VALUE | The value is not valid for the property. |

## Property Details

### The `“file”` property

      “file”                     GFile *

The file that was used to construct the object and contains the configuration settings. This property is immutable and the file can not be reloaded.

Owner: PtConfig

Flags: Read / Write / Construct Only

### The `“is-installed”` property

      “is-installed”             gboolean

Indicates whether the language model is installed.

Owner: PtConfig

Flags: Read

Default value: FALSE

### The `“is-valid”` property

      “is-valid”                 gboolean

Indicates whether the configuration is formally valid. See `pt_config_is_valid()` for the checks done. This property is available from the very beginning and is immutable. You can not recover from an invalid state.

Owner: PtConfig

Flags: Read

Default value: FALSE

### The `“name”` property

      “name”                     char *

The display name for the model.

Owner: PtConfig

Flags: Read

Default value: NULL