InfinotedParameter

InfinotedParameter — Declare parameters of infinoted plugins.

Stability Level

Unstable, unless otherwise indicated

Functions

Types and Values

Object Hierarchy

    GBoxed
    ╰── InfinotedParameterTypedValue

Includes

#include <infinoted/infinoted-parameter.h>

Description

The InfinotedParameterInfo structure allows to declare a parameter that can then be used as an input value to a plugin. While the types for input data are limited, the mechanism allows to provide a powerful validation and transformation function which can turn the input value to the final internal representation in the plugin data structure.

Parameters are declared by providing a InfinotedParameterInfo structure, and an array of such structures is then given to InfinotedPlugin which declares a plugin.

Functions

InfinotedParameterConvertFunc ()

gboolean
(*InfinotedParameterConvertFunc) (gpointer out,
                                  gpointer in,
                                  GError **error);

Definition of a parameter conversion function. A parameter conversion function transforms the value of a read which is one of the InfinotedParameterValue enumeration to its final internal representation. It can change the C type of the parameter, and it can also validate the input and produce an error if the input value is invalid.

While plugin developers can write their own conversion functions, many are already provided by libinfinoted-plugin-manager that cover the most basic usecases. These functions are infinoted_parameter_convert_string(), infinoted_parameter_convert_string_list(), infinoted_parameter_convert_filename(), infinoted_parameter_convert_boolean(), infinoted_parameter_convert_port(), infinoted_parameter_convert_nonnegative(), infinoted_parameter_convert_positive(), infinoted_parameter_convert_security_policy() and infinoted_parameter_convert_ip_address().

Parameters

out

Location where the converted value should be written to.

 

in

Location where the original input value should be taken from.

 

error

Location for error information, if any, or NULL.

 

Returns

TRUE on success or FALSE if an error occurred.


infinoted_parameter_typed_value_new ()

InfinotedParameterTypedValue *
infinoted_parameter_typed_value_new (void);

Creates a new instance of a InfinotedParameterTypedValue . The new instance will be uninitialized. Its type and value members need to be set before the object can be used or given to infinoted_parameter_typed_value_free().

Returns

A new InfinotedParameterTypedValue. Free with infinoted_parameter_typed_value_free() when no longer needed.


infinoted_parameter_typed_value_copy ()

InfinotedParameterTypedValue *
infinoted_parameter_typed_value_copy (const InfinotedParameterTypedValue *val);

Makes a dynamically allocated copy of val .

Parameters

val

The value to copy.

 

Returns

A new InfinotedParameterTypedValue. Free with infinoted_parameter_typed_value_free() when no longer needed.


infinoted_parameter_typed_value_free ()

void
infinoted_parameter_typed_value_free (gpointer data);

Frees an instance of InfinotedParameterTypedValue. Formally the argument is kept as a generic pointer so that this function can be used as a GDestroyNotify callback.

Note that the InfinotedParameterTypedValue needs to be correctly initialized, i.e. its type must be set, before it can be freed.

Parameters

data

The InfinotedParameterTypedValue to free.

 

infinoted_parameter_error_quark ()

GQuark
infinoted_parameter_error_quark (void);

Returns the GQuark for errors from the InfinotedParameter module.

Returns

The error domain for the InfinotedParameter module.


infinoted_parameter_load_from_key_file ()

gboolean
infinoted_parameter_load_from_key_file
                               (const InfinotedParameterInfo *infos,
                                GKeyFile *key_file,
                                const gchar *group,
                                gpointer base,
                                GError **error);

Attempts to read each parameter in infos from key_file and store them in a user-specified structure base . The offset field of InfinotedParameterInfo specifies where inside base the read parameter value will be written, and the convert field specifies a function which converts the parameter type (integer, string or string list) into the type of the field in the target structure.

If the key file does not have an entry for one of the entries in infos , then the current value in the base structure is untouched. This allows setting default values prior to calling this function.

If the function fails, for example because the conversion into the target type failed (which, in turn, might be due to invalid user input), FALSE is returned and error is set.

Parameters

infos

A 0-terminated array of InfinotedParameterInfo objects.

[array zero-terminated=1]

key_file

The GKeyFile to load parameter values from.

 

group

The keyfile group to load the values from.

 

base

The instance into which to write the read parameters.

 

error

Location to store error information, if any, or NULL.

 

Returns

TRUE on success, otherwise FALSE.


infinoted_parameter_convert_boolean ()

gboolean
infinoted_parameter_convert_boolean (gpointer out,
                                     gpointer in,
                                     GError **error);

This function simply writes the boolean value from in to out without any further validation.

This is a InfinotedParameterConvertFunc function that can be used for boolean values.

Parameters

