[X2Go-Commits] [libx2goclient] 45/132: src/x2goclient-openssh-version.c: document full class.
git-admin at x2go.org
git-admin at x2go.org
Fri Dec 3 15:26:30 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 f4dd721fae7c6d91e6d538824da260077f644d1a
Author: Mihai Moldovan <ionic at ionic.de>
Date: Thu Apr 29 13:19:18 2021 +0200
src/x2goclient-openssh-version.c: document full class.
---
src/x2goclient-openssh-version.c | 210 +++++++++++++++++++++++++++++++++++++++
1 file changed, 210 insertions(+)
diff --git a/src/x2goclient-openssh-version.c b/src/x2goclient-openssh-version.c
index a2c4c5d..447d60c 100644
--- a/src/x2goclient-openssh-version.c
+++ b/src/x2goclient-openssh-version.c
@@ -35,6 +35,22 @@
#include "x2goclient-openssh-version.h"
#include "x2goclient-utils.h"
+/**
+ * SECTION:X2GoClientOpenSSHVersion
+ * @short_description: Class encapsulating and parsing OpenSSH client versions
+ * @stability: Unstable
+ * @include: libx2goclient/x2goclient-openssh-version.h
+ *
+ * #X2GoClientOpenSSHVersion is a class used to handle OpenSSH client
+ * versions.
+ *
+ * It provides a general structure for OpenSSH client versions and the
+ * necessary functions to parse an OpenSSH client version string as printed by
+ * the OpenSSH client when calling it with the <option>-V</option> option.
+ *
+ * Since: 0.0.5
+ */
+
X2GoClientOpenSSHVersion* x2goclient_openssh_version_new (void) {
return (g_slice_new0 (X2GoClientOpenSSHVersion));
}
@@ -56,10 +72,78 @@ static X2GoClientOpenSSHVersion* x2goclient_openssh_version_copy (const X2GoClie
G_DEFINE_BOXED_TYPE (X2GoClientOpenSSHVersion, x2goclient_openssh_version, &x2goclient_openssh_version_copy, &x2goclient_openssh_version_free)
+/*
+ * ERROR_QUARK:
+ *
+ * Expands into the error quark of this class.
+ *
+ * Since: 0.0.5
+ */
#define ERROR_QUARK EXPAND(X2GOCLIENT_OPENSSH_VERSION_ERROR)
+
+/*
+ * GENERATE_ERROR_:
+ * @preamble: (in) (not optional): class-common preamble.
+ * @component: (in) (not optional): component that is being handled, e.g.,
+ * <literal>MAJOR</literal>.
+ * @error: (in) (not optional): actual error part, e.g.,
+ * <literal>UNDERFLOW</literal>.
+ *
+ * Expands to a error macro produced by concatenating the
+ * three arguments with underscores as separators.
+ *
+ * Since: 0.0.5
+ */
#define GENERATE_ERROR_(preamble, component, error) preamble ## _ ## component ## _ ## error
+
+/*
+ * GENERATE_ERROR:
+ * @component: (in) (not optional): component that is being handled, e.g.,
+ * <literal>MAJOR</literal>.
+ * @error: (in) (not optional): actual error part, e.g.,
+ * <literal>UNDERFLOW</literal>.
+ *
+ * Wrapper hard-coding the preamble and passing the other arguments to
+ * GENERATE_ERROR().
+ *
+ * Since: 0.0.5
+ */
#define GENERATE_ERROR(component, error) GENERATE_ERROR_ (X2GOCLIENT_OPENSSH_VERSION_ERROR, component, error)
+
+/*
+ * GENERATE_ERROR_MSG_:
+ * @component: (in) (not optional): component that is being handled, e.g.,
+ * <literal>MAJOR</literal>.
+ * @msg: (in) (not optional): error message.
+ *
+ * Generates an error message by stringifying the @component and prepending it
+ * to the actual error message @msg, set apart by a space.
+ *
+ * Since: 0.0.5
+ */
#define GENERATE_ERROR_MSG_(component, msg) #component " " msg
+
+/*
+ * GENERATE_ERROR_MSG:
+ * @out_var: (out) (not optional): variable that will hold the generated error
+ * message.
+ * @idx_var: (in) (not optional): integer-based variable selecting the
+ * component.
+ * @msg: (in) (not optional): actual error message.
+ *
+ * Generates an error message and assigns the result to @out_var, which,
+ * obviously, should better be a string.
+ *
+ * The actual component is determined via @idx_var, an integer-based variable
+ * selecting a specific component. This mapping is currently hard-coded and
+ * "magical", so make sure that all code parts agree on which value maps to
+ * what component.
+ *
+ * The actual error message is generated by passing the mapped component and
+ * error message down to GENERATE_ERROR_MSG_().
+ *
+ * Since: 0.0.5
+ */
#define GENERATE_ERROR_MSG(out_var, idx_var, msg) \
do {\
X2GOCLIENT_CHECK_TYPE (char *, out_var);\
@@ -73,6 +157,31 @@ G_DEFINE_BOXED_TYPE (X2GoClientOpenSSHVersion, x2goclient_openssh_version, &x2go
out_var = GENERATE_ERROR_MSG_ ("Patch", msg);\
}\
} while (0)
+
+/*
+ * GENERATE_ERROR_CODE:
+ * @out_var: (out) (not optional): variable that will hold the generated error
+ * code/constant.
+ * @idx_var: (in) (not optional): integer-based variable selecting the
+ * component.
+ * @error: (in) (not optional): actual error code/constant.
+ *
+ * Generates an error code/constant and assigns the result to @out_var, which,
+ * obviously, should better be integer-based.
+ *
+ * This macro does not check for the validity of @out_var and its
+ * compatibility to hold an error code/constant.
+ *
+ * The actual component is determined via @idx_var, an integer-based variable
+ * selecting a specific component. This mapping is currently hard-coded and
+ * "magical", so make sure that all code parts agree on which value maps to
+ * what component.
+ *
+ * The actual error code/constant is generated by passing the mapped component
+ * and error code/constant down to GENERATE_ERROR().
+ *
+ * Since: 0.0.5
+ */
#define GENERATE_ERROR_CODE(out_var, idx_var, error) \
do {\
if (0 == idx_var) {\
@@ -86,6 +195,35 @@ G_DEFINE_BOXED_TYPE (X2GoClientOpenSSHVersion, x2goclient_openssh_version, &x2go
}\
} while (0)
+/*
+ * SET_VER_COMPONENT:
+ * @ver_struct: (out) (not optional): a pointer to the
+ * #X2GoClientOpenSSHVersion structure to
+ * modify.
+ * @idx_var: (in) (not optional): integer-based variable selecting the
+ * component.
+ * @value: (in) (not optional): new component value.
+ * @init: (in) (not optional): boolean value indicating initialization
+ *
+ * Updates the selected component on @ver_struct.
+ *
+ * If @init is set to %TRUE, @value is ignored and the corresponding component
+ * is set to <literal>0</literal> and marked as invalid. Otherwise, the
+ * component is set to @value and marked as valid.
+ *
+ * The actual component is determined via @idx_var, an integer-based variable
+ * selecting a specific component. This mapping is currently hard-coded and
+ * "magical", so make sure that all code parts agree on which value maps to
+ * what component.
+ *
+ * The type of @ver_struct is checked to make sure it matches what we expect
+ * using X2GOCLIENT_CHECK_TYPE(). The type of the actual component that is
+ * going to be updated is checked against the type of the provided value using
+ * X2GOCLIENT_CHECK_TYPE_TYPEOF(). The caveats described for the other macros
+ * apply here as well.
+ *
+ * Since: 0.0.5
+ */
#define SET_VER_COMPONENT(ver_struct, idx_var, value, init) \
do {\
X2GOCLIENT_CHECK_TYPE (X2GoClientOpenSSHVersion *, (ver_struct));\
@@ -125,8 +263,47 @@ G_DEFINE_BOXED_TYPE (X2GoClientOpenSSHVersion, x2goclient_openssh_version, &x2go
}\
} while (0)
+/*
+ * INIT_VER_COMPONENT:
+ * @ver_struct: (out) (not optional): a pointer to the
+ * #X2GoClientOpenSSHVersion structure to
+ * modify.
+ * @idx_var: (in) (not optional): integer-based variable selecting the
+ * component.
+ *
+ * Initializes the selected component on @ver_struct.
+ *
+ * This is just a convenience wrapper using SET_VER_COMPONENT().
+ *
+ * Since: 0.0.5
+ */
#define INIT_VER_COMPONENT(ver_struct, idx_var) SET_VER_COMPONENT ((ver_struct), (idx_var), (guint32)(0), TRUE)
+/*
+ * CHECK_VER_COMPONENT:
+ * @ver_struct: (in) (not optional): a pointer to the
+ * #X2GoClientOpenSSHVersion structure to
+ * check.
+ * @idx_var: (in) (not optional): integer-based variable selecting the
+ * component.
+ * @err: (out) (not optional): error variable, set if the component is
+ * invalid.
+ *
+ * Checks the selected component on @ver_struct by setting it to @value.
+ *
+ * The actual component is determined via @idx_var, an integer-based variable
+ * selecting a specific component. This mapping is currently hard-coded and
+ * "magical", so make sure that all code parts agree on which value maps to
+ * what component.
+ *
+ * The type of @ver_struct is checked to make sure it matches what we expect
+ * using X2GOCLIENT_CHECK_TYPE(). The type of the actual component that is
+ * going to be updated is checked against the type of the provided value using
+ * X2GOCLIENT_CHECK_TYPE_TYPEOF(). The caveats described for the other macros
+ * apply here as well.
+ *
+ * Since: 0.0.5
+ */
#define CHECK_VER_COMPONENT(ver_struct, idx_var, err) \
do {\
X2GOCLIENT_CHECK_TYPE (X2GoClientOpenSSHVersion *, (ver_struct));\
@@ -146,6 +323,26 @@ G_DEFINE_BOXED_TYPE (X2GoClientOpenSSHVersion, x2goclient_openssh_version, &x2go
}\
} while (0)
+/**
+ * x2goclient_openssh_version_parse:
+ * @openssh_version: (in) (not optional): a pointer to the
+ * #X2GoClientOpenSSHVersion structure
+ * to populate.
+ * @version_string: (in) (not optional): output of ssh -V to parse as a
+ * string.
+ * @gerr: (out) (nullable): a return location for a #GError, pass %NULL if not
+ * interested.
+ *
+ * Parses the version output given as @version_string and populates the
+ * version structure passed as @openssh_version with the parsed data on
+ * success.
+ *
+ * On error, doesn't touch @openssh_version.
+ *
+ * Returns: a #_Bool value indicating success (%TRUE) or failure (%FALSE).
+ *
+ * Since: 0.0.5
+ */
_Bool x2goclient_openssh_version_parse (X2GoClientOpenSSHVersion * const openssh_version, const gchar * const version_string, GError ** const gerr) {
_Bool ret = FALSE;
@@ -397,6 +594,19 @@ _Bool x2goclient_openssh_version_parse (X2GoClientOpenSSHVersion * const openssh
return (ret);
}
+/**
+ * x2goclient_openssh_version_fetch_openssh_version:
+ * @gerr: (out) (nullable): a return location for a #GError, pass %NULL if not
+ * interested.
+ *
+ * Fetches the OpenSSH version string as returned by "ssh -V" and parses this
+ * output into an #X2GoClientOpenSSHVersion structure.
+ *
+ * Returns: the populated #X2GoClientOpenSSHVersion structure on success or
+ * %NULL on error.
+ *
+ * Since: 0.0.5
+ */
X2GoClientOpenSSHVersion* x2goclient_openssh_version_fetch_openssh_version (GError ** const gerr) {
X2GoClientOpenSSHVersion *ret = NULL;
gboolean cont = 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