State Storage

digraph inheritance { rankdir=LR; GObject -> WpState; GObject -> WpObject -> WpStateMetadata; }

struct WpState

The WpState class saves and loads properties from a file

GObject Properties

name

The file name where the state will be stored.

gchar *

G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY

enum WpStateMetadataFeatures

Flags to be used as WpObjectFeatures on WpStateMetadata.

Values:

enumerator WP_STATE_METADATA_LOADED = (1 << 0)

Loads the state metadata

WpState *wp_state_new(const gchar *name)

Constructs a new state object.

Parameters:

  • name -- the state name

Returns:

(transfer full): the new WpState

const gchar *wp_state_get_name(WpState *self)

Gets the name of a state object.

Parameters:

  • self -- the state

Returns:

the name of this state

const gchar *wp_state_get_location(WpState *self)

Gets the location of a state object.

Parameters:

  • self -- the state

Returns:

the location of this state

void wp_state_clear(WpState *self)

Clears the state removing its file.

Parameters:

  • self -- the state

gboolean wp_state_save(WpState *self, WpProperties *props, GError **error)

Saves new properties in the state, overwriting all previous data.

Parameters:

  • self -- the state

  • props -- (transfer none): the properties to save

  • error -- (out)(optional): return location for a GError, or NULL

Returns:

TRUE if the properties could be saved, FALSE otherwise

void wp_state_save_after_timeout(WpState *self, WpCore *core, WpProperties *props)

Saves new properties in the state, overwriting all previous data, after a timeout.

This is similar to wp_state_save() but it will save the state after a timeout has elapsed. If the state is saved again before the timeout elapses, the timeout is reset.

This function is useful to avoid saving the state too often. When called consecutively, it will save the state only once. Every time it is called, it will cancel the previous timer and start a new one, resulting in timing out only after the last call.

Since

0.5.0

Parameters:

  • self -- the state

  • core -- the core, used to add the timeout callback to the main loop

  • props -- (transfer none): the properties to save. This object will be referenced and kept alive until the timeout elapses, but not deep copied.

WpProperties *wp_state_load(WpState *self)

Loads the state data from the file system.

This function will never fail. If it cannot load the state, for any reason, it will simply return an empty WpProperties, behaving as if there was no previous state stored.

Parameters:

  • self -- the state

Returns:

(transfer full): a new WpProperties containing the state data

WP_TYPE_STATE (wp_state_get_type ())

The WpState GType.

struct WpStateMetadata

The WpStateMetadata class saves and loads properties from a file and reflects the state in a metadata object.

GObject Properties

name

The file name where the state will be stored.

gchar *

G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY

WpStateMetadata *wp_state_metadata_new(WpCore *core, const gchar *name)

Constructs a new state metadata object.

Parameters:

  • core -- the core associated with the state metadata

  • name -- the state metadata name

Returns:

(transfer full): the new WpStateMetadata

const gchar *wp_state_metadata_get_name(WpStateMetadata *self)

Gets the name of a state metadata object.

Parameters:

  • self -- the state metadata

Returns:

the name of this state metadata

const gchar *wp_state_metadata_get_location(WpStateMetadata *self)

Gets the location of a state metadata object.

Parameters:

  • self -- the state metadata

Returns:

the location of this state metadata

void wp_state_metadata_clear(WpStateMetadata *self)

Clears the state metadata and removes its file.

If the state metadata has not been loaded, this won't do anything.

Parameters:

  • self -- the state metadata

const gchar *wp_state_metadata_get(WpStateMetadata *self, const gchar *key)

Gets a value from the state metadata.

If the state metadata has not been loaded, this won't do anything.

Parameters:

  • self -- the state metadata

  • key -- the key of the value

Returns:

the value from the state metadata, or NULL if not found.

void wp_state_metadata_set(WpStateMetadata *self, const gchar *key, const gchar *value)

Sets a value into the state metadata.

If value is NULL, it will unset the given key. Note that this will also save the state after the timeout has elapsed.

If the state metadata has not been loaded, this won't do anything.

Parameters:

  • self -- the metadata object

  • key -- the key to set.

  • value -- (nullable): the value to set, or NULL to unset the given key

WP_TYPE_STATE_METADATA (wp_state_metadata_get_type ())

The WpStateMetadata GType.