out

The pointer to the output gboolean.

[type gboolean*][out]

in

The pointer to the input gboolean.

[type gboolean*][in]

error

Location to store error information, if any, or NULL.

 

Returns

This function always returns TRUE.


infinoted_parameter_convert_filename ()

gboolean
infinoted_parameter_convert_filename (gpointer out,
                                      gpointer in,
                                      GError **error);

This function converts the input string from UTF-8 to the Glib file name encoding.

This is a InfinotedParameterConvertFunc function that can be used for strings that should be in Glib file name encoding format instead of UTF-8.

Parameters

out

The pointer to the output string location.

[type gchar**][out]

in

A pointer to the input string location.

[type gchar**][in]

error

Location to store error information, if any, or NULL.

 

Returns

TRUE on success, or FALSE otherwise.


infinoted_parameter_convert_nonnegative ()

gboolean
infinoted_parameter_convert_nonnegative
                               (gpointer out,
                                gpointer in,
                                GError **error);

This function validates the input number to be non-negative, and converts it into an unsigned integer.

This is a InfinotedParameterConvertFunc function that can be used for any non-negative numbers.

Parameters

out

The pointer to the output guint.

[type guint*][out]

in

The pointer to the input gint.

[type gint*][in]

error

Location to store error information, if any, or NULL.

 

Returns

TRUE on success, or FALSE otherwise.


infinoted_parameter_convert_port ()

gboolean
infinoted_parameter_convert_port (gpointer out,
                                  gpointer in,
                                  GError **error);

This function validates the input number to be in the valid range for TCP or UDP ports between 1 and 65535, and converts it to an unsigned integer.

This is a InfinotedParameterConvertFunc function that can be used for TCP or UDP port numbers.

Parameters

out

The pointer to the output guint.

[type guint*][out]

in

The pointer to the input gint.

[type gint*][in]

error

Location to store error information, if any, or NULL.

 

Returns

TRUE on success, or FALSE otherwise.


infinoted_parameter_convert_positive ()

gboolean
infinoted_parameter_convert_positive (gpointer out,
                                      gpointer in,
                                      GError **error);

This function validates the input number to be positve, i.e. greater than zero, and converts it into an unsigned integer.

This is a InfinotedParameterConvertFunc function that can be used for any non-negative numbers.

Parameters

out

The pointer to the output guint.

[type guint*][out]

in

The pointer to the input gint.

[type gint*][in]

error

Location to store error information, if any, or NULL.

 

Returns

TRUE on success, or FALSE otherwise.


infinoted_parameter_convert_security_policy ()

gboolean
infinoted_parameter_convert_security_policy
                               (gpointer out,
                                gpointer in,
                                GError **error);

Converts the string that in points to to an InfXmppConnectionSecurityPolicy value, by requiring that it is either "no-tls", "allow-tls" or "require-tls". If the string is none of these three the function fails and error is set.

This is a InfinotedParameterConvertFunc function that can be used for fields of type InfXmppConnectionSecurityPolicy.

Parameters

out

The pointer to the output InfXmppConnectionSecurityPolicy.

[type InfXmppConnectionSecurityPolicy*][out]

in

The pointer to the input string location.

[type gchar**][in]

error

Location to store error information, if any, or NULL.

 

Returns

TRUE on success, or FALSE otherwise.


infinoted_parameter_convert_string ()

gboolean
infinoted_parameter_convert_string (gpointer out,
                                    gpointer in,
                                    GError **error);

This is basically a no-op, moving the string from the in location to the out location. In case in points to the empty string, it is freed and the output string is set to be NULL.

This is a InfinotedParameterConvertFunc function that can be used for strings that should not be processed further or validated.

Parameters

out

The pointer to the output string location.

[type gchar**][out]

in

A pointer to the input string location.

[type gchar**][in]

error

Location to store error information, if any, or NULL.

 

Returns

This function always returns TRUE.


infinoted_parameter_convert_string_list ()

gboolean
infinoted_parameter_convert_string_list
                               (gpointer out,
                                gpointer in,
                                GError **error);

This is basically a no-op, moving the string list from the in location to the out location. In case in points to an empty string list, or to a string list with only one entry which is the empty string, then the string list is freed and the output string list is set to be NULL.

This is a InfinotedParameterConvertFunc function that can be used for string lists that should not be processed further or validated.

Parameters

out

The pointer to the output string list.

[type gchar***][out]

in

The pointer to the input string list.

[type gchar***][array zero-terminated=1][in]

error

Location to store error information, if any, or NULL.

 

Returns

This function always returns TRUE.


infinoted_parameter_convert_flags ()

