libreport  2.1.3
A tool to inform users about various problems on the running system
run_event.h
00001 /*
00002     Copyright (C) 2009  ABRT team.
00003     Copyright (C) 2009  RedHat inc.
00004 
00005     This program is free software; you can redistribute it and/or modify
00006     it under the terms of the GNU General Public License as published by
00007     the Free Software Foundation; either version 2 of the License, or
00008     (at your option) any later version.
00009 
00010     This program is distributed in the hope that it will be useful,
00011     but WITHOUT ANY WARRANTY; without even the implied warranty of
00012     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00013     GNU General Public License for more details.
00014 
00015     You should have received a copy of the GNU General Public License along
00016     with this program; if not, write to the Free Software Foundation, Inc.,
00017     51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
00018 */
00019 #ifndef LIBREPORT_RUN_EVENT_H_
00020 #define LIBREPORT_RUN_EVENT_H_
00021 
00022 #include "problem_data.h"
00023 
00024 #ifdef __cplusplus
00025 extern "C" {
00026 #endif
00027 
00028 struct dump_dir;
00029 
00030 struct run_event_state {
00031     int children_count;
00032 
00033     /* Used only for post-create dup detection. TODO: document its API */
00034     int (*post_run_callback)(const char *dump_dir_name, void *param);
00035     void *post_run_param;
00036 
00037     /* Can take ownership of log_line, which is malloced. In this case, return NULL.
00038      * Otherwise should return log_line (it will be freed by caller)
00039      *
00040      * The default value prints log_line with trailing newline to stdout.
00041      */
00042     char* (*logging_callback)(char *log_line, void *param);
00043     void *logging_param;
00044 
00045     /*
00046      * Called if any error occures during communication with child's command.
00047      *
00048      * The default value prints error_line with trailing newline to stderr and
00049      * exits with an error code.
00050      *
00051      * @param error_line An error message
00052      * @param param a custom param
00053      */
00054     void (*error_callback)(const char *error_line, void *param);
00055     void *error_param;
00056 
00057     /*
00058      * An optional argument for the following callbacks
00059      */
00060     void *interaction_param;
00061 
00062     /*
00063      * Called when child command produced an alert.
00064      *
00065      * The default value is run_event_stdio_alert()
00066      *
00067      * @param msg An alert message produced byt child command
00068      * @param args An interaction param
00069      */
00070     void (*alert_callback)(const char *msg, void *interaction_param);
00071 
00072     /*
00073      * Called when child command ask for some input. A callee
00074      * should return a text whithout any new line character.
00075      *
00076      * The default value is run_event_stdio_ask()
00077      *
00078      * @param msg An ask message produced by child command
00079      * @param args An interaction param
00080      * @return Must allways return string without new lines, an empty string
00081      *         if response was not get.
00082      */
00083     char *(*ask_callback)(const char *msg, void *interaction_param);
00084 
00085     /*
00086      * Called when child command wants to know 'yes/no' decision.
00087      *
00088      * The default value is run_event_stdio_ask_yes_no()
00089      *
00090      * @param msg An ask message produced by child command
00091      * @param args An implementor args
00092      * @return Return 0 if an answer is NO, otherwise return nonzero value.
00093      */
00094     int (*ask_yes_no_callback)(const char *msg, void *interaction_param);
00095 
00096     /*
00097      * Called when child command wants to know 'yes/no/yesforever' decision.
00098      * The yes forever means that in next call the yes answer is returned
00099      * immediately without asking. The yes forever answer is stored in
00100      * configuration under a passed key.
00101      *
00102      * The default value is run_event_stdio_ask_yes_no_yesforever()
00103      *
00104      * @param key An option name used as a key in configuration
00105      * @param msg An ask message produced by child command
00106      * @param args An implementor args
00107      * @return Return 0 if an answer is NO, otherwise return nonzero value.
00108      */
00109     int (*ask_yes_no_yesforever_callback)(const char *key, const char *msg, void *interaction_param);
00110 
00111     /*
00112      * Called when child wants to know a password.
00113      *
00114      * The default value is run_event_stdio_ask_password()
00115      *
00116      * @param msg An ask message produced by child command
00117      * @param args An interaction param
00118      * @return Must allways return string without new lines, an empty string
00119      *         if password was not get.
00120      */
00121     char *(*ask_password_callback)(const char *msg, void *interaction_param);
00122 
00123     /* Internal data for async command execution */
00124     GList *rule_list;
00125     pid_t command_pid;
00126     int command_out_fd;
00127     int command_in_fd;
00128     int process_status;
00129     struct strbuf *command_output;
00130 };
00131 struct run_event_state *new_run_event_state(void);
00132 void free_run_event_state(struct run_event_state *state);
00133 
00134 /*
00135  * Configure callbacks to forward requests
00136  *
00137  * @param state A valid run event state pointer
00138  */
00139 void make_run_event_state_forwarding(struct run_event_state *state);
00140 
00141 
00142 /* Asynchronous command execution */
00143 
00144 /* Returns 0 if no commands found for this dump_dir_name+event, else >0 */
00145 int prepare_commands(struct run_event_state *state, const char *dump_dir_name, const char *event);
00146 /*
00147  * Returns -1 if no more commands needs to be executed,
00148  * else sets state->command_pid and state->command_out_fd and returns >=0.
00149  * execflags can be e.g. EXECFLG_SETPGID to put the event handling process
00150  * into a new process group, EXECFLG_SETSID to put it in a new session, etc.
00151  */
00152 int spawn_next_command(struct run_event_state *state,
00153                 const char *dump_dir_name,
00154                 const char *event,
00155                 unsigned execflags);
00156 /* Cleans up internal state created in prepare_commands */
00157 void free_commands(struct run_event_state *state);
00158 
00159 
00160 /* Synchronous command execution */
00161 
00162 /* The function believes that a state param value is fully initialized and
00163  * action is started.
00164  *
00165  * Returns exit code of action, or nonzero return value of post_run_callback
00166  * If action is successful, returns 0.
00167  *
00168  * If return value is lower than 0 and you set O_NONBLOCK to command's out fd
00169  * examine errno to detect EAGAIN case. Incomplete child lines are buffered
00170  * in the state param.
00171  */
00172 int consume_event_command_output(struct run_event_state *state, const char *dump_dir_name);
00173 
00174 /* Returns exit code of first failed action, or first nonzero return value
00175  * of post_run_callback. If all actions are successful, returns 0.
00176  */
00177 int run_event_on_dir_name(struct run_event_state *state, const char *dump_dir_name, const char *event);
00178 int run_event_on_problem_data(struct run_event_state *state, problem_data_t *data, const char *event);
00179 
00180 
00181 /* Querying for possible events */
00182 
00183 /* Scans event.conf for events starting with pfx which are applicable
00184  * to dd, or (if dd is NULL), to dump_dir.
00185  * Returns a malloced string with '\n'-terminated event names.
00186  */
00187 char *list_possible_events(struct dump_dir *dd, const char *dump_dir_name, const char *pfx);
00188 
00189 /*
00190  * Returns a list of possible events for given problem directory
00191  *
00192  * @param problem_dir_name the name of the problem directory
00193  * @param pfx the prefix of the events "report", "workflow"
00194  */
00195 GList *list_possible_events_glist(const char *problem_dir_name,
00196                                   const char *pfx);
00197 
00198 /* Command line run event callback implemenetation */
00199 
00200 /*
00201  * Prints the msg param on stdout
00202  *
00203  * @param msg a printed message
00204  * @param param ONLY NULL IS ALLOWED; other values are intended for internal use only
00205  */
00206 void run_event_stdio_alert(const char *msg, void *param);
00207 
00208 /*
00209  * Prints the msg param on stdout and reads a response from stdin
00210  *
00211  * @param msg a printed message
00212  * @param param ONLY NULL IS ALLOWED; other values are intended for internal use only
00213  * @return a malloced string with response, an empty string on error or no response
00214  */
00215 char *run_event_stdio_ask(const char *msg, void *param);
00216 
00217 /*
00218  * Prints the msg param on stdout and reads a response from stdin
00219  *
00220  * @param msg a printed message
00221  * @param param ONLY NULL IS ALLOWED; other values are intended for internal use only
00222  * @return 0 if user's answer is 'no', otherwise non 0 value
00223  */
00224 int run_event_stdio_ask_yes_no(const char *msg, void *param);
00225 
00226 /*
00227  * Prints the msg param on stdout and reads a response from stdin. To store the
00228  * yes forever answer uses libreport's user settings API. Therefore if you want
00229  * to get the yes forever stuff working you have to call load_user_setting()
00230  * function before this function call and call save_user_settings() function
00231  * after this function call.
00232  *
00233  * @param msg a printed message
00234  * @param key a key under which the yes forever answer is stored
00235  * @param param ONLY NULL IS ALLOWED; other values are intended for internal use only
00236  * @return 0 if user's answer is 'no', otherwise non 0 value
00237  */
00238 int run_event_stdio_ask_yes_no_yesforever(const char *msg, const char *key, void *param);
00239 
00240 /*
00241  * Prints the msg param on stdout and reads a response from stdin
00242  *
00243  * @param msg a printed message
00244  * @param param ONLY NULL IS ALLOWED; other values are intended for internal use only
00245  * @return a malloced string with response, an empty string on error or no response
00246  */
00247 char *run_event_stdio_ask_password(const char *msg, void *param);
00248 
00249 #ifdef __cplusplus
00250 }
00251 #endif
00252 
00253 #endif