Top | ![]() |
![]() |
![]() |
![]() |
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 () |
enum | InfinotedParameterType |
enum | InfinotedParameterFlags |
union | InfinotedParameterValue |
struct | InfinotedParameterTypedValue |
struct | InfinotedParameterInfo |
enum | InfinotedParameterError |
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.
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()
.
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()
.
A new InfinotedParameterTypedValue. Free with
infinoted_parameter_typed_value_free()
when no longer needed.
InfinotedParameterTypedValue *
infinoted_parameter_typed_value_copy (const InfinotedParameterTypedValue *val
);
Makes a dynamically allocated copy of val
.
A new InfinotedParameterTypedValue. Free with
infinoted_parameter_typed_value_free()
when no longer needed.
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.
GQuark
infinoted_parameter_error_quark (void
);
Returns the GQuark for errors from the InfinotedParameter module.
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. |
[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 |
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.
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.
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.
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.
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.
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. |
[type InfXmppConnectionSecurityPolicy*][out] |
in |
The pointer to the input string location. |
[type gchar**][in] |
error |
Location to store error information, if any, or |
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.
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.
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.
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*.
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 |
Additional flags for parameters that can be given to infinoted plugins.
Holds the value of a infinoted parameter. The type of the parameter must be known. See also InfinotedParameterTypedValue.
The parameter value for type |
||
The parameter value for type |
||
The parameter value for type |
||
The parameter value for type |
struct InfinotedParameterTypedValue { InfinotedParameterType type; InfinotedParameterValue value; };
Holds the type and value of a parameter that can be passed to an infinoted plugin.
InfinotedParameterType |
The type of the parameter. |
|
InfinotedParameterValue |
The value of the parameter. |
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.
The name of the parameter. |
||
InfinotedParameterType |
The input type of the parameter. |
|
InfinotedParameterFlags |
Additional flags for the parameter. |
|
Offset of the output value in the structure of the plugin. Should
be determined with |
||
InfinotedParameterConvertFunc |
The conversion function for the parameter, see InfinotedParameterConvertFunc. |
|
A short name (one character) for the parameter, used for command line option parsing. |
||
A description for the parameter that can be shown in
|
||
A description for the argument of the parameter in
|
Specifies the possible error conditions for errors in the
INFINOTED_PARAMETER_ERROR
domain. These typically
occur when parsing and processing input parameters for plugins.
A parameter is required but was not provided to the plugin. |
||
The number given as a parameter is not valid, for example a negative time interval. |
||
The flag with the given name does not exist. |
||
A security policy given as a parameter is not valid. The only allowed values are "no-tls", "allow-tls", and "require-tls". |
||
The value given as a parameter is not a valid IP address. |