gboolean
infinoted_parameter_convert_flags (gpointer out,
                                   gpointer in,
                                   const GFlagsValue *values,
                                   GError **error);

Converts the string list that in points to to a bitmask. This function can not directly be used as a convert function as expected by InfinotedParameterInfo since it has an additional argument. However, an actual convert function can make use of this function.

Each string entry is interpreted as a value of a bitmask. The values list specifies which string constant corresponds to which flag value.

Parameters

out

The pointer to the output flags (a gint).

[type gint*][out]

in

The pointer to the input string list.

[type gchar***][in][array zero-terminated=1]

values

Allowed flag values.

 

error

Location to store error information, if any, or NULL.

 

Returns

TRUE on success, or FALSE otherwise.


infinoted_parameter_convert_ip_address ()

gboolean
infinoted_parameter_convert_ip_address
                               (gpointer out,
                                gpointer in,
                                GError **error);

Converts the string that in points to to an InfIpAddress* value. If the string can not be converted to an IP address, the functions fails and error is set.

This is a InfinotedParameterConvertFunc function that can be used for fields of type InfIpAddress*.

Parameters

out

The pointer to the output InfIpAddress location.

[type InfIpAddress**][out]

in

The pointer to the input string location.

[type gchar**][in]

error

Location to store error information, if any, or NULL.

 

Returns

TRUE on success, or FALSE otherwise.

Types and Values

enum InfinotedParameterType

Allowed types for a parameter that can be given to a infinoted plugin.

Members

INFINOTED_PARAMETER_BOOLEAN

A boolean parameter.

 

INFINOTED_PARAMETER_INT

A signed integer parameter.

 

INFINOTED_PARAMETER_STRING

A string parameter.

 

INFINOTED_PARAMETER_STRING_LIST

An array of strings.

 

enum InfinotedParameterFlags

Additional flags for parameters that can be given to infinoted plugins.

Members

INFINOTED_PARAMETER_REQUIRED

The parameter is required and cannot be omitted.

 

union InfinotedParameterValue

Holds the value of a infinoted parameter. The type of the parameter must be known. See also InfinotedParameterTypedValue.

Members

gboolean yesno;

The parameter value for type INFINOTED_PARAMETER_BOOLEAN.

 

gint number;

The parameter value for type INFINOTED_PARAMETER_INT.

 

gchar *str;

The parameter value for type INFINOTED_PARAMETER_STRING.

 

gchar **strv;

The parameter value for type INFINOTED_PARAMETER_STRING_LIST.

 

struct InfinotedParameterTypedValue

struct InfinotedParameterTypedValue {
  InfinotedParameterType type;
  InfinotedParameterValue value;
};

Holds the type and value of a parameter that can be passed to an infinoted plugin.

Members

InfinotedParameterType type;

The type of the parameter.

 

InfinotedParameterValue value;

The value of the parameter.

 

struct InfinotedParameterInfo

struct InfinotedParameterInfo {
  const char* name;
  InfinotedParameterType type;
  InfinotedParameterFlags flags;
  size_t offset;
  InfinotedParameterConvertFunc convert;
  char short_name;
  const char* description;
  const char* arg_description;
};

This structure contains generic information about a parameter that can be passed to an infinoted plugin.

Members

const char *name;

The name of the parameter.

 

InfinotedParameterType type;

The input type of the parameter.

 

InfinotedParameterFlags flags;

Additional flags for the parameter.

 

size_t offset;

Offset of the output value in the structure of the plugin. Should be determined with G_STRUCT_OFFSET.

 

InfinotedParameterConvertFunc convert;

The conversion function for the parameter, see InfinotedParameterConvertFunc.

 

char short_name;

A short name (one character) for the parameter, used for command line option parsing.

 

const char *description;

A description for the parameter that can be shown in --help output

 

const char *arg_description;

A description for the argument of the parameter in --help output, if any.

 

enum InfinotedParameterError

Specifies the possible error conditions for errors in the INFINOTED_PARAMETER_ERROR domain. These typically occur when parsing and processing input parameters for plugins.

Members

INFINOTED_PARAMETER_ERROR_REQUIRED

A parameter is required but was not provided to the plugin.

 

INFINOTED_PARAMETER_ERROR_INVALID_NUMBER

The number given as a parameter is not valid, for example a negative time interval.

 

INFINOTED_PARAMETER_ERROR_INVALID_FLAG

The flag with the given name does not exist.

 

INFINOTED_PARAMETER_ERROR_INVALID_SECURITY_POLICY

A security policy given as a parameter is not valid. The only allowed values are "no-tls", "allow-tls", and "require-tls".

 

INFINOTED_PARAMETER_ERROR_INVALID_IP_ADDRESS

The value given as a parameter is not a valid IP address.