libreport  2.5.0
A tool to inform users about various problems on the running system
problem_report.h
1 /*
2  Copyright (C) 2014 ABRT team
3  Copyright (C) 2014 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_PROBLEM_REPORT_H
20 #define LIBREPORT_PROBLEM_REPORT_H
21 
22 #include <glib.h>
23 #include <stdio.h>
24 #include "problem_data.h"
25 
26 #ifdef __cplusplus
27 extern "C" {
28 #endif
29 
30 #define PR_SEC_SUMMARY "summary"
31 #define PR_SEC_DESCRIPTION "description"
32 
33 /*
34  * The problem report structure represents a problem data formatted according
35  * to a format string.
36  *
37  * A problem report is composed of well-known sections:
38  * - summary
39  * - descritpion
40  * - attach
41  *
42  * and custom sections accessed by:
43  * problem_report_get_section();
44  */
45 struct problem_report;
46 typedef struct problem_report problem_report_t;
47 
48 /*
49  * Helpers for easily switching between FILE and struct strbuf
50  */
51 
52 /*
53  * Type of buffer used by Problem report
54  */
55 typedef FILE problem_report_buffer;
56 
57 /*
58  * Wrapper for the proble buffer's formated output function.
59  */
60 #define problem_report_buffer_printf(buf, fmt, ...)\
61  fprintf((buf), (fmt), ##__VA_ARGS__)
62 
63 
64 /*
65  * Get a section buffer
66  *
67  * Use this function if you need to amend something to a formatted section.
68  *
69  * @param self Problem report
70  * @param section_name Name of required section
71  * @return Always valid pointer to a section buffer
72  */
73 problem_report_buffer *problem_report_get_buffer(const problem_report_t *self,
74  const char *section_name);
75 
76 /*
77  * Get Summary string
78  *
79  * The returned pointer is valid as long as you perform no further output to
80  * the summary buffer.
81  *
82  * @param self Problem report
83  * @return Non-NULL pointer to summary data
84  */
85 const char *problem_report_get_summary(const problem_report_t *self);
86 
87 /*
88  * Get Description string
89  *
90  * The returned pointer is valid as long as you perform no further output to
91  * the description buffer.
92  *
93  * @param self Problem report
94  * @return Non-NULL pointer to description data
95  */
96 const char *problem_report_get_description(const problem_report_t *self);
97 
98 /*
99  * Get Section's string
100  *
101  * The returned pointer is valid as long as you perform no further output to
102  * the section's buffer.
103  *
104  * @param self Problem report
105  * @param section_name Name of the required section
106  * @return Non-NULL pointer to description data
107  */
108 const char *problem_report_get_section(const problem_report_t *self,
109  const char *section_name);
110 
111 /*
112  * Get GList of the problem data items that are to be attached
113  *
114  * @param self Problem report
115  * @return A pointer to GList (NULL means empty list)
116  */
117 GList *problem_report_get_attachments(const problem_report_t *self);
118 
119 /*
120  * Releases all resources allocated by a problem report
121  *
122  * @param self Problem report
123  */
124 void problem_report_free(problem_report_t *self);
125 
126 
127 /*
128  * An enum of Extra section flags
129  */
130 enum problem_formatter_section_flags {
131  PFFF_REQUIRED = 1 << 0,
132 };
133 
134 /*
135  * The problem formatter structure formats a problem data according to a format
136  * string and stores result a problem report.
137  *
138  * The problem formatter uses '%reason%' as %summary section format string, if
139  * %summary is not provided by a format string.
140  */
141 struct problem_formatter;
142 typedef struct problem_formatter problem_formatter_t;
143 
144 /*
145  * Constructs a new problem formatter.
146  *
147  * @return Non-NULL pointer to the new problem formatter
148  */
149 problem_formatter_t *problem_formatter_new(void);
150 
151 /*
152  * Releases all resources allocated by a problem formatter
153  *
154  * @param self Problem formatter
155  */
156 void problem_formatter_free(problem_formatter_t *self);
157 
158 /*
159  * Adds a new recognized section
160  *
161  * The problem formatter ignores a section in the format spec if the section is
162  * not one of the default nor added by this function.
163  *
164  * How the problem formatter handles these extra sections:
165  *
166  * A custom section is something like %description section. %description is the
167  * default section where all text (sub)sections are stored. If the formatter
168  * finds the custom section in format string, then starts storing text
169  * (sub)sections in the custom section.
170  *
171  * (%description) |:: comment
172  * (%description) |
173  * (%description) |Package:: package
174  * (%description) |
175  * (%additiona_info) |%additional_info::
176  * (%additiona_info) |%reporter%
177  * (%additiona_info) |User:: user_name,uid
178  * (%additiona_info) |
179  * (%additiona_info) |Directories:: root,cwd
180  *
181  *
182  * @param self Problem formatter
183  * @param name Name of the added section
184  * @param flags Info about the added section
185  * @return Zero on success. -EEXIST if the name is already known by the formatter
186  */
187 int problem_formatter_add_section(problem_formatter_t *self, const char *name, int flags);
188 
189 /*
190  * Loads a problem format from a string.
191  *
192  * @param self Problem formatter
193  * @param fmt Format
194  * @return Zero on success or number of warnings (e.g. missing section,
195  * unrecognized section).
196  */
197 int problem_formatter_load_string(problem_formatter_t* self, const char *fmt);
198 
199 
200 /*
201  * Loads a problem format from a file.
202  *
203  * @param self Problem formatter
204  * @param pat Path to the format file
205  * @return Zero on success or number of warnings (e.g. missing section,
206  * unrecognized section).
207  */
208 int problem_formatter_load_file(problem_formatter_t* self, const char *path);
209 
210 /*
211  * Creates a new problem report, formats the data according to the loaded
212  * format string and stores output in the report.
213  *
214  * @param self Problem formatter
215  * @param data Problem data to format
216  * @param report Pointer where the created problem report is to be stored
217  * @return Zero on success, otherwise non-zero value.
218  */
219 int problem_formatter_generate_report(const problem_formatter_t *self, problem_data_t *data, problem_report_t **report);
220 
221 #ifdef __cplusplus
222 }
223 #endif
224 
225 #endif // LIBREPORT_PROBLEM_REPORT_H