PipeWire 1.6.8

Loading...
Searching...
No Matches
Hooks
SPA » Utilities

A SPA Hook is a data structure to keep track of callbacks. More...

## Files
file | hook.h
| spa/utils/hook.h

## Data Structures
struct | spa_hook_list
| A list of hooks. More...
struct | spa_hook
| A hook, contains the structure with functions and the data passed to the functions. More...

## Macros
#define | spa_hook_list_call_simple(l, type, method, vers, ...)
#define | spa_hook_list_do_call(l, start, type, method, vers, once, ...)
| Call all hooks in a list, starting from the given one and optionally stopping after calling the first non-NULL function, returns the number of methods called.
#define | spa_hook_list_call(l, t, m, v, ...)
| Call the method named m for each element in list l.
#define | spa_hook_list_call_once(l, t, m, v, ...)
| Call the method named m for each element in list l, stopping after the first invocation.
#define | spa_hook_list_call_start(l, s, t, m, v, ...)
#define | spa_hook_list_call_once_start(l, s, t, m, v, ...)

## Functions
SPA_API_HOOK void | spa_hook_list_init (struct spa_hook_list *list)
| Initialize a hook list to the empty list.
SPA_API_HOOK bool | spa_hook_list_is_empty (struct spa_hook_list *list)
SPA_API_HOOK void | spa_hook_list_append (struct spa_hook_list *list, struct spa_hook *hook, const void *funcs, void *data)
| Append a hook.
SPA_API_HOOK void | spa_hook_list_prepend (struct spa_hook_list *list, struct spa_hook *hook, const void *funcs, void *data)
| Prepend a hook.
SPA_API_HOOK void | spa_hook_remove (struct spa_hook *hook)
| Remove a hook.
SPA_API_HOOK void | spa_hook_list_clean (struct spa_hook_list *list)
| Remove all hooks from the list.
SPA_API_HOOK void | spa_hook_list_isolate (struct spa_hook_list *list, struct spa_hook_list *save, struct spa_hook *hook, const void *funcs, void *data)
SPA_API_HOOK void | spa_hook_list_join (struct spa_hook_list *list, struct spa_hook_list *save)

## Detailed Description

A SPA Hook is a data structure to keep track of callbacks.

It is similar to the Interfaces and typically used where an implementation allows for multiple external callback functions. For example, an implementation may use a hook list to implement signals with each caller using a hook to register callbacks to be invoked on those signals.

The below (pseudo)code is a minimal example outlining the use of hooks:

// the public interface
#define VERSION_BAR_EVENTS 0 // version of the vtable
struct bar_events {
uint32_t version; // NOTE: an integral member named `version`
// must be present in the vtable
void (*boom)(void *data, const char *msg);
};
// private implementation
struct party {
struct spa_hook_list bar_list;
};
void party_add_event_listener(struct party *p, struct spa_hook *listener,
const struct bar_events *events, void *data)
{
spa_hook_list_append(&p->bar_list, listener, events, data);
}
static void party_on(struct party *p)
{
// NOTE: this is a macro, it evaluates to an integer,
// which is the number of hooks called
spa_hook_list_call(&p->list,
struct bar_events, // vtable type
boom, // function name
0, // hardcoded version,
// usually the version in which `boom`
// has been added to the vtable
"party on, wayne" // function argument(s)
);
}
spa_hook_list_call
#define spa_hook_list_call(l, t, m, v,...)
Call the method named m for each element in list l.
Definition hook.h:538
spa_hook_list_append
SPA_API_HOOK void spa_hook_list_append(struct spa_hook_list *list, struct spa_hook *hook, const void *funcs, void *data)
Append a hook.
Definition hook.h:448
spa_hook_list
A list of hooks.
Definition hook.h:416
spa_hook
A hook, contains the structure with functions and the data passed to the functions.
Definition hook.h:427

In the caller, the hooks can be used like this:

static void boom_cb(void *data, const char *msg) {
// data is userdata from main()
printf("%s", msg);
}
static const struct bar_events events = {
.version = VERSION_BAR_EVENTS, // version of the implemented interface
.boom = boom_cb,
};
void main(void) {
void *userdata = whatever;
struct spa_hook hook;
struct party *p = start_the_party();
party_add_event_listener(p, &hook, &events, userdata);
mainloop();
return 0;
}

