# Settings

struct WpSettingsSpec

  WpSettingSpec holds the specification of a setting.

struct WpSettingsItem

  WpSettingsItem holds the key and value of a setting

struct WpSettings

  WpSettings loads and parses the "sm-settings" (default value) metadata, which contains wireplumber settings, and provides APIs to its clients (modules, lua scripts etc) to access them.

  Being a WpObject subclass, the settings inherits WpObject's activation system.

enum WpSettingsSpecType

  The different spec types of a setting.

  Values:

  enumerator WP_SETTINGS_SPEC_TYPE_UNKNOWN
  enumerator WP_SETTINGS_SPEC_TYPE_BOOL
  enumerator WP_SETTINGS_SPEC_TYPE_INT
  enumerator WP_SETTINGS_SPEC_TYPE_FLOAT
  enumerator WP_SETTINGS_SPEC_TYPE_STRING
  enumerator WP_SETTINGS_SPEC_TYPE_ARRAY
  enumerator WP_SETTINGS_SPEC_TYPE_OBJECT

enum WpSettingsFeatures

  Flags to be used as WpObjectFeatures on WpSettings subclasses.

  Values:

  enumerator WP_SETTINGS_LOADED = (1 << 0)

    Loads the settings

typedef void (*WpSettingsChangedCallback)(WpSettings *obj, const gchar *setting, WpSpaJson *value, gpointer user_data)

  callback conveying the changed setting and its json value

  Param obj:

    the wpsettings object

  Param setting:

    the changed setting

  Param value:

    json value of the the changed setting

  Param user_data:

    data passed in the wp_settings_subscribe

WpSettingsSpec *wp_settings_spec_ref(WpSettingsSpec *self)

  Increases the reference count of a settings spec object.

  Parameters:

    - self -- a settings spec object

  Returns:

    (transfer full): self with an additional reference count on it

void wp_settings_spec_unref(WpSettingsSpec *self)

  Decreases the reference count on self and frees it when the ref count reaches zero.

  Parameters:

    - self -- (transfer full): a settings spec object

const gchar *wp_settings_spec_get_name(WpSettingsSpec *self)

  Gets the human-readable name of a settings spec.

  Parameters:

    - self -- the settings spec object

  Returns:

    (nullable): the human-readable name of the settings spec, or NULL if none

const gchar *wp_settings_spec_get_description(WpSettingsSpec *self)

  Gets the description of a settings spec.

  Parameters:

    - self -- the settings spec object

  Returns:

    the description of the settings spec

WpSettingsSpecType wp_settings_spec_get_value_type(WpSettingsSpec *self)

  Gets the type of a settings spec.

  Parameters:

    - self -- the settings spec object

  Returns:

    the type of the settings spec

WpSpaJson *wp_settings_spec_get_default_value(WpSettingsSpec *self)

  Gets the default value of a settings spec.

  Parameters:

    - self -- the settings spec object

  Returns:

    (transfer full): the default value of the settings spec

WpSpaJson *wp_settings_spec_get_min_value(WpSettingsSpec *self)

  Gets the minimum value of a settings spec.

  Parameters:

    - self -- the settings spec object

  Returns:

    (transfer full)(nullable): the minimum value of the settings spec, or NULL if the spec type is not WP_SETTINGS_SPEC_TYPE_INT or WP_SETTINGS_SPEC_TYPE_FLOAT

WpSpaJson *wp_settings_spec_get_max_value(WpSettingsSpec *self)

  Gets the maximum value of a settings spec.

  Parameters:

    - self -- the settings spec object

  Returns:

    (transfer full)(nullable): the maximum value of the settings spec, or NULL if the spec type is not WP_SETTINGS_SPEC_TYPE_INT or WP_SETTINGS_SPEC_TYPE_FLOAT

gboolean wp_settings_spec_check_value(WpSettingsSpec *self, WpSpaJson *value)

  Checks whether a value is compatible with the spec or not.

  Parameters:

    - self -- the settings spec object

    - value -- (transfer none): the value to check

  Returns:

    TRUE if the value is compatible with the spec, FALSE otherwise

WpSettingsItem *wp_settings_item_ref(WpSettingsItem *self)

  Increases the reference count of a settings item object.

  Parameters:

    - self -- a settings item object

  Returns:

    (transfer full): self with an additional reference count on it

void wp_settings_item_unref(WpSettingsItem *self)

  Decreases the reference count on self and frees it when the ref count reaches zero.

  Parameters:

    - self -- (transfer full): a settings item object

const gchar *wp_settings_item_get_key(WpSettingsItem *self)

  Gets the key from a settings item.

  Parameters:

    - self -- the item held by the GValue that was returned from the WpIterator of wp_settings_new_iterator()

  Returns:

    (transfer none): the settings key of the item

WpSpaJson *wp_settings_item_get_value(WpSettingsItem *self)

  Gets the value from a settings item.

  Parameters:

    - self -- the item held by the GValue that was returned from the WpIterator of wp_settings_new_iterator()

  Returns:

    (transfer full): the settings value of the item

