Update of "Manual for lc_register_callback"
Overview

Artifact ID: f00ca8da5328c9efa1cbd401cdc0eda68d5ccd29
Page Name:Manual for lc_register_callback
Date: 2014-11-24 20:11:50
Original User: rkeene
Parent: 31daac3aebfbe2f560542663ec4c80bb2f9a6160
Content

NAME

lc_register_callback - Register a function for callback in config processing.

 

SYNOPSIS

#include <libconfig.h>

int lc_register_callback(const char *var, char opt, lc_var_type_t type, int (*callback)(const char *, const char *, const char *, const char *, lc_flags_t, void *), void *extra);

 

DESCRIPTION

The lc_register_callback(3) function registers a function to be called when var is encounted in a configuration file, command line, or environment variable. The parameters are as follows:
const char *var
The var parameter indicates the name of the variable to register for a callback when encountered in a configuration file, the environment, or as a long option. The var may be prefixed with "*." to indicate that the object can occur in any section or subsection.

const char opt
The opt parameter indicates the single charectar short option to use from the command line to invoke the register callback. A value of 0 indicates that no short option is acceptable.

lc_var_type_t type
The type parameter indicates the type of values that are acceptable for this callback. A value of LC_VAR_NONE means that the command will accept no arguments, while a value of LC_VAR_UNKNOWN indicates that it's not known whether or not an argument is applicable, this will also disable command line processing. Any other value is currently ignored.

int (*callback)(...)
The callback parameter indicates the name of the function to invoke when the above parameters are met. The specified function should take 6 parameters, see below for more information. This value may not be NULL.

void *extra
The extra parameter is a pointer that can be used to pass data to the callback upon invocation, it will not be mangled or examined by any function.

The arguments to the function specified as callback are as follows:

const char *shortvar
The shortvar parameter is the local variable name, provided as a convience. It is the portion of the variable name after the first "dot" (.) in the fully qualified variable name. The "dot" (.) value in the fully qualified variable name indicates a section or subsection that the variable belongs to. This may be NULL if the var parameter to lc_register_callback(3) was NULL too.
const char *var
The var parameter is the fully qualified variable name. It includes in the prefix any sections and subsections that contain this variable. This may be NULL if the var parameter to lc_register_callback(3) was NULL too.
const char *arguments
The arguments parameter provides the arguments passed to the variable, currently only sections may have arguments. This may be NULL if there were no arguments specified, or if arguments were not applicable.
const char *value
The value parameter provides the value of the variable specified. This may be NULL if no value was specified. Values are required if the type parameter to lc_register_callback(3) was not specified as one of LC_VAR_NONE, LC_VAR_SECTION, LC_VAR_SECTIONSTART, or LC_VAR_SECTIONEND.
lc_flags_t flags
The flags parameter provides information about the type of command being called. The valid values are:
LC_FLAGS_VAR
To indicate a regular variable in a configuration file.
LC_FLAGS_CMDLINE
To indicate a command line option has been used to invoke this option.
LC_FLAGS_SECTIONSTART
To indicate that this command represents the beginning of a section.
LC_FLAGS_SECTIONEND
To indicate that this command represents the end of a section.
void *extra
The extra parameter is just a copy of the extra parameter passed to lc_register_callback(3) when the callback was registered.

The callback function should return one of three values:

LC_CBRET_IGNORESECTION
Returning LC_CBRET_IGNORESECTION from a callback that begins a section causes the entire section to be ignored without generating an error.
LC_CBRET_OKAY
Returning LC_CBRET_OKAY from a callback indicates that all went well and further processing may continue.
LC_CBRET_ERROR
Returnning LC_CBRET_ERROR from a callback indicates that the command failed for some reason, the error will be passed back down the chain back to the lc_process(3) call that began processing the configuration data. If LC_CBRET_ERROR is returned from a callback that begins a section, the entire section is ignored. If LC_CBRET_ERROR is returned from a callback that ends a section, the error is ignored.

 

RETURN VALUE

On success 0 is returned, otherwise -1 is returned.

 

EXAMPLE

#include <libconfig.h>
#include <strings.h>
#include <stdlib.h>
#include <stdio.h>
int callback_ifmodule(const char *shortvar, const char *var,
                      const char *arguments, const char *value,
                      lc_flags_t flags, void *extra) {
        if (flags == LC_FLAGS_SECTIONEND) {
                return(LC_CBRET_OKAY);
        }
        if (arguments == NULL) {
                lc_seterrstr("You must specify an argument to \
                              IfModule.");
                return(LC_CBRET_ERROR);
        }
        printf("IfModule %s\n", arguments);
        if (strcasecmp(arguments, "MyModule") == 0) {
                return(LC_CBRET_IGNORESECTION);
        }
        return(LC_CBRET_OKAY);
}
int main(int argc, char **argv) {
        int lc_rc_ret, lc_p_ret;
        lc_rc_ret = lc_register_callback("*.IfModule", 0, LC_VAR_SECTION,
                                         callback_ifmodule, NULL);
        if (lc_rc_ret != 0) {
                fprintf(stderr, "Error registering callback.\n");
                return(EXIT_FAILURE);
        }
        lc_p_ret = lc_process(argc, argv, "example", LC_CONF_APACHE,
                              NULL);
        lc_cleanup();
        if (lc_p_ret != 0) {
                fprintf(stderr, "Error processing configuration: \
                        %s\n", lc_geterrstr());
                return(EXIT_FAILURE);
        }
        return(EXIT_SUCCESS);
}

 

ERRORS

ENOMEM
Memory could not be allocated to create the needed internal structures.

 

SEE ALSO

libconfig(3), lc_register_var(3), lc_geterrno(3), lc_geterrstr(3), lc_seterrstr(3), lc_handle_type(3), lc_process(3), lc_process_file(3), lc_cleanup(3)