Make FlatpakInstance api public

This can be of use in frontends like GNOME Software.

Closes: #2201
Approved by: alexlarsson

1 files changed, 147 insertions, 1 deletions

diff --git a/common/flatpak-instance.c b/common/flatpak-instance.c
index 1f15776f..4d816025 100644
--- a/common/flatpak-instance.c
+++ b/common/flatpak-instance.c
@@ -22,9 +22,27 @@
 
 #include "flatpak-utils-private.h"
 #include "flatpak-run-private.h"
-#include "flatpak-instance-private.h"
+#include "flatpak-instance.h"
 #include "flatpak-enum-types.h"
 
+/**
+ * SECTION:flatpak-instance
+ * @Title: FlatpakInstance
+ * @Short_description: Information about a running sandbox
+ *
+ * A FlatpakInstance refers to a running sandbox, and contains
+ * some basic information about the sandbox setup, such as the
+ * application and runtime used inside the sandbox.
+ *
+ * Importantly, it also gives access to the PID of the main
+ * processes in the sandbox.
+ *
+ * Note that process lifecycle tracking is fundamentally racy.
+ * You have to be prepared for the sandbox and the processes
+ * represented by a FlatpakInstance to not be around anymore.
+ *
+ * The FlatpakInstance api was added in Flatpak 1.1.
+ */
 
 typedef struct _FlatpakInstancePrivate FlatpakInstancePrivate;
 
@@ -81,6 +99,17 @@ flatpak_instance_init (FlatpakInstance *self)
 {
 }
 
+/**
+ * flatpak_instance_get_id:
+ * @self: a #FlatpakInstance
+ *
+ * Gets the instance ID. The ID is used by Flatpak for bookkeeping
+ * purposes and has no further relevance.
+ *
+ * Returns: the instance ID
+ *
+ * Since: 1.1
+ */
 const char *
 flatpak_instance_get_id (FlatpakInstance *self)
 {
@@ -89,6 +118,16 @@ flatpak_instance_get_id (FlatpakInstance *self)
   return priv->id;
 }
 
+/**
+ * flatpak_instance_get_app:
+ * @self: a #FlatpakInstance
+ *
+ * Gets the application ID of the application running in the instance.
+ *
+ * Returns: the application ID
+ *
+ * Since: 1.1
+ */
 const char *
 flatpak_instance_get_app (FlatpakInstance *self)
 {
@@ -97,6 +136,16 @@ flatpak_instance_get_app (FlatpakInstance *self)
   return priv->app;
 }
 
+/**
+ * flatpak_instance_get_arch:
+ * @self: a #FlatpakInstance
+ *
+ * Gets the architecture of the application running in the instance.
+ *
+ * Returns: the architecture
+ *
+ * Since: 1.1
+ */
 const char *
 flatpak_instance_get_arch (FlatpakInstance *self)
 {
@@ -105,6 +154,16 @@ flatpak_instance_get_arch (FlatpakInstance *self)
   return priv->arch;
 }
 
+/**
+ * flatpak_instance_get_branch:
+ * @self: a #FlatpakInstance
+ *
+ * Gets the branch of the application running in the instance.
+ *
+ * Returns: the architecture
+ *
+ * Since: 1.1
+ */
 const char *
 flatpak_instance_get_branch (FlatpakInstance *self)
 {
@@ -113,6 +172,16 @@ flatpak_instance_get_branch (FlatpakInstance *self)
   return priv->branch;
 }
 
+/**
+ * flatpak_instance_get_commit:
+ * @self: a #FlatpakInstance
+ *
+ * Gets the commit of the application running in the instance.
+ *
+ * Returns: the commit
+ *
+ * Since: 1.1
+ */
 const char *
 flatpak_instance_get_commit (FlatpakInstance *self)
 {
@@ -121,6 +190,16 @@ flatpak_instance_get_commit (FlatpakInstance *self)
   return priv->commit;
 }
 
+/**
+ * flatpak_instance_get_runtime:
+ * @self: a #FlatpakInstance
+ *
+ * Gets the ref of the runtime used in the instance.
+ *
+ * Returns: the runtime ref
+ *
+ * Since: 1.1
+ */
 const char *
 flatpak_instance_get_runtime (FlatpakInstance *self)
 {
@@ -129,6 +208,16 @@ flatpak_instance_get_runtime (FlatpakInstance *self)
   return priv->runtime;
 }
 
+/**
+ * flatpak_instance_get_runtime_commit:
+ * @self: a #FlatpakInstance
+ *
+ * Gets the commit of the runtime used in the instance.
+ *
+ * Returns: the runtime commit
+ *
+ * Since: 1.1
+ */
 const char *
 flatpak_instance_get_runtime_commit (FlatpakInstance *self)
 {
@@ -137,6 +226,19 @@ flatpak_instance_get_runtime_commit (FlatpakInstance *self)
   return priv->runtime_commit;
 }
 
+/**
+ * flatpak_instance_get_pid:
+ * @self: a #FlatpakInstance
+ *
+ * Gets the PID of the outermost process in the sandbox. This is not the
+ * application process itself, but a bubblewrap 'babysitter' process.
+ *
+ * See flatpak_instance_get_child_pid().
+ *
+ * Returns: the outermost process PID
+ *
+ * Since: 1.1
+ */
 int
 flatpak_instance_get_pid (FlatpakInstance *self)
 {
@@ -145,6 +247,18 @@ flatpak_instance_get_pid (FlatpakInstance *self)
   return priv->pid;
 }
 
+/**
+ * flatpak_instance_get_child_pid:
+ * @self: a #FlatpakInstance
+ *
+ * Gets the PID of the application process in the sandbox.
+ *
+ * See flatpak_instance_get_pid().
+ *
+ * Returns: the application process PID
+ *
+ * Since: 1.1
+ */
 int
 flatpak_instance_get_child_pid (FlatpakInstance *self)
 {
@@ -153,6 +267,21 @@ flatpak_instance_get_child_pid (FlatpakInstance *self)
   return priv->child_pid;
 }
 
+/**
+ * flatpak_instance_get_info:
+ * @self: a #FlatpakInstance
+ *
+ * Gets a keyfile that holds information about the running sandbox.
+ *
+ * This file is available as /.flatpak-info inside the sandbox as well.
+ *
+ * The most important data in the keyfile is available with separate getters,
+ * but there may be more information in the keyfile.
+ *
+ * Returns: the flatpak-info keyfile
+ *
+ * Since: 1.1
+ */
 GKeyFile *
 flatpak_instance_get_info (FlatpakInstance *self)
 {
@@ -264,6 +393,15 @@ flatpak_instance_new (const char *id)
   return self;
 }
 
+/**
+ * flatpak_instance_get_all:
+ *
+ * Gets FlatpakInstance objects for all running sandboxes in the current session.
+ *
+ * Returns: (transfer full): a #GPtrArray of #FlatpakInstance objects
+ *
+ * Since: 1.1
+ */
 GPtrArray *
 flatpak_instance_get_all (void)
 {
@@ -317,6 +455,14 @@ flatpak_instance_get_all (void)
   return g_steal_pointer (&instances);
 }
 
+/**
+ * flatpak_instance_is_running:
+ * @self: a #FlatpakInstance
+ *
+ * Finds out if the sandbox represented by @self is still running.
+ *
+ * Returns: %TRUE if the sandbox is still running
+ */
 gboolean
 flatpak_instance_is_running (FlatpakInstance *self)
 {