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