docs: add more docs

also some small improvements

src/client/pulsevideo.c

@@ -22,6 +22,14 @@
 #include "gst/gstfdpay.h"
 #include "gst/gstfddepay.h"
 
+/**
+ * pv_init:
+ * @argc: pointer to argc
+ * @argv: pointer to argv
+ *
+ * initialize the pulsevideo system, parse and modify any parameters given
+ * by @argc and @argv.
+ */
 void
 pv_init (int *argc, char **argv[])
 {
@@ -30,4 +38,3 @@ pv_init (int *argc, char **argv[])
   gst_element_register (NULL, "pvfdpay", GST_RANK_NONE, GST_TYPE_FDPAY);
   gst_element_register (NULL, "pvfddepay", GST_RANK_NONE, GST_TYPE_FDDEPAY);
 }
-

src/client/pv-context.c

@@ -38,7 +38,6 @@ struct _PvContextPrivate
 
   PvDaemon1 *daemon;
 
-  gchar *client_path;
   PvClient1 *client;
 
   PvSubscribe *subscribe;
@@ -59,7 +58,7 @@ enum
   PROP_PROPERTIES,
   PROP_STATE,
   PROP_CONNECTION,
-  PROP_CLIENT_PATH
+  PROP_CLIENT_PROXY
 };
 
 static void
@@ -88,8 +87,8 @@ pv_context_get_property (GObject    *_object,
       g_value_set_object (value, priv->connection);
       break;
 
-    case PROP_CLIENT_PATH:
+    case PROP_CLIENT_PROXY:
-      g_value_set_string (value, priv->client_path);
+      g_value_set_object (value, priv->client);
       break;
 
     default:
@@ -208,11 +207,11 @@ pv_context_class_init (PvContextClass * klass)
    * The client object path of the context.
    */
   g_object_class_install_property (gobject_class,
-                                   PROP_CLIENT_PATH,
+                                   PROP_CLIENT_PROXY,
-                                   g_param_spec_string ("client-path",
+                                   g_param_spec_object ("client-proxy",
-                                                        "Client Path",
+                                                        "Client Proxy",
-                                                        "The client object path",
+                                                        "The client proxy",
-                                                        NULL,
+                                                        G_TYPE_DBUS_PROXY,
                                                         G_PARAM_READABLE |
                                                         G_PARAM_STATIC_STRINGS));
 }
@@ -250,25 +249,6 @@ context_set_state (PvContext *context, PvContextState state)
   }
 }
 
