Data Settings API Reference (obs_data_t)

Data settings objects are reference-counted objects that store values in a string-table or array. They’re similar to Json objects, but additionally allow additional functionality such as default or auto-selection values. Data is saved/loaded to/from Json text and Json text files.

type obs_data_t

A reference-counted data object.

type obs_data_array_t

A reference-counted data array object.

#include <obs.h>

General Functions

obs_data_t *obs_data_create()
Returns:

A new reference to a data object. Release with obs_data_release().


obs_data_t *obs_data_create_from_json(const char *json_string)

Creates a data object from a Json string.

Parameters:
  • json_string – Json string

Returns:

A new reference to a data object. Release with obs_data_release().


obs_data_t *obs_data_create_from_json_file(const char *json_file)

Creates a data object from a Json file.

Parameters:
  • json_file – Json file path

Returns:

A new reference to a data object. Release with obs_data_release().


obs_data_t *obs_data_create_from_json_file_safe(const char *json_file, const char *backup_ext)

Creates a data object from a Json file, with a backup file in case the original is corrupted or fails to load.

Parameters:
  • json_file – Json file path

  • backup_ext – Backup file extension

Returns:

A new reference to a data object. Release with obs_data_release().


void obs_data_addref(obs_data_t *data)
void obs_data_release(obs_data_t *data)

Adds/releases a reference to a data object.


const char *obs_data_get_json(obs_data_t *data)

Generates a new json string. The string allocation is stored within the data object itself, and does not need to be manually freed.

Returns:

Json string for this object


const char *obs_data_get_json_with_defaults(obs_data_t *data)

Same as obs_data_get_json() but default values are also serialized.

Returns:

Json string for this object


const char *obs_data_get_json_pretty(obs_data_t *data)

Same as obs_data_get_json() but the JSON data is pretty-printed.

Returns:

Json string for this object


const char *obs_data_get_json_pretty_with_defaults(obs_data_t *data)

Same as obs_data_get_json_pretty() but default values are also serialized.

Returns:

Json string for this object


const char *obs_data_get_last_json(obs_data_t *data)

Returns the last json string generated for this data object. Does not generate a new string. Use obs_data_get_json() to generate a json string first.

Returns:

Json string for this object


bool obs_data_save_json(obs_data_t *data, const char *file)

Saves the data to a file as Json text.

Parameters:
  • file – The file to save to

Returns:

true if successful, false otherwise


bool obs_data_save_json_safe(obs_data_t *data, const char *file, const char *temp_ext, const char *backup_ext)

Saves the data to a file as Json text, and if overwriting an old file, backs up that old file to help prevent potential file corruption.

Parameters:
  • file – The file to save to

  • backup_ext – The backup extension to use for the overwritten file if it exists

Returns:

true if successful, false otherwise


void obs_data_apply(obs_data_t *target, obs_data_t *apply_data)

Merges the data of apply_data in to target.


void obs_data_erase(obs_data_t *data, const char *name)

Erases the user data for item name within the data object.


void obs_data_clear(obs_data_t *data)

Clears all user data in the data object.


Set Functions

void obs_data_set_string(obs_data_t *data, const char *name, const char *val)

void obs_data_set_int(obs_data_t *data, const char *name, long long val)

void obs_data_set_double(obs_data_t *data, const char *name, double val)

void obs_data_set_bool(obs_data_t *data, const char *name, bool val)

void obs_data_set_obj(obs_data_t *data, const char *name, obs_data_t *obj)

void obs_data_set_array(obs_data_t *data, const char *name, obs_data_array_t *array)

Get Functions

const char *obs_data_get_string(obs_data_t *data, const char *name)

long long obs_data_get_int(obs_data_t *data, const char *name)

double obs_data_get_double(obs_data_t *data, const char *name)

bool obs_data_get_bool(obs_data_t *data, const char *name)

obs_data_t *obs_data_get_obj(obs_data_t *data, const char *name)
Returns:

An incremented reference to a data object. Release with obs_data_release().


obs_data_array_t *obs_data_get_array(obs_data_t *data, const char *name)
Returns:

An incremented reference to a data array object. Release with obs_data_array_release().


Default Value Functions

Default values are used to determine what value will be given if a value is not set.

obs_data_t *obs_data_get_defaults(obs_data_t *data);
Returns:

obs_data_t * with all default values (recursively for all objects as well).


void obs_data_set_default_string(obs_data_t *data, const char *name, const char *val)
const char *obs_data_get_default_string(obs_data_t *data, const char *name)

void obs_data_set_default_int(obs_data_t *data, const char *name, long long val)
long long obs_data_get_default_int(obs_data_t *data, const char *name)

void obs_data_set_default_double(obs_data_t *data, const char *name, double val)
double obs_data_get_default_double(obs_data_t *data, const char *name)

void obs_data_set_default_bool(obs_data_t *data, const char *name, bool val)
bool obs_data_get_default_bool(obs_data_t *data, const char *name)

void obs_data_set_default_obj(obs_data_t *data, const char *name, obs_data_t *obj)
obs_data_t *obs_data_get_default_obj(obs_data_t *data, const char *name)
Returns:

An incremented reference to a data object. Release with obs_data_release().


void obs_data_set_default_array(obs_data_t *data, const char *name, obs_data_array_t *arr)
obs_data_array_t *obs_data_get_default_array(obs_data_t *data, const char *name)

Autoselect Functions

Autoselect values are optionally used to determine what values should be used to ensure functionality if the currently set values are inappropriate or invalid.

void obs_data_set_autoselect_string(obs_data_t *data, const char *name, const char *val)
const char *obs_data_get_autoselect_string(obs_data_t *data, const char *name)

void obs_data_set_autoselect_int(obs_data_t *data, const char *name, long long val)
long long obs_data_get_autoselect_int(obs_data_t *data, const char *name)

void obs_data_set_autoselect_double(obs_data_t *data, const char *name, double val)
double obs_data_get_autoselect_double(obs_data_t *data, const char *name)

void obs_data_set_autoselect_bool(obs_data_t *data, const char *name, bool val)
bool obs_data_get_autoselect_bool(obs_data_t *data, const char *name)

void obs_data_set_autoselect_obj(obs_data_t *data, const char *name, obs_data_t *obj)
obs_data_t *obs_data_get_autoselect_obj(obs_data_t *data, const char *name)
Returns:

An incremented reference to a data object. Release with obs_data_release().


void obs_data_set_autoselect_array(obs_data_t *data, const char *name, obs_data_array_t *arr)
obs_data_array_t *obs_data_get_autoselect_array(obs_data_t *data, const char *name)
Returns:

An incremented reference to a data array object. Release with obs_data_array_release().

Added in version 30.1.


Array Functions

obs_data_array_t *obs_data_array_create()
Returns:

A new reference to a data array object. Release with obs_data_array_release().


void obs_data_array_addref(obs_data_array_t *array)

void obs_data_array_release(obs_data_array_t *array)

size_t obs_data_array_count(obs_data_array_t *array)

obs_data_t *obs_data_array_item(obs_data_array_t *array, size_t idx)
Returns:

An incremented reference to the data object associated with this array entry. Release with obs_data_release().


size_t obs_data_array_push_back(obs_data_array_t *array, obs_data_t *obj)

void obs_data_array_insert(obs_data_array_t *array, size_t idx, obs_data_t *obj)

void obs_data_array_erase(obs_data_array_t *array, size_t idx)