(Trivial) Fix some spelling & etc in comments
[metze/wireshark/wip.git] / file.h
1 /* file.h
2  * Definitions for file structures and routines
3  *
4  * $Id$
5  *
6  * Wireshark - Network traffic analyzer
7  * By Gerald Combs <gerald@wireshark.org>
8  * Copyright 1998 Gerald Combs
9  *
10  * This program is free software; you can redistribute it and/or
11  * modify it under the terms of the GNU General Public License
12  * as published by the Free Software Foundation; either version 2
13  * of the License, or (at your option) any later version.
14  *
15  * This program is distributed in the hope that it will be useful,
16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
18  * GNU General Public License for more details.
19  *
20  * You should have received a copy of the GNU General Public License
21  * along with this program; if not, write to the Free Software
22  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
23  */
24
25 #ifndef __FILE_H__
26 #define __FILE_H__
27
28 #include "packet-range.h"
29 #include "wiretap/wtap.h"
30 #include <epan/dfilter/dfilter.h>
31 #include "print.h"
32 #include <errno.h>
33 #include <epan/epan.h>
34
35 #include "cfile.h"
36
37
38 /** Return values from functions that only can succeed or fail. */
39 typedef enum {
40         CF_OK,                      /**< operation succeeded */
41         CF_ERROR        /**< operation got an error (function may provide err with details) */
42 } cf_status_t;
43
44 /** Return values from functions that read capture files. */
45 typedef enum {
46         CF_READ_OK,             /**< operation succeeded */
47         CF_READ_ERROR,          /**< operation got an error (function may provide err with details) */
48         CF_READ_ABORTED         /**< operation aborted by user */
49 } cf_read_status_t;
50
51 /** Return values from functions that print sets of packets. */
52 typedef enum {
53         CF_PRINT_OK,                /**< print operation succeeded */
54         CF_PRINT_OPEN_ERROR,    /**< print operation failed while opening printer */
55         CF_PRINT_WRITE_ERROR    /**< print operation failed while writing to the printer */
56 } cf_print_status_t;
57
58 typedef enum {
59     cf_cb_file_closing,
60     cf_cb_file_closed,
61     cf_cb_file_read_start,
62     cf_cb_file_read_finished,
63     cf_cb_packet_selected,
64     cf_cb_packet_unselected,
65     cf_cb_field_unselected,
66     cf_cb_file_safe_started,
67     cf_cb_file_safe_finished,
68     cf_cb_file_safe_reload_finished,
69     cf_cb_file_safe_failed
70 } cf_cbs;
71
72 typedef void (*cf_callback_t) (gint event, gpointer data, gpointer user_data);
73
74 extern void
75 cf_callback_add(cf_callback_t func, gpointer user_data);
76
77 extern void
78 cf_callback_remove(cf_callback_t func);
79
80 /**
81  * Open a capture file.
82  *
83  * @param cf the capture file to be opened
84  * @param fname the filename to be opened
85  * @param is_tempfile is this a temporary file?
86  * @return one of cf_status_t
87  */
88 cf_status_t cf_open(capture_file *cf, const char *fname, gboolean is_tempfile, int *err);
89
90 /**
91  * Close a capture file.
92  *
93  * @param cf the capture file to be closed
94  */
95 void cf_close(capture_file *cf);
96
97 /**
98  * Reload a capture file.
99  *
100  * @param cf the capture file to be reloaded
101  */
102 void cf_reload(capture_file *cf);
103
104 /**
105  * Read all packets of a capture file into the internal structures.
106  * 
107  * @param cf the capture file to be read
108  * @return one of cf_read_status_t
109  */
110 cf_read_status_t cf_read(capture_file *cf);
111
112 /**
113  * Start reading from the end of a capture file.
114  * This is used in "Update list of packets in Real-Time".
115  * 
116  * @param cf the capture file to be read from
117  * @param fname the filename to be read from
118  * @param is_tempfile is this a temporary file?
119  * @param err the error code, if an error had occured
120  * @return one of cf_status_t
121  */
122 cf_status_t cf_start_tail(capture_file *cf, const char *fname, gboolean is_tempfile, int *err);
123
124 /**
125  * Read packets from the "end" of a capture file.
126  * 
127  * @param cf the capture file to be read from
128  * @param to_read the number of packets to read
129  * @param err the error code, if an error had occured
130  * @return one of cf_read_status_t
131  */
132 cf_read_status_t cf_continue_tail(capture_file *cf, volatile int to_read, int *err);
133
134 /**
135  * Finish reading from "end" of a capture file.
136  * 
137  * @param cf the capture file to be read from
138  * @param err the error code, if an error had occured
139  * @return one of cf_read_status_t
140  */
141 cf_read_status_t cf_finish_tail(capture_file *cf, int *err);
142
143 /**
144  * Determine whether this capture file (or a range of it) can be saved
145  * (except by copying the raw file data).
146  * 
147  * @param cf the capture file to check
148  * @return TRUE if it can be saved, FALSE if it can't
149  */
150 gboolean cf_can_save_as(capture_file *cf);
151
152 /**
153  * Save a capture file (or a range of it).
154  * 
155  * @param cf the capture file to save to
156  * @param fname the filename to save to
157  * @param range the range of packets to save
158  * @param save_format the format of the file to save (libpcap, ...)
159  * @param compressed whether to gzip compress the file
160  * @return one of cf_status_t
161  */
162 cf_status_t cf_save(capture_file * cf, const char *fname, packet_range_t *range, guint save_format, gboolean compressed);
163
164 /**
165  * Get a displayable name of the capture file.
166  * 
167  * @param cf the capture file
168  * @return the displayable name (don't have to be g_free'd)
169  */
170 const gchar *cf_get_display_name(capture_file *cf);
171
172 /**
173  * Get the number of packets in the capture file.
174  * 
175  * @param cf the capture file
176  * @return the number of packets in the capture file
177  */
178 int cf_get_packet_count(capture_file *cf);
179
180 /**
181  * Set the number of packets in the capture file.
182  * 
183  * @param cf the capture file
184  * @param the number of packets in the capture file
185  */
186 void cf_set_packet_count(capture_file *cf, int packet_count);
187
188 /**
189  * Is this capture file a temporary file?
190  * 
191  * @param cf the capture file
192  * @return TRUE if it's a temporary file, FALSE otherwise
193  */
194 gboolean cf_is_tempfile(capture_file *cf);
195
196 /**
197  * Set flag, that this file is a tempfile.
198  */
199 void cf_set_tempfile(capture_file *cf, gboolean is_tempfile);
200
201 /**
202  * Set flag, if the number of packet drops while capturing are known or not.
203  * 
204  * @param cf the capture file
205  * @param drops_known TRUE if the number of packet drops are known, FALSE otherwise
206  */
207 void cf_set_drops_known(capture_file *cf, gboolean drops_known);
208
209 /**
210  * Set the number of packet drops while capturing.
211  * 
212  * @param cf the capture file
213  * @param drops the number of packet drops occured while capturing
214  */
215 void cf_set_drops(capture_file *cf, guint32 drops);
216
217 /**
218  * Get flag state, if the number of packet drops while capturing are known or not.
219  * 
220  * @param cf the capture file
221  * @return TRUE if the number of packet drops are known, FALSE otherwise
222  */
223 gboolean cf_get_drops_known(capture_file *cf);
224
225 /**
226  * Get the number of packet drops while capturing.
227  * 
228  * @param cf the capture file
229  * @return the number of packet drops occured while capturing
230  */
231 guint32 cf_get_drops(capture_file *cf);
232
233 /**
234  * Set the read filter.
235  * @todo this shouldn't be required, remove it somehow
236  * 
237  * @param cf the capture file
238  * @param rfcode the readfilter
239  */
240 void cf_set_rfcode(capture_file *cf, dfilter_t *rfcode);
241
242 /**
243  * "Display Filter" packets in the capture file.
244  * 
245  * @param cf the capture file
246  * @param dfilter the display filter
247  * @param force TRUE if do in any case, FALSE only if dfilter changed
248  * @return one of cf_status_t
249  */
250 cf_status_t cf_filter_packets(capture_file *cf, gchar *dfilter, gboolean force);
251
252 /**
253  * At least one "Refence Time" flag has changed, rescan all packets.
254  * 
255  * @param cf the capture file
256  */
257 void cf_reftime_packets(capture_file *cf);
258
259 /**
260  * At least one "Refence Time" flag has changed, rescan all packets.
261  * 
262  * @param cf the capture file
263  */
264 void cf_colorize_packets(capture_file *cf);
265
266 /**
267  * "Something" has changed, rescan all packets.
268  * 
269  * @param cf the capture file
270  */
271 void cf_redissect_packets(capture_file *cf);
272
273 /**
274  * Rescan all packets and just run taps - don't reconstruct the display.
275  * 
276  * @param cf the capture file
277  * @param do_columns TRUE if columns are to be generated, FALSE otherwise
278  * @return one of cf_read_status_t
279  */
280 cf_read_status_t cf_retap_packets(capture_file *cf, gboolean do_columns);
281
282 /**
283  * The time format has changed, rescan all packets.
284  * 
285  * @param cf the capture file
286  */
287 void cf_change_time_formats(capture_file *cf);
288
289 /**
290  * Print the capture file.
291  * 
292  * @param cf the capture file
293  * @param print_args the arguments what and how to print
294  * @return one of cf_print_status_t
295  */
296 cf_print_status_t cf_print_packets(capture_file *cf, print_args_t *print_args);
297
298 /**
299  * Print (export) the capture file into PDML format.
300  * 
301  * @param cf the capture file
302  * @param print_args the arguments what and how to export
303  * @return one of cf_print_status_t
304  */
305 cf_print_status_t cf_write_pdml_packets(capture_file *cf, print_args_t *print_args);
306
307 /**
308  * Print (export) the capture file into PSML format.
309  * 
310  * @param cf the capture file
311  * @param print_args the arguments what and how to export
312  * @return one of cf_print_status_t
313  */
314 cf_print_status_t cf_write_psml_packets(capture_file *cf, print_args_t *print_args);
315
316 /**
317  * Print (export) the capture file into CSV format.
318  *
319  * @param cf the capture file
320  * @param print_args the arguments what and how to export
321  * @return one of cf_print_status_t
322  */
323 cf_print_status_t cf_write_csv_packets(capture_file *cf, print_args_t *print_args);
324
325 /**
326  * Print (export) the capture file into C Arrays format.
327  *
328  * @param cf the capture file
329  * @param print_args the arguments what and how to export
330  * @return one of cf_print_status_t
331  */
332 cf_print_status_t cf_write_carrays_packets(capture_file *cf, print_args_t *print_args);
333
334 /**
335  * Find Packet in protocol tree.
336  * 
337  * @param cf the capture file
338  * @param string the string to find
339  * @return TRUE if a packet was found, FALSE otherwise
340  */
341 gboolean cf_find_packet_protocol_tree(capture_file *cf, const char *string);
342
343 /**
344  * Find Packet in summary line.
345  * 
346  * @param cf the capture file
347  * @param string the string to find
348  * @return TRUE if a packet was found, FALSE otherwise
349  */
350 gboolean cf_find_packet_summary_line(capture_file *cf, const char *string);
351
352 /**
353  * Find Packet in packet data.
354  * 
355  * @param cf the capture file
356  * @param string the string to find
357  * @param string_size the size of the string to find
358  * @return TRUE if a packet was found, FALSE otherwise
359  */
360 gboolean cf_find_packet_data(capture_file *cf, const guint8 *string,
361                           size_t string_size);
362
363 /**
364  * Find Packet by display filter.
365  * 
366  * @param cf the capture file
367  * @param sfcode the display filter to find a packet for
368  * @return TRUE if a packet was found, FALSE otherwise
369  */
370 gboolean cf_find_packet_dfilter(capture_file *cf, dfilter_t *sfcode);
371
372 /**
373  * GoTo Packet in first row.
374  * 
375  * @param cf the capture file
376  * @return TRUE if the first row exists, FALSE otherwise
377  */
378 gboolean cf_goto_top_frame(capture_file *cf);
379
380 /**
381  * GoTo Packet in last row.
382  * 
383  * @param cf the capture file
384  * @return TRUE if last row exists, FALSE otherwise
385  */
386 gboolean cf_goto_bottom_frame(capture_file *cf);
387
388 /**
389  * GoTo Packet with the given row.
390  * 
391  * @param cf the capture file
392  * @param row the row to go to
393  * @return TRUE if this row exists, FALSE otherwise
394  */
395 gboolean cf_goto_frame(capture_file *cf, guint row);
396
397 /**
398  * Go to frame specified by currently selected protocol tree field.
399  * (Go To Corresponding Packet)
400  * @todo this is ugly and should be improved!
401  *
402  * @param cf the capture file
403  * @return TRUE if this packet exists, FALSE otherwise
404  */
405 gboolean cf_goto_framenum(capture_file *cf);
406
407 /**
408  * Select the packet in the given row.
409  *
410  * @param cf the capture file
411  * @param row the row to select
412  */
413 void cf_select_packet(capture_file *cf, int row);
414
415 /**
416  * Unselect all packets, if any.
417  *
418  * @param cf the capture file
419  * @param row the row to select
420  */
421 void cf_unselect_packet(capture_file *cf);
422
423 /**
424  * Unselect all protocol tree fields, if any.
425  *
426  * @param cf the capture file
427  * @param row the row to select
428  */
429 void cf_unselect_field(capture_file *cf);
430
431 /**
432  * Mark a particular frame in a particular capture.
433  *
434  * @param cf the capture file
435  * @param frame the frame to be marked
436  */
437 void cf_mark_frame(capture_file *cf, frame_data *frame);
438
439 /**
440  * Unmark a particular frame in a particular capture.
441  *
442  * @param cf the capture file
443  * @param frame the frame to be unmarked
444  */
445 void cf_unmark_frame(capture_file *cf, frame_data *frame);
446
447 /**
448  * Convert error number and info to a complete message.
449  *
450  * @param err the error number
451  * @param err_info a string with additional details about this error
452  * @return statically allocated error message
453  */
454 char *cf_read_error_message(int err, gchar *err_info);
455
456 /**
457  * Merge two (or more) capture files into one.
458  * @todo is this the right place for this function? It doesn't have to do a lot with capture_file.
459  *
460  * @param out_filename pointer to output filename; if output filename is
461  * NULL, a temporary file name is generated and *out_filename is set
462  * to point to the generated file name
463  * @param in_file_count the number of input files to merge
464  * @param in_filnames array of input filenames
465  * @param file_type the output filetype
466  * @param do_append FALSE to merge chronologically, TRUE simply append
467  * @return one of cf_status_t
468  */
469 cf_status_t
470 cf_merge_files(char **out_filename, int in_file_count,
471                char *const *in_filenames, int file_type, gboolean do_append);
472
473 #if defined(HAVE_HEIMDAL_KERBEROS) || defined(HAVE_MIT_KERBEROS)
474 void read_keytab_file(const char *);
475 #endif
476
477 #endif /* file.h */