mirror of
https://gitlab.freedesktop.org/pipewire/pipewire
synced 2024-10-14 11:53:16 +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.
237 lines
7 KiB
Plaintext
237 lines
7 KiB
Plaintext
/** \page page_tutorial3 Tutorial - Part 3: Forcing a roundtrip
|
|
|
|
\ref page_tutorial2 | \ref page_tutorial "Index" | \ref page_tutorial4
|
|
|
|
In this tutorial we show how to force a roundtrip to the server
|
|
to make sure an action completed.
|
|
|
|
We'll change our example from \ref page_tutorial2 "Tutorial2" slightly
|
|
and add the extra code to implement the roundtrip.
|
|
|
|
Let's take the following small method first:
|
|
|
|
\code{.c}
|
|
static int roundtrip(struct pw_core *core, struct pw_main_loop *loop)
|
|
{
|
|
struct spa_hook core_listener;
|
|
int pending, done = 0;
|
|
|
|
void core_event_done(void *object, uint32_t id, int seq) {
|
|
if (id == PW_ID_CORE && seq == pending) {
|
|
done = 1;
|
|
pw_main_loop_quit(loop);
|
|
}
|
|
}
|
|
const struct pw_core_events core_events = {
|
|
PW_VERSION_CORE_EVENTS,
|
|
.done = core_event_done,
|
|
};
|
|
|
|
spa_zero(core_listener);
|
|
pw_core_add_listener(core, &core_listener,
|
|
&core_events, NULL);
|
|
|
|
pending = pw_core_sync(core, PW_ID_CORE, 0);
|
|
|
|
while (!done) {
|
|
pw_main_loop_run(loop);
|
|
}
|
|
spa_hook_remove(&core_listener);
|
|
return 0;
|
|
}
|
|
\endcode
|
|
|
|
Let's take a look at what this method does.
|
|
|
|
\code{.c}
|
|
struct spa_hook core_listener;
|
|
spa_zero(core_listener);
|
|
pw_core_add_listener(core, &core_listener,
|
|
&core_events, NULL);
|
|
\endcode
|
|
|
|
First of all we add a listener for the events of the core
|
|
object. We are only interested in the `done` event in this
|
|
tutorial. This is the event handler:
|
|
|
|
\code{.c}
|
|
int pending, done = 0;
|
|
|
|
void core_event_done(void *object, uint32_t id, int seq) {
|
|
if (id == PW_ID_CORE && seq == pending) {
|
|
done = 1;
|
|
pw_main_loop_quit(loop);
|
|
}
|
|
}
|
|
const struct pw_core_events core_events = {
|
|
PW_VERSION_CORE_EVENTS,
|
|
.done = core_event_done,
|
|
};
|
|
\endcode
|
|
|
|
When the done event is received for an object with id `PW_ID_CORE`
|
|
and a certain sequence number `seq`, this function will set the done
|
|
variable to 1 and call `pw_main_loop_quit()`.
|
|
|
|
Next we do:
|
|
|
|
\code{.c}
|
|
pending = pw_core_sync(core, PW_ID_CORE, 0);
|
|
\endcode
|
|
|
|
This triggers the `sync` method on the core object with id
|
|
`PW_ID_CORE` and sequence number 0.
|
|
|
|
Because this is a method on a proxy object, it will be executed
|
|
asynchronously and the returns value will reflect this. PipeWire
|
|
uses the return values of the underlying SPA (Simple Plugin API)
|
|
helper objects (See also [error codes](spa-design.md#error-codes)).
|
|
|
|
Because all messages on the PipeWire server are handled sequentially,
|
|
the sync method will be executed after all previous methods are
|
|
completed. The PipeWire server will emit a `done` event with the
|
|
same ID and the return value of the original `pw_core_sync()`
|
|
method in the sequence number.
|
|
|
|
We then run the mainloop to send the messages to the server and
|
|
receive the events:
|
|
|
|
\code{.c}
|
|
while (!done) {
|
|
pw_main_loop_run(loop);
|
|
}
|
|
\endcode
|
|
|
|
When we get the done event, we can compare it to the sync method
|
|
and then we know that we did a complete roundtrip and there are no
|
|
more pending methods on the server. We can quit the mainloop and
|
|
remove the listener:
|
|
|
|
\code{.c}
|
|
spa_hook_remove(&core_listener);
|
|
\endcode
|
|
|
|
If we add this roundtrip method to our code and call it instead of the
|
|
`pw_main_loop_run()` we will exit the program after all previous methods
|
|
are finished. This means that the `pw_core_get_registry()` call
|
|
completed and thus that we also received all events for the globals
|
|
on the server.
|
|
|
|
|
|
\code{.c}
|
|
#include <pipewire/pipewire.h>
|
|
|
|
static int roundtrip(struct pw_core *core, struct pw_main_loop *loop)
|
|
{
|
|
struct spa_hook core_listener;
|
|
int pending, done = 0;
|
|
void core_event_done(void *object, uint32_t id, int seq) {
|
|
if (id == PW_ID_CORE && seq == pending) {
|
|
done = 1;
|
|
pw_main_loop_quit(loop);
|
|
}
|
|
}
|
|
const struct pw_core_events core_events = {
|
|
PW_VERSION_CORE_EVENTS,
|
|
.done = core_event_done,
|
|
};
|
|
|
|
spa_zero(core_listener);
|
|
pw_core_add_listener(core, &core_listener,
|
|
&core_events, NULL);
|
|
|
|
pending = pw_core_sync(core, PW_ID_CORE, 0);
|
|
|
|
while (!done) {
|
|
pw_main_loop_run(loop);
|
|
}
|
|
spa_hook_remove(&core_listener);
|
|
return 0;
|
|
}
|
|
|
|
static void registry_event_global(void *data, uint32_t id,
|
|
uint32_t permissions, const char *type, uint32_t version,
|
|
const struct spa_dict *props)
|
|
{
|
|
printf("object: id:%u type:%s/%d\n", id, type, version);
|
|
}
|
|
|
|
static const struct pw_registry_events registry_events = {
|
|
PW_VERSION_REGISTRY_EVENTS,
|
|
.global = registry_event_global,
|
|
};
|
|
|
|
int main(int argc, char *argv[])
|
|
{
|
|
struct pw_main_loop *loop;
|
|
struct pw_context *context;
|
|
struct pw_core *core;
|
|
struct pw_registry *registry;
|
|
struct spa_hook registry_listener;
|
|
|
|
pw_init(&argc, &argv);
|
|
|
|
loop = pw_main_loop_new(NULL /* properties */);
|
|
context = pw_context_new(pw_main_loop_get_loop(loop),
|
|
NULL /* properties */,
|
|
0 /* user_data size */);
|
|
|
|
core = pw_context_connect(context,
|
|
NULL /* properties */,
|
|
0 /* user_data size */);
|
|
|
|
registry = pw_core_get_registry(core, PW_VERSION_REGISTRY,
|
|
0 /* user_data size */);
|
|
|
|
spa_zero(registry_listener);
|
|
pw_registry_add_listener(registry, ®istry_listener,
|
|
®istry_events, NULL);
|
|
|
|
roundtrip(core, loop);
|
|
|
|
pw_proxy_destroy((struct pw_proxy*)registry);
|
|
pw_core_disconnect(core);
|
|
pw_context_destroy(context);
|
|
pw_main_loop_destroy(loop);
|
|
|
|
return 0;
|
|
}
|
|
\endcode
|
|
|
|
To compile the simple test application, copy it into a tutorial3.c file and
|
|
use:
|
|
|
|
gcc -Wall tutorial3.c -o tutorial3 $(pkg-config --cflags --libs libpipewire-0.3)
|
|
|
|
Now that our program completes, we can take a look at how we can destroy
|
|
the objects we created. Let's destroy each of them in reverse order that we
|
|
created them:
|
|
|
|
\code{.c}
|
|
pw_proxy_destroy((struct pw_proxy*)registry);
|
|
\endcode
|
|
|
|
The registry is a proxy and can be destroyed with the generic proxy destroy
|
|
method. After destroying the object, you should not use it anymore. It is
|
|
an error to destroy an object more than once.
|
|
|
|
We can disconnect from the server with:
|
|
|
|
\code{.c}
|
|
pw_core_disconnect(core);
|
|
\endcode
|
|
|
|
This will also destroy the core proxy object and will remove the proxies
|
|
that might have been created on this connection.
|
|
|
|
We can finally destroy our context and mainloop to conclude this tutorial:
|
|
|
|
\code{.c}
|
|
pw_context_destroy(context);
|
|
pw_main_loop_destroy(loop);
|
|
\endcode
|
|
|
|
\ref page_tutorial2 | \ref page_tutorial "Index" | \ref page_tutorial4
|
|
|
|
*/
|