## InfinotedParameter

InfinotedParameter — Declare parameters of infinoted plugins.

## Stability Level

Unstable, unless otherwise indicated

## Functions

gboolean | (*InfinotedParameterConvertFunc) ()
InfinotedParameterTypedValue * | infinoted_parameter_typed_value_new ()
InfinotedParameterTypedValue * | infinoted_parameter_typed_value_copy ()
void | infinoted_parameter_typed_value_free ()
GQuark | infinoted_parameter_error_quark ()
gboolean | infinoted_parameter_load_from_key_file ()
gboolean | infinoted_parameter_convert_boolean ()
gboolean | infinoted_parameter_convert_filename ()
gboolean | infinoted_parameter_convert_nonnegative ()
gboolean | infinoted_parameter_convert_port ()
gboolean | infinoted_parameter_convert_positive ()
gboolean | infinoted_parameter_convert_security_policy ()
gboolean | infinoted_parameter_convert_string ()
gboolean | infinoted_parameter_convert_string_list ()
gboolean | infinoted_parameter_convert_flags ()
gboolean | infinoted_parameter_convert_ip_address ()

## Types and Values

enum | InfinotedParameterType
enum | InfinotedParameterFlags
union | InfinotedParameterValue
struct | InfinotedParameterTypedValue
struct | InfinotedParameterInfo
enum | InfinotedParameterError

## 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. |