Adding upstream version 0.3.65.upstream/0.3.65upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 119 insertions, 0 deletions

diff --git a/doc/tutorial3.dox b/doc/tutorial3.dox
new file mode 100644
index 0000000..776ea14
--- /dev/null
+++ b/doc/tutorial3.dox
@@ -0,0 +1,119 @@
+/** \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 "Tutorial 2" slightly
+and add the extra code to implement the roundtrip.
+
+Let's take the following small method first:
+
+\snippet tutorial3.c roundtrip
+
+Let's take a look at what this method does.
+
+\code{.c}
+	struct spa_hook core_listener;
+
+	pw_core_add_listener(core, &core_listener, &core_events, &d);
+\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}
+static void on_core_done(void *data, uint32_t id, int seq)
+{
+	struct roundtrip_data *d = data;
+
+	if (id == PW_ID_CORE && seq == d->pending)
+		pw_main_loop_quit(d->loop);
+}
+\endcode
+
+When the done event is received for an object with id `PW_ID_CORE` and
+a certain sequence number `seq`, this function will call `pw_main_loop_quit()`.
+
+Next we do:
+
+\code{.c}
+	d.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 return value will reflect this. PipeWire
+uses the return values of the underlying SPA (Simple Plugin API)
+helper objects (See also \ref page_spa_design ).
+
+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}
+	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.
+
+\snippet tutorial3.c code
+
+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
+
+*/