InfinotedParameter

InfinotedParameter — Declare parameters of infinoted plugins.

Stability Level

Unstable, unless otherwise indicated

Synopsis

#include <infinoted/infinoted-parameter.h>

enum                InfinotedParameterType;
enum                InfinotedParameterFlags;
union               InfinotedParameterValue;
struct              InfinotedParameterTypedValue;
gboolean            (*InfinotedParameterConvertFunc)    (gpointer out,
                                                         gpointer in,
                                                         GError **error);
struct              InfinotedParameterInfo;
enum                InfinotedParameterError;
InfinotedParameterTypedValue * infinoted_parameter_typed_value_new
                                                        (void);
void                infinoted_parameter_typed_value_free
                                                        (gpointer data);
GQuark              infinoted_parameter_error_quark     (void);
gboolean            infinoted_parameter_load_from_key_file
                                                        (const InfinotedParameterInfo *infos,
                                                         GKeyFile *key_file,
                                                         const gchar *group,
                                                         gpointer base,
                                                         GError **error);
gboolean            infinoted_parameter_convert_boolean (gpointer out,
                                                         gpointer in,
                                                         GError **error);
gboolean            infinoted_parameter_convert_filename
                                                        (gpointer out,
                                                         gpointer in,
                                                         GError **error);
gboolean            infinoted_parameter_convert_nonnegative
                                                        (gpointer out,
                                                         gpointer in,
                                                         GError **error);
gboolean            infinoted_parameter_convert_port    (gpointer out,
                                                         gpointer in,
                                                         GError **error);
gboolean            infinoted_parameter_convert_positive
                                                        (gpointer out,
                                                         gpointer in,
                                                         GError **error);
gboolean            infinoted_parameter_convert_security_policy
                                                        (gpointer out,
                                                         gpointer in,
                                                         GError **error);
gboolean            infinoted_parameter_convert_string  (gpointer out,
                                                         gpointer in,
                                                         GError **error);
gboolean            infinoted_parameter_convert_string_list
                                                        (gpointer out,
                                                         gpointer in,
                                                         GError **error);

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.

Details

enum InfinotedParameterType

typedef enum {
  INFINOTED_PARAMETER_BOOLEAN,
  INFINOTED_PARAMETER_INT,
  INFINOTED_PARAMETER_STRING,
  INFINOTED_PARAMETER_STRING_LIST
} InfinotedParameterType;

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

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

typedef enum {
  INFINOTED_PARAMETER_REQUIRED = 1 << 0
} InfinotedParameterFlags;

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

INFINOTED_PARAMETER_REQUIRED

The parameter is required and cannot be omitted.

union InfinotedParameterValue

union _InfinotedParameterValue {
  gboolean yesno;
  gint number;
  gchar* str;
  gchar** strv;
};

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

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.

InfinotedParameterType type;

The type of the parameter.

InfinotedParameterValue value;

The value of the parameter.

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(), and infinoted_parameter_convert_security_policy().

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.

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.

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

typedef enum {
  INFINOTED_PARAMETER_ERROR_REQUIRED,
  INFINOTED_PARAMETER_ERROR_INVALID_NUMBER,
  INFINOTED_PARAMETER_ERROR_INVALID_SECURITY_POLICY
} 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.

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

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.

infos :

A 0-terminated array of InfinotedParameterInfo objects.

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.

out :

The pointer to the output gboolean.

in :

The pointer to the input gboolean.

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.

out :

The pointer to the output string location.

in :

A pointer to the input string location.

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.

out :

The pointer to the output guint.

in :

The pointer to the input gint.

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.

out :

The pointer to the output guint.

in :

The pointer to the input gint.

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.

out :

The pointer to the output guint.

in :

The pointer to the input gint.

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.

out :

The pointer to the output InfXmppConnectionSecurityPolicy.

in :

The pointer to the input string location.

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.

out :

The pointer to the output string location.

in :

A pointer to the input string location.

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.

out :

The pointer to the output string list.

in :

The pointer to the input string list.

error :

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

Returns :

This function always returns TRUE.