libreport  2.3.0
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 
160 /* Returns 0 if no commands found for this dump_dir_name+event, else >0 */
161 int prepare_commands(struct run_event_state *state, const char *dump_dir_name, const char *event);
162 /*
163  * Returns -1 if no more commands needs to be executed,
164  * else sets state->command_pid and state->command_out_fd and returns >=0.
165  * execflags can be e.g. EXECFLG_SETPGID to put the event handling process
166  * into a new process group, EXECFLG_SETSID to put it in a new session, etc.
167  */
168 int spawn_next_command(struct run_event_state *state,
169  const char *dump_dir_name,
170  const char *event,
171  unsigned execflags);
172 /* Cleans up internal state created in prepare_commands */
173 void free_commands(struct run_event_state *state);
174 
175 
176 /* Synchronous command execution */
177 
178 /* The function believes that a state param value is fully initialized and
179  * action is started.
180  *
181  * Returns exit code of action, or nonzero return value of post_run_callback
182  * If action is successful, returns 0.
183  *
184  * If return value is lower than 0 and you set O_NONBLOCK to command's out fd
185  * examine errno to detect EAGAIN case. Incomplete child lines are buffered
186  * in the state param.
187  */
188 int consume_event_command_output(struct run_event_state *state, const char *dump_dir_name);
189 
190 /* Returns exit code of first failed action, or first nonzero return value
191  * of post_run_callback. If all actions are successful, returns 0.
192  */
193 int run_event_on_dir_name(struct run_event_state *state, const char *dump_dir_name, const char *event);
194 int run_event_on_problem_data(struct run_event_state *state, problem_data_t *data, const char *event);
195 
196 
197 /* Querying for possible events */
198 
199 /* Scans event.conf for events starting with pfx which are applicable
200  * to dd, or (if dd is NULL), to dump_dir.
201  * Returns a malloced string with '\n'-terminated event names.
202  */
203 char *list_possible_events(struct dump_dir *dd, const char *dump_dir_name, const char *pfx);
204 
205 /*
206  * Returns a list of possible events for given problem directory
207  *
208  * @param problem_dir_name the name of the problem directory
209  * @param pfx the prefix of the events "report", "workflow"
210  */
211 GList *list_possible_events_glist(const char *problem_dir_name,
212  const char *pfx);
213 
214 /* Command line run event callback implemenetation */
215 
216 /*
217  * Prints the msg param on stdout
218  *
219  * @param msg a printed message
220  * @param param ONLY NULL IS ALLOWED; other values are intended for internal use only
221  */
222 void run_event_stdio_alert(const char *msg, void *param);
223 
224 /*
225  * Prints the msg param on stdout and reads a response from stdin
226  *
227  * @param msg a printed message
228  * @param param ONLY NULL IS ALLOWED; other values are intended for internal use only
229  * @return a malloced string with response, an empty string on error or no response
230  */
231 char *run_event_stdio_ask(const char *msg, void *param);
232 
233 /*
234  * Prints the msg param on stdout and reads a response from stdin
235  *
236  * @param msg a printed message
237  * @param param ONLY NULL IS ALLOWED; other values are intended for internal use only
238  * @return 0 if user's answer is 'no', otherwise non 0 value
239  */
240 int run_event_stdio_ask_yes_no(const char *msg, void *param);
241 
242 /*
243  * Prints the msg param on stdout and reads a response from stdin. To store the
244  * yes forever answer uses libreport's user settings API. Therefore if you want
245  * to get the yes forever stuff working you have to call load_user_setting()
246  * function before this function call and call save_user_settings() function
247  * after this function call.
248  *
249  * @param msg a printed message
250  * @param key a key under which the yes forever answer is stored
251  * @param param ONLY NULL IS ALLOWED; other values are intended for internal use only
252  * @return 0 if user's answer is 'no', otherwise non 0 value
253  */
254 int run_event_stdio_ask_yes_no_yesforever(const char *msg, const char *key, void *param);
255 
256 /*
257  * Prints the msg param on stdout and reads a response from stdin. To store the
258  * forever or never answer uses libreport's user settings API.
259  * Therefore if you want to get the forever or never stuff working you
260  * have to call load_user_setting() function before this function call and call
261  * save_user_settings() function after this function call.
262  *
263  * @param msg a printed message
264  * @param key a key under which the forever (yes) or never (no) answer is stored
265  * @param param ONLY NULL IS ALLOWED; other values are intended for internal use only
266  * @return 0 if user's answer is 'no', otherwise non 0 value
267  */
268 int run_event_stdio_ask_yes_no_save_result(const char *msg, const char *key, void *param);
269 
270 /*
271  * Prints the msg param on stdout and reads a response from stdin
272  *
273  * @param msg a printed message
274  * @param param ONLY NULL IS ALLOWED; other values are intended for internal use only
275  * @return a malloced string with response, an empty string on error or no response
276  */
277 char *run_event_stdio_ask_password(const char *msg, void *param);
278 
279 
280 /* A simple helper */
281 #define exit_status_as_string libreport_exit_status_as_string
282 char *exit_status_as_string(const char *progname, int status);
283 
284 
285 #ifdef __cplusplus
286 }
287 #endif
288 
289 #endif