Callback API Reference (libobs/callback)

Calldata

The calldata_t object is used to pass parameters from signal handlers or to procedure handlers.

type calldata_t

void calldata_init(calldata_t *data)

Initializes a calldata structure (zeroes it).

Parameters

data – Calldata structure

void calldata_free(calldata_t *data)

Frees a calldata structure. Should only be used if calldata_init() was used. If the object is received as a callback parameter, this function should not be used.

Parameters

data – Calldata structure

void calldata_set_int(calldata_t *data, const char *name, long long val)

Sets an integer parameter.

Parameters

data – Calldata structure
name – Parameter name
val – Integer value

void calldata_set_float(calldata_t *data, const char *name, double val)

Sets a floating point parameter.

Parameters

data – Calldata structure
name – Parameter name
val – Floating point value

void calldata_set_bool(calldata_t *data, const char *name, bool val)

Sets a boolean parameter.

Parameters

data – Calldata structure
name – Parameter name
val – Boolean value

void calldata_set_ptr(calldata_t *data, const char *name, void *ptr)

Sets a pointer parameter.

Parameters

data – Calldata structure
name – Parameter name
val – Pointer value

void calldata_set_string(calldata_t *data, const char *name, const char *str)

Sets a string parameter.

Parameters

data – Calldata structure
name – Parameter name
val – String

long long calldata_int(const calldata_t *data, const char *name)

Gets an integer parameter.

Parameters

data – Calldata structure
name – Parameter name

Returns

Integer value

double calldata_float(const calldata_t *data, const char *name)

Gets a floating point parameter.

Parameters

data – Calldata structure
name – Parameter name

Returns

Floating point value

bool calldata_bool(const calldata_t *data, const char *name)

Gets a boolean parameter.

Parameters

data – Calldata structure
name – Parameter name

Returns

Boolean value

void *calldata_ptr(const calldata_t *data, const char *name)

Gets a pointer parameter. For example, Core OBS Signals that have ptr source as a parameter requires this function to get the pointer, which can be casted to obs_source_t. Does not have to be freed.

Parameters

data – Calldata structure
name – Parameter name

Returns

Pointer value

const char *calldata_string(const calldata_t *data, const char *name)

Gets a string parameter.

Parameters

data – Calldata structure
name – Parameter name

Returns

String value

Signals

Signals are used for all event-based callbacks.

#include <callback/signal.h>

type signal_handler_t

typedef void (*signal_callback_t)(void *data, calldata_t *cd)

Signal callback.

Param data: Private data passed to this callback
Param cd: Calldata object

signal_handler_t *signal_handler_create(void)

Creates a new signal handler object.

Returns: A new signal handler object

void signal_handler_destroy(signal_handler_t *handler)

Destroys a signal handler.

Parameters

handler – Signal handler object

bool signal_handler_add(signal_handler_t *handler, const char *signal_decl)

Adds a signal to a signal handler.

Parameters

handler – Signal handler object
signal_decl – Signal declaration string

bool signal_handler_add_array(signal_handler_t *handler, const char **signal_decls)

Adds multiple signals to a signal handler.

Parameters

handler – Signal handler object
signal_decls – An array of signal declaration strings, terminated by NULL

void signal_handler_connect(signal_handler_t *handler, const char *signal, signal_callback_t callback, void *data)

Connects a callback to a signal on a signal handler. Does nothing if the combination of signal, callback, and data is already connected to the handler.

Parameters

handler – Signal handler object
signal – Name of signal to handle
callback – Signal callback
data – Private data passed to the callback

For scripting, use signal_handler_connect().

void signal_handler_connect_ref(signal_handler_t *handler, const char *signal, signal_callback_t callback, void *data)

Connects a callback to a signal on a signal handler, and increments the handler’s internal reference counter, preventing it from being destroyed until the signal has been disconnected. Even if the combination of signal, callback, and data is already connected to the handler, the reference counter is still incremented.

Parameters

handler – Signal handler object
signal – Name of signal to handle
callback – Signal callback
data – Private data passed to the callback

void signal_handler_disconnect(signal_handler_t *handler, const char *signal, signal_callback_t callback, void *data)

Disconnects a callback from a signal on a signal handler. Does nothing if the combination of signal, callback, and data is not yet connected to the handler.

Parameters

handler – Signal handler object
signal – Name of signal that was handled
callback – Signal callback
data – Private data passed to the callback

For scripting, use signal_handler_disconnect().

void signal_handler_signal(signal_handler_t *handler, const char *signal, calldata_t *params)

Triggers a signal, calling all connected callbacks.

Parameters

handler – Signal handler object
signal – Name of signal to trigger
params – Parameters to pass to the signal

Procedure Handlers

Procedure handlers are used to call functions without having to have direct access to declarations or callback pointers.

#include <callback/proc.h>

type proc_handler_t

typedef void (*proc_handler_proc_t)(void *data, calldata_t *cd)

Procedure handler callback.

Param data: Private data passed to this callback
Param cd: Calldata object

proc_handler_t *proc_handler_create(void)

Creates a new procedure handler.

Returns: A new procedure handler object

void proc_handler_destroy(proc_handler_t *handler)

Destroys a procedure handler object.

Parameters

handler – Procedure handler object

void proc_handler_add(proc_handler_t *handler, const char *decl_string, proc_handler_proc_t proc, void *data)

Adds a procedure to a procedure handler.

Parameters

handler – Procedure handler object
decl_string – Procedure declaration string
proc – Procedure callback
data – Private data to pass to the callback

bool proc_handler_call(proc_handler_t *handler, const char *name, calldata_t *params)

Calls a procedure within the procedure handler.

Parameters

handler – Procedure handler object
name – Name of procedure to call
params – Calldata structure to pass to the procedure