[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