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@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