libreport  2.1.11
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 wants to know a password.
113  *
114  * The default value is run_event_stdio_ask_password()
115  *
116  * @param msg An ask message produced by child command
117  * @param args An interaction param
118  * @return Must allways return string without new lines, an empty string
119  * if password was not get.
120  */
121  char *(*ask_password_callback)(const char *msg, void *interaction_param);
122 
123  /* Internal data for async command execution */
124  GList *rule_list;
125  pid_t command_pid;
126  int command_out_fd;
127  int command_in_fd;
128  int process_status;
129  struct strbuf *command_output;
130 };
131 struct run_event_state *new_run_event_state(void);
132 void free_run_event_state(struct run_event_state *state);
133 
134 /*
135  * Configure callbacks to forward requests
136  *
137  * @param state A valid run event state pointer
138  */
139 void make_run_event_state_forwarding(struct run_event_state *state);
140 
141 
142 /* Asynchronous command execution */
143 
144 /* Returns 0 if no commands found for this dump_dir_name+event, else >0 */
145 int prepare_commands(struct run_event_state *state, const char *dump_dir_name, const char *event);
146 /*
147  * Returns -1 if no more commands needs to be executed,
148  * else sets state->command_pid and state->command_out_fd and returns >=0.
149  * execflags can be e.g. EXECFLG_SETPGID to put the event handling process
150  * into a new process group, EXECFLG_SETSID to put it in a new session, etc.
151  */
152 int spawn_next_command(struct run_event_state *state,
153  const char *dump_dir_name,
154  const char *event,
155  unsigned execflags);
156 /* Cleans up internal state created in prepare_commands */
157 void free_commands(struct run_event_state *state);
158 
159 
160 /* Synchronous command execution */
161 
162 /* The function believes that a state param value is fully initialized and
163  * action is started.
164  *
165  * Returns exit code of action, or nonzero return value of post_run_callback
166  * If action is successful, returns 0.
167  *
168  * If return value is lower than 0 and you set O_NONBLOCK to command's out fd
169  * examine errno to detect EAGAIN case. Incomplete child lines are buffered
170  * in the state param.
171  */
172 int consume_event_command_output(struct run_event_state *state, const char *dump_dir_name);
173 
174 /* Returns exit code of first failed action, or first nonzero return value
175  * of post_run_callback. If all actions are successful, returns 0.
176  */
177 int run_event_on_dir_name(struct run_event_state *state, const char *dump_dir_name, const char *event);
178 int run_event_on_problem_data(struct run_event_state *state, problem_data_t *data, const char *event);
179 
180 
181 /* Querying for possible events */
182 
183 /* Scans event.conf for events starting with pfx which are applicable
184  * to dd, or (if dd is NULL), to dump_dir.
185  * Returns a malloced string with '\n'-terminated event names.
186  */
187 char *list_possible_events(struct dump_dir *dd, const char *dump_dir_name, const char *pfx);
188 
189 /*
190  * Returns a list of possible events for given problem directory
191  *
192  * @param problem_dir_name the name of the problem directory
193  * @param pfx the prefix of the events "report", "workflow"
194  */
195 GList *list_possible_events_glist(const char *problem_dir_name,
196  const char *pfx);
197 
198 /* Command line run event callback implemenetation */
199 
200 /*
201  * Prints the msg param on stdout
202  *
203  * @param msg a printed message
204  * @param param ONLY NULL IS ALLOWED; other values are intended for internal use only
205  */
206 void run_event_stdio_alert(const char *msg, void *param);
207 
208 /*
209  * Prints the msg param on stdout and reads a response from stdin
210  *
211  * @param msg a printed message
212  * @param param ONLY NULL IS ALLOWED; other values are intended for internal use only
213  * @return a malloced string with response, an empty string on error or no response
214  */
215 char *run_event_stdio_ask(const char *msg, void *param);
216 
217 /*
218  * Prints the msg param on stdout and reads a response from stdin
219  *
220  * @param msg a printed message
221  * @param param ONLY NULL IS ALLOWED; other values are intended for internal use only
222  * @return 0 if user's answer is 'no', otherwise non 0 value
223  */
224 int run_event_stdio_ask_yes_no(const char *msg, void *param);
225 
226 /*
227  * Prints the msg param on stdout and reads a response from stdin. To store the
228  * yes forever answer uses libreport's user settings API. Therefore if you want
229  * to get the yes forever stuff working you have to call load_user_setting()
230  * function before this function call and call save_user_settings() function
231  * after this function call.
232  *
233  * @param msg a printed message
234  * @param key a key under which the yes forever answer is stored
235  * @param param ONLY NULL IS ALLOWED; other values are intended for internal use only
236  * @return 0 if user's answer is 'no', otherwise non 0 value
237  */
238 int run_event_stdio_ask_yes_no_yesforever(const char *msg, const char *key, void *param);
239 
240 /*
241  * Prints the msg param on stdout and reads a response from stdin
242  *
243  * @param msg a printed message
244  * @param param ONLY NULL IS ALLOWED; other values are intended for internal use only
245  * @return a malloced string with response, an empty string on error or no response
246  */
247 char *run_event_stdio_ask_password(const char *msg, void *param);
248 
249 
250 /* A simple helper */
251 #define exit_status_as_string libreport_exit_status_as_string
252 char *exit_status_as_string(const char *progname, int status);
253 
254 
255 #ifdef __cplusplus
256 }
257 #endif
258 
259 #endif