## Macro Definition Documentation

## ◆ spa_hook_list_call_simple

#define spa_hook_list_call_simple | ( |  | l,
|  |  | type,
|  |  | method,
|  |  | vers,
|  |  | ... )

## ◆ spa_hook_list_do_call

#define spa_hook_list_do_call | ( |  | l,
|  |  | start,
|  |  | type,
|  |  | method,
|  |  | vers,
|  |  | once,
|  |  | ... )

Call all hooks in a list, starting from the given one and optionally stopping after calling the first non-NULL function, returns the number of methods called.

## ◆ spa_hook_list_call

#define spa_hook_list_call | ( |  | l,
|  |  | t,
|  |  | m,
|  |  | v,
|  |  | ... )

Value:
spa_hook_list_do_call(l,NULL,t,m,v,false,##__VA_ARGS__)
spa_hook_list_do_call
#define spa_hook_list_do_call(l, start, type, method, vers, once,...)
Call all hooks in a list, starting from the given one and optionally stopping after calling the first...
Definition hook.h:516

Call the method named m for each element in list l.

t specifies the type of the callback struct.

## ◆ spa_hook_list_call_once

#define spa_hook_list_call_once | ( |  | l,
|  |  | t,
|  |  | m,
|  |  | v,
|  |  | ... )

Value:
spa_hook_list_do_call(l,NULL,t,m,v,true,##__VA_ARGS__)

Call the method named m for each element in list l, stopping after the first invocation.

t specifies the type of the callback struct.

## ◆ spa_hook_list_call_start

#define spa_hook_list_call_start | ( |  | l,
|  |  | s,
|  |  | t,
|  |  | m,
|  |  | v,
|  |  | ... )

Value:
spa_hook_list_do_call(l,s,t,m,v,false,##__VA_ARGS__)

## ◆ spa_hook_list_call_once_start

#define spa_hook_list_call_once_start | ( |  | l,
|  |  | s,
|  |  | t,
|  |  | m,
|  |  | v,
|  |  | ... )

Value:
spa_hook_list_do_call(l,s,t,m,v,true,##__VA_ARGS__)

## Function Documentation

## ◆ spa_hook_list_init()

SPA_API_HOOK void spa_hook_list_init | ( | struct spa_hook_list * | list | ) |

Initialize a hook list to the empty list.

Examples
  export-sink.c, and export-source.c.

## ◆ spa_hook_list_is_empty()

SPA_API_HOOK bool spa_hook_list_is_empty | ( | struct spa_hook_list * | list | ) |

## ◆ spa_hook_list_append()

SPA_API_HOOK void spa_hook_list_append | ( | struct spa_hook_list * | list,
|  | struct spa_hook * | hook,
|  | const void * | funcs,
|  | void * | data )

Append a hook.

## ◆ spa_hook_list_prepend()

SPA_API_HOOK void spa_hook_list_prepend | ( | struct spa_hook_list * | list,
|  | struct spa_hook * | hook,
|  | const void * | funcs,
|  | void * | data )

Prepend a hook.

## ◆ spa_hook_remove()

SPA_API_HOOK void spa_hook_remove | ( | struct spa_hook * | hook | ) |

Remove a hook.

Examples
  bluez-session.c, and tutorial3.c.

## ◆ spa_hook_list_clean()

SPA_API_HOOK void spa_hook_list_clean | ( | struct spa_hook_list * | list | ) |

Remove all hooks from the list.

## ◆ spa_hook_list_isolate()

SPA_API_HOOK void spa_hook_list_isolate | ( | struct spa_hook_list * | list,
|  | struct spa_hook_list * | save,
|  | struct spa_hook * | hook,
|  | const void * | funcs,
|  | void * | data )

Examples
  export-sink.c, and export-source.c.

## ◆ spa_hook_list_join()

SPA_API_HOOK void spa_hook_list_join | ( | struct spa_hook_list * | list,
|  | struct spa_hook_list * | save )

Examples
  export-sink.c, and export-source.c.