libreport  2.9.4
A tool to inform users about various problems on the running system
run_event.h
1 /*
2  Copyright (C) 2009 ABRT team.
3  Copyright (C) 2009 RedHat inc.
4 
5  This program is free software; you can redistribute it and/or modify
6  it under the terms of the GNU General Public License as published by
7  the Free Software Foundation; either version 2 of the License, or
8  (at your option) any later version.
9 
10  This program is distributed in the hope that it will be useful,
11  but WITHOUT ANY WARRANTY; without even the implied warranty of
12  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13  GNU General Public License for more details.
14 
15  You should have received a copy of the GNU General Public License along
16  with this program; if not, write to the Free Software Foundation, Inc.,
17  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
18 */
19 #ifndef LIBREPORT_RUN_EVENT_H_
20 #define LIBREPORT_RUN_EVENT_H_
21 
22 #include "problem_data.h"
23 
24 #ifdef __cplusplus
25 extern "C" {
26 #endif
27 
28 struct dump_dir;
29 
31  int children_count;
32 
33  /* Used only for post-create dup detection. TODO: document its API */
34  int (*post_run_callback)(const char *dump_dir_name, void *param);
35  void *post_run_param;
36 
37  /* Can take ownership of log_line, which is malloced. In this case, return NULL.
38  * Otherwise should return log_line (it will be freed by caller)
39  *
40  * The default value prints log_line with trailing newline to stdout.
41  */
42  char* (*logging_callback)(char *log_line, void *param);
43  void *logging_param;
44 
45  /*
46  * Called if any error occures during communication with child's command.
47  *
48  * The default value prints error_line with trailing newline to stderr and
49  * exits with an error code.
50  *
51  * @param error_line An error message
52  * @param param a custom param
53  */
54  void (*error_callback)(const char *error_line, void *param);
55  void *error_param;
56 
57  /*
58  * An optional argument for the following callbacks
59  */
60  void *interaction_param;
61 
62  /*
63  * Called when child command produced an alert.
64  *
65  * The default value is run_event_stdio_alert()
66  *
67  * @param msg An alert message produced byt child command
68  * @param args An interaction param
69  */
70  void (*alert_callback)(const char *msg, void *interaction_param);
71 
72  /*
73  * Called when child command ask for some input. A callee
74  * should return a text whithout any new line character.
75  *
76  * The default value is run_event_stdio_ask()
77  *
78  * @param msg An ask message produced by child command
79  * @param args An interaction param
80  * @return Must allways return string without new lines, an empty string
81  * if response was not get.
82  */
83  char *(*ask_callback)(const char *msg, void *interaction_param);
84 
85  /*
86  * Called when child command wants to know 'yes/no' decision.
87  *
88  * The default value is run_event_stdio_ask_yes_no()
89  *
90  * @param msg An ask message produced by child command
91  * @param args An implementor args
92  * @return Return 0 if an answer is NO, otherwise return nonzero value.
93  */
94  int (*ask_yes_no_callback)(const char *msg, void *interaction_param);
95 
96  /*
97  * Called when child command wants to know 'yes/no/yesforever' decision.
98  * The yes forever means that in next call the yes answer is returned
99  * immediately without asking. The yes forever answer is stored in
100  * configuration under a passed key.
101  *
102  * The default value is run_event_stdio_ask_yes_no_yesforever()
103  *
104  * @param key An option name used as a key in configuration
105  * @param msg An ask message produced by child command
106  * @param args An implementor args
107  * @return Return 0 if an answer is NO, otherwise return nonzero value.
108  */
109  int (*ask_yes_no_yesforever_callback)(const char *key, const char *msg, void *interaction_param);
110 
111  /*
112  * Called when child command wants to know 'yes/no/forever/never' decision.
113  * The forever means that in next call the yes answer is returned
114  * immediately without asking. The never means that in next call the
115  * no answer is returned immediately without asking. The answer is stored
116  * in configuration under a passed key.
117  *
118  * The default value is run_event_stdio_ask_yes_no_save_result()
119  *
120  * @param key An option name used as a key in configuration
121  * @param msg An ask message produced by child command
122  * @param args An implementor args
123  * @return Return 0 if an answer is NO, otherwise return nonzero value.
124  */
125  int (*ask_yes_no_save_result_callback)(const char *key, const char *msg, void *interaction_param);
126 
127  /*
128  * Called when child wants to know a password.
129  *
130  * The default value is run_event_stdio_ask_password()
131  *
132  * @param msg An ask message produced by child command
133  * @param args An interaction param
134  * @return Must allways return string without new lines, an empty string
135  * if password was not get.
136  */
137  char *(*ask_password_callback)(const char *msg, void *interaction_param);
138 
139  /* Internal data for async command execution */
140  GList *rule_list;
141  pid_t command_pid;
142  int command_out_fd;
143  int command_in_fd;
144  int process_status;
145  struct strbuf *command_output;
146 };
147 struct run_event_state *new_run_event_state(void);
148 void free_run_event_state(struct run_event_state *state);
149 
150 /*
151  * Configure callbacks to forward requests
152  *
153  * @param state A valid run event state pointer
154  */
155 void make_run_event_state_forwarding(struct run_event_state *state);
156 
157 
158 /* Asynchronous command execution */
159 struct rule {
160  GList *conditions;
161  char *command; /* never NULL */
162 };
163 
164 /* Returns 0 if no commands found for this dump_dir_name+event, else >0 */
165 int prepare_commands(struct run_event_state *state, const char *dump_dir_name, const char *event);
166 /*
167  * Returns -1 if no more commands needs to be executed,
168  * else sets state->command_pid and state->command_out_fd and returns >=0.
169  * execflags can be e.g. EXECFLG_SETPGID to put the event handling process
170  * into a new process group, EXECFLG_SETSID to put it in a new session, etc.
171  */
172 int spawn_next_command(struct run_event_state *state,
173  const char *dump_dir_name,
174  const char *event,
175  unsigned execflags);
176 /* Cleans up internal state created in prepare_commands */
177 void free_commands(struct run_event_state *state);
178 
179 /* Load rule list from config file.
180  * Returns a list of all defined rules (struct rule)
181  * @param rule_list variable to append to or NONE to create new list
182  * @param conf_file_name path to configuration file
183  * @param recursion_depth internal recursion protection, should be 0
184  */
185 GList *load_rule_list(GList *rule_list, const char *conf_file_name, unsigned recursion_depth);
186 
187 /* Cleans up rule list created by load_rule_list */
188 void free_rule_list(GList *rule_list);
189 
190 /* Synchronous command execution */
191 
192 /* The function believes that a state param value is fully initialized and
193  * action is started.
194  *
195  * Returns exit code of action, or nonzero return value of post_run_callback
196  * If action is successful, returns 0.
197  *
198  * If return value is lower than 0 and you set O_NONBLOCK to command's out fd
199  * examine errno to detect EAGAIN case. Incomplete child lines are buffered
200  * in the state param.
201  */
202 int consume_event_command_output(struct run_event_state *state, const char *dump_dir_name);
203 
204 /* Returns exit code of first failed action, or first nonzero return value
205  * of post_run_callback. If all actions are successful, returns 0.
206  */
207 int run_event_on_dir_name(struct run_event_state *state, const char *dump_dir_name, const char *event);
208 int run_event_on_problem_data(struct run_event_state *state, problem_data_t *data, const char *event);
209 
210 
211 /* Querying for possible events */
212 
213 /* Scans event.conf for events starting with pfx which are applicable
214  * to dd, or (if dd is NULL), to dump_dir.
215  * Returns a malloced string with '\n'-terminated event names.
216  */
217 char *list_possible_events(struct dump_dir *dd, const char *dump_dir_name, const char *pfx);
218 
219 /* Like list_possible_events but accepts problem_data_t */
220 char *list_possible_events_problem_data(problem_data_t *pd, const char *dump_dir_name, const char *pfx);
221 
222 /*
223  * Returns a list of possible events for given problem directory
224  *
225  * @param problem_dir_name the name of the problem directory
226  * @param pfx the prefix of the events "report", "workflow"
227  */
228 GList *list_possible_events_glist(const char *problem_dir_name,
229  const char *pfx);
230 
231 /* Like list_possible_events_glist but accepts problem_data_t */
232 GList *list_possible_events_problem_data_glist(problem_data_t *pd,
233  const char *problem_dir_name,
234  const char *pfx);
235 
236 /* Command line run event callback implemenetation */
237 
238 /*
239  * Prints the msg param on stdout
240  *
241  * @param msg a printed message
242  * @param param ONLY NULL IS ALLOWED; other values are intended for internal use only
243  */
244 void run_event_stdio_alert(const char *msg, void *param);
245 
246 /*
247  * Prints the msg param on stdout and reads a response from stdin
248  *
249  * @param msg a printed message
250  * @param param ONLY NULL IS ALLOWED; other values are intended for internal use only
251  * @return a malloced string with response, an empty string on error or no response
252  */
253 char *run_event_stdio_ask(const char *msg, void *param);
254 
255 /*
256  * Prints the msg param on stdout and reads a response from stdin
257  *
258  * @param msg a printed message
259  * @param param ONLY NULL IS ALLOWED; other values are intended for internal use only
260  * @return 0 if user's answer is 'no', otherwise non 0 value
261  */
262 int run_event_stdio_ask_yes_no(const char *msg, void *param);
263 
264 /*
265  * Prints the msg param on stdout and reads a response from stdin. To store the
266  * yes forever answer uses libreport's user settings API. Therefore if you want
267  * to get the yes forever stuff working you have to call load_user_setting()
268  * function before this function call and call save_user_settings() function
269  * after this function call.
270  *
271  * @param msg a printed message
272  * @param key a key under which the yes forever answer is stored
273  * @param param ONLY NULL IS ALLOWED; other values are intended for internal use only
274  * @return 0 if user's answer is 'no', otherwise non 0 value
275  */
276 int run_event_stdio_ask_yes_no_yesforever(const char *msg, const char *key, void *param);
277 
278 /*
279  * Prints the msg param on stdout and reads a response from stdin. To store the
280  * forever or never answer uses libreport's user settings API.
281  * Therefore if you want to get the forever or never stuff working you
282  * have to call load_user_setting() function before this function call and call
283  * save_user_settings() function after this function call.
284  *
285  * @param msg a printed message
286  * @param key a key under which the forever (yes) or never (no) answer is stored
287  * @param param ONLY NULL IS ALLOWED; other values are intended for internal use only
288  * @return 0 if user's answer is 'no', otherwise non 0 value
289  */
290 int run_event_stdio_ask_yes_no_save_result(const char *msg, const char *key, void *param);
291 
292 /*
293  * Prints the msg param on stdout and reads a response from stdin
294  *
295  * @param msg a printed message
296  * @param param ONLY NULL IS ALLOWED; other values are intended for internal use only
297  * @return a malloced string with response, an empty string on error or no response
298  */
299 char *run_event_stdio_ask_password(const char *msg, void *param);
300 
301 
302 /* A simple helper */
303 #define exit_status_as_string libreport_exit_status_as_string
304 char *exit_status_as_string(const char *progname, int status);
305 
306 
307 #ifdef __cplusplus
308 }
309 #endif
310 
311 #endif