-/**
- * pv_context_get_state:
- * @context: a #PvContext
- *
- * Get the state of @context.
- *
- * Returns: the state of @context
- */
-PvContextState
-pv_context_get_state (PvContext *context)
-{
-  PvContextPrivate *priv;
-
-  g_return_val_if_fail (PV_IS_CONTEXT (context), PV_CONTEXT_STATE_ERROR);
-  priv = context->priv;
-
-  return priv->state;
-}
-
 static void
 on_client_proxy (GObject *source_object,
                  GAsyncResult *res,
@@ -296,8 +276,9 @@ on_client_connected (GObject *source_object,
   PvContext *context = user_data;
   PvContextPrivate *priv = context->priv;
   GError *error = NULL;
+  gchar *client_path;
 
-  if (!pv_daemon1_call_connect_client_finish (priv->daemon, &priv->client_path, res, &error)) {
+  if (!pv_daemon1_call_connect_client_finish (priv->daemon, &client_path, res, &error)) {
     context_set_state (context, PV_CONTEXT_STATE_ERROR);
     g_error ("failed to connect client: %s", error->message);
     g_clear_error (&error);
@@ -307,10 +288,11 @@ on_client_connected (GObject *source_object,
   pv_client1_proxy_new (priv->connection,
                         G_DBUS_PROXY_FLAGS_NONE,
                         PV_DBUS_SERVICE,
-                        priv->client_path,
+                        client_path,
                         NULL,
                         on_client_proxy,
                         context);
+  g_free (client_path);
 }
 
 static void
@@ -395,6 +377,15 @@ on_name_vanished (GDBusConnection *connection,
   }
 }
 
+/**
+ * pv_context_set_subscribe:
+ * @context: a #PvContext
+ * @subscribe: (transfer full): a #PvSubscribe
+ *
+ * Use @subscribe to receive subscription events from @context.
+ *
+ * Returns: %TRUE on success.
+ */
 gboolean
 pv_context_set_subscribe (PvContext *context, PvSubscribe *subscribe)
 {
@@ -498,6 +489,16 @@ pv_context_disconnect (PvContext *context)
   return TRUE;
 }
 
+/**
+ * pv_context_register_source:
+ * @context: a #PvContext
+ * @source: a #PvSource
+ *
+ * Register @source in @context. This makes @source availabe to other
+ * connected clients.
+ *
+ * Returns: %TRUE on success.
+ */
 gboolean
 pv_context_register_source (PvContext *context, PvSource *source)
 {
@@ -513,6 +514,16 @@ pv_context_register_source (PvContext *context, PvSource *source)
   return TRUE;
 }
 
+/**
+ * pv_context_unregister_source:
+ * @context: a #PvContext
+ * @source: a #PvSource
+ *
+ * Unregister @source from @context. @source will no longer be
+ * available for clients.
+ *
+ * Returns: %TRUE on success.
+ */
 gboolean
 pv_context_unregister_source (PvContext *context, PvSource *source)
 {
@@ -524,6 +535,25 @@ pv_context_unregister_source (PvContext *context, PvSource *source)
   return TRUE;
 }
 
+/**
+ * pv_context_get_state:
+ * @context: a #PvContext
+ *
+ * Get the state of @context.
+ *
+ * Returns: the state of @context
+ */
+PvContextState
+pv_context_get_state (PvContext *context)
+{
+  PvContextPrivate *priv;
+
+  g_return_val_if_fail (PV_IS_CONTEXT (context), PV_CONTEXT_STATE_ERROR);
+  priv = context->priv;
+
+  return priv->state;
+}
+
 /**
  * pv_context_get_connection:
  * @context: a #PvContext
@@ -556,21 +586,3 @@ pv_context_get_client_proxy (PvContext *context)
 
   return G_DBUS_PROXY (context->priv->client);
 }
-
-/**
- * pv_context_get_client_path:
- * @context: a #PvContext
- *
- * Get the client object path that @context is registered with
- *
- * Returns: the client object path of @context or %NULL when not
- * registered.
- */
-const gchar *
-pv_context_get_client_path (PvContext *context)
-{
-  g_return_val_if_fail (PV_IS_CONTEXT (context), NULL);
-
-  return context->priv->client_path;
-}
-

src/client/pv-context.h

@@ -108,11 +108,10 @@ gboolean          pv_context_disconnect            (PvContext *context);
 gboolean          pv_context_register_source       (PvContext *context, PvSource *source);
 gboolean          pv_context_unregister_source     (PvContext *context, PvSource *source);
 
+PvContextState    pv_context_get_state             (PvContext *context);
 GDBusConnection * pv_context_get_connection        (PvContext *context);
 GDBusProxy *      pv_context_get_client_proxy      (PvContext *context);
-const gchar *     pv_context_get_client_path       (PvContext *context);
 
-PvContextState    pv_context_get_state             (PvContext *context);
 
 G_END_DECLS
 

src/client/pv-stream.c

@@ -405,10 +405,10 @@ remove_source_output (PvStream *stream)
 /**
  * pv_stream_connect_capture:
  * @stream: a #PvStream
- * @device: the device name to connect to
+ * @source: the source name to connect to
  * @flags: a #PvStreamFlags
  *
- * Connect @stream for capturing from @device.
+ * Connect @stream for capturing from @source.
  *
  * Returns: %TRUE on success.
  */
@@ -460,11 +460,7 @@ pv_stream_disconnect (PvStream *stream)
   return TRUE;
 }
 
-
+#include <gst/wire-protocol.h>
-typedef struct {
-  guint64 offset;
-  guint64 size;
-} FDMessage;
 
 static gboolean
 on_socket_data (GSocket       *socket,
@@ -502,6 +498,11 @@ on_socket_data (GSocket       *socket,
 
       if (priv->info.message)
         g_object_unref (priv->info.message);
+
+      priv->info.flags = msg.flags;
+      priv->info.seq = msg.seq;
+      priv->info.pts = msg.pts;
+      priv->info.dts_offset = msg.dts_offset;
       priv->info.offset = msg.offset;
       priv->info.size = msg.size;
       priv->info.message = num_messages > 0 ? messages[0] : NULL;
@@ -641,7 +642,7 @@ exit_error:
  * When @mode is #PV_STREAM_MODE_SOCKET, you should connect to the notify::socket
  * signal to obtain a readable socket with metadata and data.
  *
- * When @mode is ##PV_STREAM_MODE_BUFFER, you should connect to the new-buffer
+ * When @mode is #PV_STREAM_MODE_BUFFER, you should connect to the new-buffer
  * signal and use pv_stream_capture_buffer() to get the latest metadata and
  * data.
  *

src/client/pv-stream.h

@@ -55,8 +55,10 @@ typedef enum {
 } PvStreamFlags;
 
 typedef struct {
-  gint64 timestamp;
+  guint32 flags;
-  guint64 seq;
+  guint32 seq;
+  gint64 pts;
+  gint64 dts_offset;
   guint64 offset;
   guint64 size;
   GSocketControlMessage *message;

src/server/pv-client.c

@@ -274,10 +274,12 @@ pv_client_init (PvClient * client)
 
 /**
  * pv_client_new:
+ * @daemon: a #PvDaemon
+ * @prefix: a prefix
  *
- * Make a new unconnected #PvClient
+ * Make a new #PvClient object and register it to @daemon under the @prefix.
  *
- * Returns: a new unconnected #PvClient
+ * Returns: a new #PvClient
  */
 PvClient *
 pv_client_new (PvDaemon * daemon, const gchar *prefix)
@@ -288,6 +290,14 @@ pv_client_new (PvDaemon * daemon, const gchar *prefix)
   return g_object_new (PV_TYPE_CLIENT, "daemon", daemon, "object-path", prefix, NULL);
 }
 
+/**
+ * pv_client_get_object_path:
+ * @client: a #PvClient
+ *
+ * Get the object path of @client.
+ *
+ * Returns: the object path of @client
+ */
 const gchar *
 pv_client_get_object_path (PvClient *client)
 {

src/server/pv-daemon.c

@@ -297,12 +297,25 @@ name_lost_handler (GDBusConnection *connection,
   g_dbus_object_manager_server_set_connection (manager, connection);
 }
 
+/**
+ * pv_daemon_new:
+ *
+ * Make a new #PvDaemon object
+ *
+ * Returns: a new #PvDaemon
+ */
 PvDaemon *
 pv_daemon_new (void)
 {
   return g_object_new (PV_TYPE_DAEMON, NULL);
 }
 
+/**
+ * pv_daemon_start:
+ * @daemon: a #PvDaemon
+ *
+ * Start the @daemon.
+ */
 void
 pv_daemon_start (PvDaemon *daemon)
 {
@@ -323,6 +336,12 @@ pv_daemon_start (PvDaemon *daemon)
                              NULL);
 }
 
+/**
+ * pv_daemon_stop:
+ * @daemon: a #PvDaemon
+ *
+ * Stop the @daemon.
+ */
 void
 pv_daemon_stop (PvDaemon *daemon)
 {
@@ -330,10 +349,21 @@ pv_daemon_stop (PvDaemon *daemon)
 
   g_return_if_fail (PV_IS_DAEMON (daemon));
 
+  if (priv->id != 0) {
     g_bus_unown_name (priv->id);
     priv->id = 0;
   }
+}
 
+/**
+ * pv_daemon_export_uniquely:
+ * @daemon: a #PvDaemon
+ * @skel: a #GDBusObjectSkeleton
+ *
+ * Export @skel with @daemon with a unique name
+ *
+ * Returns: the unique named used to export @skel.
+ */
 gchar *
 pv_daemon_export_uniquely (PvDaemon *daemon, GDBusObjectSkeleton *skel)
 {
@@ -345,6 +375,13 @@ pv_daemon_export_uniquely (PvDaemon *daemon, GDBusObjectSkeleton *skel)
   return g_strdup (g_dbus_object_get_object_path (G_DBUS_OBJECT (skel)));
 }
 
+/**
+ * pv_daemon_unexport:
+ * @daemon: a #PvDaemon
+ * @object_path: an object path
+ *
+ * Unexport the object on @object_path
+ */
 void
 pv_daemon_unexport (PvDaemon *daemon, const gchar *object_path)
 {
@@ -354,6 +391,13 @@ pv_daemon_unexport (PvDaemon *daemon, const gchar *object_path)
   g_dbus_object_manager_server_unexport (daemon->priv->server_manager, object_path);
 }
 
+/**
+ * pv_daemon_add_source:
+ * @daemon: a #PvDaemon
+ * @source: a #PvSource
+ *
+ * Register @source with @daemon so that it becomes available to clients.
+ */
 void
 pv_daemon_add_source (PvDaemon *daemon, PvSource *source)
 {
@@ -366,6 +410,13 @@ pv_daemon_add_source (PvDaemon *daemon, PvSource *source)
   pv_source_set_manager (source, priv->server_manager);
 }
 
+/**
+ * pv_daemon_remove_source:
+ * @daemon: a #PvDaemon
+ * @source: a #PvSource
+ *
+ * Unregister @source from @daemon so that it becomes unavailable to clients.
+ */
 void
 pv_daemon_remove_source (PvDaemon *daemon, PvSource *source)
 {
@@ -375,6 +426,15 @@ pv_daemon_remove_source (PvDaemon *daemon, PvSource *source)
   pv_source_set_manager (source, NULL);
 }
 
+/**
+ * pv_daemon_get_source:
+ * @daemon: a #PvDaemon
+ * @name: a name
+ *
+ * Find a #PvSource1 for @name in @daemon
+ *
+ * Returns: a #PvSource1
+ */
 PvSource1 *
 pv_daemon_get_source (PvDaemon *daemon, const gchar *name)
 {