docs/sphinx/reference-libobs-callback.rst
The :c:type:calldata_t object is used to pass parameters from signal
handlers or to procedure handlers.
.. type:: calldata_t
.. function:: void calldata_init(calldata_t *data)
Initializes a calldata structure (zeroes it).
:param data: Calldata structure
.. function:: void calldata_free(calldata_t *data)
Frees a calldata structure. Should only be used if :c:func:calldata_init()
was used. If the object is received as a callback parameter, this function
should not be used.
:param data: Calldata structure
.. function:: void calldata_set_int(calldata_t *data, const char *name, long long val)
Sets an integer parameter.
:param data: Calldata structure :param name: Parameter name :param val: Integer value
.. function:: void calldata_set_float(calldata_t *data, const char *name, double val)
Sets a floating point parameter.
:param data: Calldata structure :param name: Parameter name :param val: Floating point value
.. function:: void calldata_set_bool(calldata_t *data, const char *name, bool val)
Sets a boolean parameter.
:param data: Calldata structure :param name: Parameter name :param val: Boolean value
.. function:: void calldata_set_ptr(calldata_t *data, const char *name, void *ptr)
Sets a pointer parameter.
:param data: Calldata structure :param name: Parameter name :param val: Pointer value
.. function:: void calldata_set_string(calldata_t *data, const char *name, const char *str)
Sets a string parameter.
:param data: Calldata structure :param name: Parameter name :param val: String
.. function:: long long calldata_int(const calldata_t *data, const char *name)
Gets an integer parameter.
:param data: Calldata structure :param name: Parameter name :return: Integer value
.. function:: double calldata_float(const calldata_t *data, const char *name)
Gets a floating point parameter.
:param data: Calldata structure :param name: Parameter name :return: Floating point value
.. function:: bool calldata_bool(const calldata_t *data, const char *name)
Gets a boolean parameter.
:param data: Calldata structure :param name: Parameter name :return: Boolean value
.. function:: void *calldata_ptr(const calldata_t *data, const char *name)
Gets a pointer parameter. For example, :ref:core_signal_handler_reference
that have ptr source as a parameter requires this function to get the
pointer, which can be casted to :c:type:obs_source_t. Does not have to be freed.
:param data: Calldata structure :param name: Parameter name :return: Pointer value
.. function:: const char *calldata_string(const calldata_t *data, const char *name)
Gets a string parameter.
:param data: Calldata structure :param name: Parameter name :return: String value
Signals are used for all event-based callbacks.
.. code:: cpp
#include <callback/signal.h>
.. type:: signal_handler_t
.. type:: void (*signal_callback_t)(void *data, calldata_t *cd)
Signal callback.
:param data: Private data passed to this callback :param cd: Calldata object
.. function:: signal_handler_t *signal_handler_create(void)
Creates a new signal handler object.
:return: A new signal handler object
.. function:: void signal_handler_destroy(signal_handler_t *handler)
Destroys a signal handler.
:param handler: Signal handler object
.. function:: bool signal_handler_add(signal_handler_t *handler, const char *signal_decl)
Adds a signal to a signal handler.
:param handler: Signal handler object :param signal_decl: Signal declaration string
.. function:: bool signal_handler_add_array(signal_handler_t *handler, const char **signal_decls)
Adds multiple signals to a signal handler.
:param handler: Signal handler object :param signal_decls: An array of signal declaration strings, terminated by NULL
.. function:: 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.
:param handler: Signal handler object :param signal: Name of signal to handle :param callback: Signal callback :param data: Private data passed to the callback
For scripting, use :py:func:signal_handler_connect.
.. function:: 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.
:param handler: Signal handler object :param signal: Name of signal to handle :param callback: Signal callback :param data: Private data passed to the callback
.. function:: 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.
:param handler: Signal handler object :param signal: Name of signal that was handled :param callback: Signal callback :param data: Private data passed to the callback
For scripting, use :py:func:signal_handler_disconnect.
.. function:: void signal_handler_signal(signal_handler_t *handler, const char *signal, calldata_t *params)
Triggers a signal, calling all connected callbacks.
:param handler: Signal handler object :param signal: Name of signal to trigger :param params: Parameters to pass to the signal
Procedure handlers are used to call functions without having to have direct access to declarations or callback pointers.
.. code:: cpp
#include <callback/proc.h>
.. type:: proc_handler_t
.. type:: 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
.. function:: proc_handler_t *proc_handler_create(void)
Creates a new procedure handler.
:return: A new procedure handler object
.. function:: void proc_handler_destroy(proc_handler_t *handler)
Destroys a procedure handler object.
:param handler: Procedure handler object
.. function:: 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.
:param handler: Procedure handler object :param decl_string: Procedure declaration string :param proc: Procedure callback :param data: Private data to pass to the callback
.. function:: bool proc_handler_call(proc_handler_t *handler, const char *name, calldata_t *params)
Calls a procedure within the procedure handler.
:param handler: Procedure handler object :param name: Name of procedure to call :param params: Calldata structure to pass to the procedure