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