[X2Go-Commits] [libx2goclient] 12/132: src/x2goclient-network.c: document API and a corresponding private function.

git-admin at x2go.org git-admin at x2go.org
Fri Dec 3 15:26:28 CET 2021


This is an automated email from the git hooks/post-receive script.

x2go pushed a commit to branch master
in repository libx2goclient.

commit e8677acb98bed7c1416a90bccbf615b610630745
Author: Mihai Moldovan <ionic at ionic.de>
Date:   Sat Oct 31 07:02:52 2020 +0100

    src/x2goclient-network.c: document API and a corresponding private function.
---
 src/x2goclient-network.c | 179 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 179 insertions(+)

diff --git a/src/x2goclient-network.c b/src/x2goclient-network.c
index 1a4da7e..a5cb1ad 100644
--- a/src/x2goclient-network.c
+++ b/src/x2goclient-network.c
@@ -33,6 +33,23 @@
 #include "x2goclient.h"
 #include "x2goclient-network.h"
 
+/**
+ * SECTION:X2GoClientNetworkOptions
+ * @short_description: Abstract base class encapsulating network options
+ * @stability: Unstable
+ * @include: libx2goclient/x2goclient-network.h
+ *
+ * #X2GoClientNetworkOptions is an abstract base class used to encapsulate
+ * network options.
+ *
+ * Currently, there are no common options that could be used generically for
+ * all dependent classes, so it's essentially fully empty (yet providing the
+ * general skeleton).
+ *
+ * An example of a more concrete implementation is
+ * #X2GoClientNetworkOptionsSSH.
+ */
+
 /* Not sure if we need this, so comment out for now. */
 /*
 typedef struct X2GoClientNetworkOptionsPrivate_ {
@@ -49,6 +66,28 @@ static void x2goclient_network_options_init (X2GoClientNetworkOptions * const se
 }
 
 
+/**
+ * SECTION:X2GoClientNetwork
+ * @short_description: Abstract base class representing network connections
+ * @stability: Unstable
+ * @include: libx2goclient/x2goclient-network.h
+ *
+ * #X2GoClientNetwork is an abstract base class providing a common interface
+ * for network connections.
+ *
+ * These are basic functions and behaviors that every dependent class must
+ * implement, rely upon and obey.
+ *
+ * An example of a more concrete implementation is #X2GoClientNetworkSSH.
+ */
+
+/**
+ * X2GoClientNetwork:
+ *
+ * #X2GoClientNetwork is an opaque data structure and can only be accessed
+ * using the following functions.
+ */
+
 typedef struct X2GoClientNetworkPrivate_ {
   GString *socket_spec;
   GSocketAddress *socket;
@@ -99,18 +138,62 @@ static void x2goclient_network_class_init (X2GoClientNetworkClass * const klass)
   object_class->set_property = &x2goclient_network_set_property;
   object_class->get_property = &x2goclient_network_get_property;
 
+  /**
+   * X2GoClientNetwork:socket-spec:
+   *
+   * A low-level socket specification as a string.
+   *
+   * It is write-only.
+   *
+   * It updates the #X2GoClientNetwork:socket property accordingly.
+   *
+   * Note that, if parsing the socket specification failed,
+   * #X2GoClientNetwork:socket will be %NULL. This is also the case if no
+   * parsing function has been set.
+   *
+   * See also x2goclient_network_parse_sockspec().
+   *
+   * Since: 0.0.5
+   */
   net_obj_properties[X2GO_NET_PROP_SOCKET_SPEC] = g_param_spec_boxed ("socket-spec", _("Low-level socket string specification"),
                                                                       _("String specification for the low-level socket network "
                                                                       "connection. Updates the \"socket\" property."),
                                                                       G_TYPE_GSTRING,
                                                                       G_PARAM_STATIC_STRINGS | G_PARAM_WRITABLE);
 
+  /**
+   * X2GoClientNetwork:socket:
+   *
+   * A low-level #GSocketAddress object, representing the parsed remote socket
+   * address.
+   *
+   * It is read-only.
+   *
+   * It can be %NULL if no socket specifier has been provided yet or parsing
+   * one failed.
+   *
+   * If a local part as been specified, it will be used as the socket's local
+   * (i.e., outgoing) binding address.
+   *
+   * FIXME: the "local part" as described here is not implemented.
+   *
+   * Since: 0.0.5
+   */
   net_obj_properties[X2GO_NET_PROP_SOCKET] = g_param_spec_object ("socket", _("Low-level socket"),
                                                                   _("Low-level socket for the network connection, the local "
                                                                   "part will be used for local binding if specified."),
                                                                   G_TYPE_SOCKET_ADDRESS,
                                                                   G_PARAM_STATIC_STRINGS | G_PARAM_READABLE);
 
+  /**
+   * X2GoClientNetwork:options:
+   *
+   * A mutable #X2GoClientNetworkOptions object encapsulating network options.
+   *
+   * Can be %NULL if not set previously.
+   *
+   * Since: 0.0.5
+   */
   net_obj_properties[X2GO_NET_PROP_OPTIONS] = g_param_spec_object ("options", _("Socket options"),
                                                                    _("Specific socket options."),
                                                                    X2GOCLIENT_TYPE_NETWORK_OPTIONS,
@@ -118,6 +201,16 @@ static void x2goclient_network_class_init (X2GoClientNetworkClass * const klass)
 
   GString *default_session_path = g_string_new (g_get_home_dir ());
   g_string_append (default_session_path, "/.libx2goclient/");
+  /**
+   * X2GoClientNetwork:session-path:
+   *
+   * A string representing the base file system path to session data.
+   *
+   * It can only be set at the object's creation time and is immutable
+   * following the constructions.
+   *
+   * Since: 0.0.5
+   */
   net_obj_properties[X2GO_NET_PROP_SESSION_PATH] = g_param_spec_string ("session-path", _("Base path to session data"),
                                                                         _("The file system path that will be used as the "
                                                                           "session data base path. Connection-related files "
@@ -127,17 +220,49 @@ static void x2goclient_network_class_init (X2GoClientNetworkClass * const klass)
   g_boxed_free (G_TYPE_GSTRING, default_session_path);
   default_session_path = NULL;
 
+  /**
+   * X2GoClientNetwork:connected:
+   *
+   * This boolean value denotes whether a connection has been established or
+   * not.
+   *
+   * It is read-only.
+   *
+   * Since: 0.0.5
+   */
   net_obj_properties[X2GO_NET_PROP_CONNECTED] = g_param_spec_boolean ("connected", _("Boolean for connected state"),
                                                                       _("Boolean value denoting whether a connection has "
                                                                         "been established or not."),
                                                                       FALSE,
                                                                       G_PARAM_STATIC_STRINGS | G_PARAM_READABLE);
 
+  /**
+   * X2GoClientNetwork:connect-function:
+   *
+   * This property holds a pointer to the instance's connect function.
+   *
+   * It is read-only.
+   *
+   * Use it to fetch the parent's connect function in derived classes.
+   *
+   * Since: 0.0.5
+   */
   net_obj_properties[X2GO_NET_PROP_CONN_FUNC] = g_param_spec_pointer ("connect-function", _("Pointer to this instance's connect function"),
                                                                       _("A pointer to the instance's connect function. "
                                                                         "This is supposed to be immutable."),
                                                                       G_PARAM_STATIC_STRINGS | G_PARAM_READABLE);
 
+  /**
+   * X2GoClientNetwork:disconnect-function:
+   *
+   * This property holds a pointer to the instance's disconnect function.
+   *
+   * It is read-only.
+   *
+   * Use it to fetch the parent's disconnect function in derived classes.
+   *
+   * Since: 0.0.5
+   */
   net_obj_properties[X2GO_NET_PROP_DISCONN_FUNC] = g_param_spec_pointer ("disconnect-function", _("Pointer to this instance's disconnect function"),
                                                                          _("A pointer to the instance's disconnect function. "
                                                                            "This is supposed to be immutable."),
@@ -183,6 +308,21 @@ static void x2goclient_network_finalize (GObject * const object) {
 }
 
 
+/*
+ * x2goclient_network_parse_sockspec:
+ * @self: (in) (not optional): an #X2GoClientNetwork.
+ * @sockspec: (in) (not optional): socket specification as a pointer to a
+ *                                 #GString.
+ *
+ * Takes a socket specification and passes it down to the actual parsing
+ * function if one has been set.
+ *
+ * Returns: (transfer full): a pointer to the parsed result as a
+ *                           #GSocketAddress. %NULL on error or if no parsing
+ *                           function has been set.
+ *
+ * Since: 0.0.5
+ */
 static GSocketAddress* x2goclient_network_parse_sockspec (X2GoClientNetwork * const self, const GString * const sockspec) {
   GSocketAddress *ret = NULL;
 
@@ -196,6 +336,25 @@ static GSocketAddress* x2goclient_network_parse_sockspec (X2GoClientNetwork * co
   return (ret);
 }
 
+/**
+ * x2goclient_network_connect:
+ * @self: (in) (not optional): an #X2GoClientNetwork.
+ * @gerr: (out) (nullable): a return location for a #GError, pass %NULL if not
+ *                          interested.
+ *
+ * Connects to a remote location.
+ *
+ * This function uses the #X2GoClientNetworkClass::connect virtual method to
+ * actually connect. By default, this virtual method is unset (or rather, set
+ * to %NULL). Make sure to probably initialize it in your derived class.
+ *
+ * This function is idempotent.
+ *
+ * Returns: %TRUE if the connection was established successful or it is
+ *          already running, %FALSE on error.
+ *
+ * Since: 0.0.5
+ */
 gboolean x2goclient_network_connect (X2GoClientNetwork * const self, GError ** const gerr) {
   gboolean ret = FALSE;
 
@@ -217,6 +376,26 @@ gboolean x2goclient_network_connect (X2GoClientNetwork * const self, GError ** c
   return (ret);
 }
 
+/**
+ * x2goclient_network_disconnect:
+ * @self: (in) (not optional): an #X2GoClientNetwork.
+ * @gerr: (out) (nullable): a return location for a #GError, pass %NULL if not
+ *                          interested.
+ *
+ * Disconnects from a remote location.
+ *
+ * This function uses the #X2GoClientNetworkClass::disconnect virtual method
+ * to actually disconnect. By default, this virtual method is unset (or
+ * rather, set to %NULL). Make sure to probably initialize it in your derived
+ * class.
+ *
+ * This function is idempotent.
+ *
+ * Returns: %TRUE if the connection was successfully destroyed or there was
+ *          none to begin with, %FALSE on error.
+ *
+ * Since: 0.0.5
+ */
 gboolean x2goclient_network_disconnect (X2GoClientNetwork * const self, GError ** const gerr) {
   gboolean ret = FALSE;
 

--
Alioth's /home/x2go-admin/maintenancescripts/git/hooks/post-receive-email on /srv/git/code.x2go.org/libx2goclient.git


More information about the x2go-commits mailing list