Callback API Reference (libobs/callback) ======================================== Calldata -------- 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 ------- Signals are used for all event-based callbacks. .. code:: cpp #include .. 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 ------------------ Procedure handlers are used to call functions without having to have direct access to declarations or callback pointers. .. code:: cpp #include .. 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