mirror of
https://gitlab.freedesktop.org/pipewire/pipewire
synced 2024-10-14 20:02:38 +00:00
9ed9980fa2
While doxygen can handle markdown pages, support for it is very limited: markdown pages can only be included as a whole page, they get an automatic title (custom titles are possible but aren't standard markdown) and it's not possible to use \subpage without messing with the markdown again. Any markdown page will thus end up as separate item in the doxygen output, not really suitable for generating a good page hiearchy. Let's switch the tutorial to use doxygen directly instead of markdown, short of using code/endcode instead of markdown's ``` there isn't that much difference anyway but it allows us to structure things nicer in the online docs.
188 lines
4.8 KiB
Plaintext
188 lines
4.8 KiB
Plaintext
/** \page page_tutorial6 Tutorial - Part 6: Binding objects
|
|
|
|
\ref page_tutorial5 | \ref page_tutorial "Index"
|
|
|
|
In this tutorial we show how to bind to an object so that we can
|
|
receive events and call methods on the object.
|
|
|
|
Let take a look at the following application to start.
|
|
|
|
\code{.c}
|
|
#include <pipewire/pipewire.h>
|
|
|
|
struct data {
|
|
struct pw_main_loop *loop;
|
|
struct pw_context *context;
|
|
struct pw_core *core;
|
|
|
|
struct pw_registry *registry;
|
|
struct spa_hook registry_listener;
|
|
|
|
struct pw_client *client;
|
|
struct spa_hook client_listener;
|
|
};
|
|
|
|
static void client_info(void *object, const struct pw_client_info *info)
|
|
{
|
|
struct data *data = object;
|
|
const struct spa_dict_item *item;
|
|
|
|
printf("client: id:%u\n", info->id);
|
|
printf("\tprops:\n");
|
|
spa_dict_for_each(item, info->props)
|
|
printf("\t\t%s: \"%s\"\n", item->key, item->value);
|
|
|
|
pw_main_loop_quit(data->loop);
|
|
}
|
|
|
|
static const struct pw_client_events client_events = {
|
|
PW_VERSION_CLIENT_EVENTS,
|
|
.info = client_info,
|
|
};
|
|
|
|
static void registry_event_global(void *_data, uint32_t id,
|
|
uint32_t permissions, const char *type,
|
|
uint32_t version, const struct spa_dict *props)
|
|
{
|
|
struct data *data = _data;
|
|
if (data->client != NULL)
|
|
return;
|
|
|
|
if (strcmp(type, PW_TYPE_INTERFACE_Client) == 0) {
|
|
data->client = pw_registry_bind(data->registry,
|
|
id, type, PW_VERSION_CLIENT, 0);
|
|
pw_client_add_listener(data->client,
|
|
&data->client_listener,
|
|
&client_events, data);
|
|
}
|
|
}
|
|
|
|
static const struct pw_registry_events registry_events = {
|
|
PW_VERSION_REGISTRY_EVENTS,
|
|
.global = registry_event_global,
|
|
};
|
|
|
|
int main(int argc, char *argv[])
|
|
{
|
|
struct data data;
|
|
|
|
spa_zero(data);
|
|
|
|
pw_init(&argc, &argv);
|
|
|
|
data.loop = pw_main_loop_new(NULL /* properties */ );
|
|
data.context = pw_context_new(pw_main_loop_get_loop(data.loop),
|
|
NULL /* properties */ ,
|
|
0 /* user_data size */ );
|
|
|
|
data.core = pw_context_connect(data.context, NULL /* properties */ ,
|
|
0 /* user_data size */ );
|
|
|
|
data.registry = pw_core_get_registry(data.core, PW_VERSION_REGISTRY,
|
|
0 /* user_data size */ );
|
|
|
|
pw_registry_add_listener(data.registry, &data.registry_listener,
|
|
®istry_events, &data);
|
|
|
|
pw_main_loop_run(data.loop);
|
|
|
|
pw_proxy_destroy((struct pw_proxy *)data.client);
|
|
pw_proxy_destroy((struct pw_proxy *)data.registry);
|
|
pw_core_disconnect(data.core);
|
|
pw_context_destroy(data.context);
|
|
pw_main_loop_destroy(data.loop);
|
|
|
|
return 0;
|
|
}
|
|
\endcode
|
|
|
|
To compile the simple test application, copy it into a tutorial6.c file and
|
|
use:
|
|
|
|
gcc -Wall tutorial6.c -o tutorial6 $(pkg-config --cflags --libs libpipewire-0.3)
|
|
|
|
Most of this is the same as \ref page_tutorial2 where we simply
|
|
enumerated all objects on the server. Instead of just printing the object
|
|
id and some other properties, in this example we also bind to the object.
|
|
|
|
We use the `pw_registry_bind()` method on our registry object like this:
|
|
|
|
\code{.c}
|
|
static void registry_event_global(void *_data, uint32_t id,
|
|
uint32_t permissions, const char *type,
|
|
uint32_t version, const struct spa_dict *props)
|
|
{
|
|
struct data *data = _data;
|
|
if (data->client != NULL)
|
|
return;
|
|
|
|
if (strcmp(type, PW_TYPE_INTERFACE_Client) == 0) {
|
|
data->client = pw_registry_bind(data->registry,
|
|
id, type, PW_VERSION_CLIENT, 0);
|
|
/* ... */
|
|
}
|
|
}
|
|
\endcode
|
|
|
|
We bind to the first client object that we see. This gives us a pointer
|
|
to a `struct pw_proxy` that we can also cast to a `struct pw_client`.
|
|
|
|
On the proxy we can call methods and listen for events. PipeWire will
|
|
automatically serialize the method calls and events between client and
|
|
server for us.
|
|
|
|
We can now listen for events by adding a listener. We're going to
|
|
listen to the info event on the client object that is emitted right
|
|
after we bind to it or when it changes. This is not very different
|
|
from the registry listener we added before:
|
|
|
|
\code{.c}
|
|
static void client_info(void *object, const struct pw_client_info *info)
|
|
{
|
|
struct data *data = object;
|
|
const struct spa_dict_item *item;
|
|
|
|
printf("client: id:%u\n", info->id);
|
|
printf("\tprops:\n");
|
|
spa_dict_for_each(item, info->props)
|
|
printf("\t\t%s: \"%s\"\n", item->key, item->value);
|
|
|
|
pw_main_loop_quit(data->loop);
|
|
}
|
|
|
|
static const struct pw_client_events client_events = {
|
|
PW_VERSION_CLIENT_EVENTS,
|
|
.info = client_info,
|
|
};
|
|
|
|
static void registry_event_global(void *_data, uint32_t id,
|
|
uint32_t permissions, const char *type,
|
|
uint32_t version, const struct spa_dict *props)
|
|
{
|
|
/* ... */
|
|
pw_client_add_listener(data->client,
|
|
&data->client_listener,
|
|
&client_events, data);
|
|
/* ... */
|
|
}
|
|
\endcode
|
|
|
|
We're also quitting the mainloop after we get the info to nicely stop
|
|
our tutorial application.
|
|
|
|
When we stop the application, don't forget to destroy all proxies that
|
|
you created. Otherwise, they will be leaked:
|
|
|
|
\code{.c}
|
|
/* ... */
|
|
pw_proxy_destroy((struct pw_proxy *)data.client);
|
|
/* ... */
|
|
|
|
return 0;
|
|
}
|
|
\endcode
|
|
|
|
\ref page_tutorial5 | \ref page_tutorial "Index"
|
|
|
|
*/
|