WpSettings *wp_settings_new(WpCore *core, const gchar *metadata_name)

  Creates a new WpSettings object.

  Parameters:

    - core -- the WpCore

    - metadata_name -- (nullable): the name of the metadata object to associate with the settings object; NULL means the default "sm-settings"

  Returns:

    (transfer full): a new WpSettings object

WpSettings *wp_settings_find(WpCore *core, const gchar *metadata_name)

  Finds a registered WpSettings object by its metadata name.

  Parameters:

    - core -- the WpCore

    - metadata_name -- (nullable): the name of the metadata object that the settings object is associated with; NULL returns the first settings object that is found

  Returns:

    (transfer full) (nullable): the WpSettings object, or NULL if not found

guintptr wp_settings_subscribe(WpSettings *self, const gchar *pattern, WpSettingsChangedCallback callback, gpointer user_data)

  Subscribes callback for a given setting pattern(a glob-style pattern matched using g_pattern_match_simple), this allows clients to look for any changes made in settings through metadata.

  Parameters:

    - self -- the settings object

    - pattern -- name of the pattern to match the settings with

    - callback -- (scope async): the callback triggered when the settings change.

    - user_data -- data to pass to callback

  Returns:

    the subscription ID (always greater than 0 for successful subscriptions)

guintptr wp_settings_subscribe_closure(WpSettings *self, const gchar *pattern, GClosure *closure)

  Subscribes callback for a given setting pattern(a glob-style pattern matched using g_pattern_match_simple), this allows clients to look for any changes made in settings through metadata.

  Parameters:

    - self -- the settings object

    - pattern -- name of the pattern to match the settings with

    - closure -- (nullable): a GAsyncReadyCallback wrapped in a GClosure

  Returns:

    the subscription ID (always greater than 0 for success)

gboolean wp_settings_unsubscribe(WpSettings *self, guintptr subscription_id)

  Unsubscribes callback for a given subscription_id.

  Parameters:

    - self -- the settings object

    - subscription_id -- identifies the callback

  Returns:

    TRUE if success, FALSE otherwise

WpSpaJson *wp_settings_get(WpSettings *self, const gchar *name)

  Gets the WpSpaJson value of a setting.

  Parameters:

    - self -- the settings object

    - name -- the name of the setting

  Returns:

    (transfer full) (nullable): The WpSpaJson value of the setting, or NULL if the setting does not exist

WpSpaJson *wp_settings_get_saved(WpSettings *self, const gchar *name)

  Gets the WpSpaJson saved value of a setting.

  Parameters:

    - self -- the settings object

    - name -- the name of the setting

  Returns:

    (transfer full) (nullable): The WpSpaJson saved value of the setting, or NULL if the setting does not exist

WpSettingsSpec *wp_settings_get_spec(WpSettings *self, const gchar *name)

  Gets the specification of a setting.

  Parameters:

    - self -- the settings object

    - name -- the name of the setting

  Returns:

    (transfer full) (nullable): the specification of the setting

gboolean wp_settings_set(WpSettings *self, const gchar *name, WpSpaJson *value)

  Sets a new setting value.

  Parameters:

    - self -- the settings object

    - name -- the name of the setting

    - value -- (transfer none): the JSON value of the setting

  Returns:

    TRUE if the setting could be set, FALSE otherwise

gboolean wp_settings_reset(WpSettings *self, const char *name)

  Resets the setting to its default value.

  Parameters:

    - self -- the settings object

    - name -- the name of the setting to reset

  Returns:

    TRUE if the setting could be reset, FALSE otherwise

gboolean wp_settings_save(WpSettings *self, const char *name)

  Saves a setting to make it persistent after reboot.

  Parameters:

    - self -- the settings object

    - name -- the name of the setting to be saved

  Returns:

    TRUE if the setting could be saved, FALSE otherwise

gboolean wp_settings_delete(WpSettings *self, const char *name)

  Deletes a saved setting to not make it persistent after reboot.

  Parameters:

    - self -- the settings object

    - name -- the name of the saved setting to be deleted

  Returns:

    TRUE if the setting could be deleted, FALSE otherwise

void wp_settings_reset_all(WpSettings *self)

  Resets all the settings to their default value.

  Parameters:

    - self -- the settings object

void wp_settings_save_all(WpSettings *self)

  Saves all the settings to make them persistent after reboot.

  Parameters:

    - self -- the settings object

void wp_settings_delete_all(WpSettings *self)

  Deletes all saved setting to not make them persistent after reboot.

  Parameters:

    - self -- the settings object

WpIterator *wp_settings_new_iterator(WpSettings *self)

  Iterates over settings.

  Parameters:

    - self -- the settings object

  Returns:

    (transfer full): an iterator that iterates over the settings.

WP_TYPE_SETTINGS_SPEC (wp_settings_spec_get_type ())

  The WpSettingsSpec GType.

WP_TYPE_SETTINGS_ITEM (wp_settings_item_get_type ())

  The WpSettingsItem GType.

WP_TYPE_SETTINGS (wp_settings_get_type ())

  The WpSettings GType.