plugins: Be more descriptive in "about wireshark"->"folders"
[metze/wireshark/wip.git] / wsutil / filesystem.h
1 /* filesystem.h
2  * Filesystem utility definitions
3  *
4  * Wireshark - Network traffic analyzer
5  * By Gerald Combs <gerald@wireshark.org>
6  * Copyright 1998 Gerald Combs
7  *
8  * This program is free software; you can redistribute it and/or
9  * modify it under the terms of the GNU General Public License
10  * as published by the Free Software Foundation; either version 2
11  * of the License, or (at your option) any later version.
12  *
13  * This program is distributed in the hope that it will be useful,
14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
16  * GNU General Public License for more details.
17  *
18  * You should have received a copy of the GNU General Public License
19  * along with this program; if not, write to the Free Software
20  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
21  */
22
23 #ifndef FILESYSTEM_H
24 #define FILESYSTEM_H
25
26 #include "ws_symbol_export.h"
27 #include "ws_attributes.h"
28
29 #ifdef __cplusplus
30 extern "C" {
31 #endif /* __cplusplus */
32
33 /*
34  * Default profile name.
35  */
36 #define DEFAULT_PROFILE      "Default"
37
38
39 /*
40  * Get the pathname of the directory from which the executable came,
41  * and save it for future use.  Returns NULL on success, and a
42  * g_mallocated string containing an error on failure.
43  */
44 WS_DLL_PUBLIC char *init_progfile_dir(const char *arg0, int (*function_addr)(int, char **));
45
46 /*
47  * Get the directory in which the program resides.
48  */
49 WS_DLL_PUBLIC const char *get_progfile_dir(void);
50
51 /*
52  * Get the directory in which plugins are stored; this must not be called
53  * before init_progfile_dir() is called, as they might be stored in a
54  * subdirectory of the program file directory.
55  */
56 WS_DLL_PUBLIC const char *get_plugins_dir(void);
57
58 /*
59  * Append VERSION_MAJOR.VERSION_MINOR to the plugin dir.
60  */
61 WS_DLL_PUBLIC const char *get_plugins_dir_with_version(void);
62
63 /*
64  * Get the personal plugin dir.
65  */
66 WS_DLL_PUBLIC const char *get_plugins_pers_dir(void);
67
68 /*
69  * Append VERSION_MAJOR.VERSION_MINOR to the plugin personal dir.
70  */
71 WS_DLL_PUBLIC const char *get_plugins_pers_dir_with_version(void);
72
73 /*
74  * Get the directory in which extcap hooks are stored; this must not be called
75  * before init_progfile_dir() is called, as they might be stored in a
76  * subdirectory of the program file directory.
77  */
78 WS_DLL_PUBLIC const char *get_extcap_dir(void);
79
80 /*
81  * Get the flag indicating whether we're running from a build
82  * directory.
83  */
84 WS_DLL_PUBLIC gboolean running_in_build_directory(void);
85
86 /*
87  * Get the directory in which global configuration files are
88  * stored.
89  */
90 WS_DLL_PUBLIC const char *get_datafile_dir(void);
91
92 /*
93  * Construct the path name of a global configuration file, given the
94  * file name.
95  *
96  * The returned file name was g_malloc()'d so it must be g_free()d when the
97  * caller is done with it.
98  */
99 WS_DLL_PUBLIC char *get_datafile_path(const char *filename);
100
101 /*
102  * Get the directory in which files that, at least on UNIX, are
103  * system files (such as "/etc/ethers") are stored; on Windows,
104  * there's no "/etc" directory, so we get them from the Wireshark
105  * global configuration and data file directory.
106  */
107 WS_DLL_PUBLIC const char *get_systemfile_dir(void);
108
109 /*
110  * Set the configuration profile name to be used for storing
111  * personal configuration files.
112  */
113 WS_DLL_PUBLIC void set_profile_name(const gchar *profilename);
114
115 /*
116  * Get the current configuration profile name used for storing
117  * personal configuration files.
118  */
119 WS_DLL_PUBLIC const char *get_profile_name(void);
120
121 /*
122  * Check if current profile is default profile.
123  */
124 WS_DLL_PUBLIC gboolean is_default_profile(void);
125
126 /*
127  * Check if we have global profiles.
128  */
129 WS_DLL_PUBLIC gboolean has_global_profiles(void);
130
131 /*
132  * Get the directory used to store configuration profile directories.
133  * Caller must free the returned string
134  */
135 WS_DLL_PUBLIC char *get_profiles_dir(void);
136
137 /*
138  * Create the directory used to store configuration profile directories.
139  */
140 WS_DLL_PUBLIC int create_profiles_dir(char **pf_dir_path_return);
141
142 /*
143  * Get the directory used to store global configuration profile directories.
144  * Caller must free the returned string
145  */
146 WS_DLL_PUBLIC char *get_global_profiles_dir(void);
147
148
149 /*
150  * Store filenames used for personal config files so we know which
151  * files to copy when duplicate a configuration profile.
152  */
153 WS_DLL_PUBLIC void profile_store_persconffiles(gboolean store);
154
155 /*
156  * Check if given configuration profile exists.
157  */
158 WS_DLL_PUBLIC gboolean profile_exists(const gchar *profilename, gboolean global);
159
160 /*
161  * Create a directory for the given configuration profile.
162  * If we attempted to create it, and failed, return -1 and
163  * set "*pf_dir_path_return" to the pathname of the directory we failed
164  * to create (it's g_mallocated, so our caller should free it); otherwise,
165  * return 0.
166  */
167 WS_DLL_PUBLIC int create_persconffile_profile(const char *profilename,
168                                        char **pf_dir_path_return);
169
170 /*
171  * Delete the directory for the given configuration profile.
172  * If we attempted to delete it, and failed, return -1 and
173  * set "*pf_dir_path_return" to the pathname of the directory we failed
174  * to delete (it's g_mallocated, so our caller should free it); otherwise,
175  * return 0.
176  */
177 WS_DLL_PUBLIC int delete_persconffile_profile(const char *profilename,
178                                        char **pf_dir_path_return);
179
180 /*
181  * Rename the directory for the given confinguration profile.
182  */
183 WS_DLL_PUBLIC int rename_persconffile_profile(const char *fromname, const char *toname,
184                                        char **pf_from_dir_path_return,
185                                        char **pf_to_dir_path_return);
186
187 /*
188  * Copy files in one profile to the other.
189  */
190 WS_DLL_PUBLIC int copy_persconffile_profile(const char *toname, const char *fromname,
191                                      gboolean from_global,
192                                      char **pf_filename_return,
193                                      char **pf_to_dir_path_return,
194                                      char **pf_from_dir_path_return);
195
196 /*
197  * Create the directory that holds personal configuration files, if
198  * necessary.  If we attempted to create it, and failed, return -1 and
199  * set "*pf_dir_path_return" to the pathname of the directory we failed
200  * to create (it's g_mallocated, so our caller should free it); otherwise,
201  * return 0.
202  */
203 WS_DLL_PUBLIC int create_persconffile_dir(char **pf_dir_path_return);
204
205 /*
206  * Construct the path name of a personal configuration file, given the
207  * file name.  If using configuration profiles this directory will be
208  * used if "from_profile" is TRUE.
209  *
210  * The returned file name was g_malloc()'d so it must be g_free()d when the
211  * caller is done with it.
212  */
213 WS_DLL_PUBLIC char *get_persconffile_path(const char *filename, gboolean from_profile);
214
215 /*
216  * Set the path of the personal configuration file directory.
217  */
218 WS_DLL_PUBLIC void set_persconffile_dir(const char *p);
219
220 /*
221  * Get the (default) directory in which personal data is stored.
222  *
223  * On Win32, this is the "My Documents" folder in the personal profile.
224  * On UNIX this is simply the current directory.
225  */
226 WS_DLL_PUBLIC const char *get_persdatafile_dir(void);
227
228 /*
229  * Set the path of the directory in which personal data is stored.
230  */
231 WS_DLL_PUBLIC void set_persdatafile_dir(const char *p);
232
233 /*
234  * Return an error message for UNIX-style errno indications on open or
235  * create operations.
236  */
237 WS_DLL_PUBLIC const char *file_open_error_message(int err, gboolean for_writing);
238
239 /*
240  * Return an error message for UNIX-style errno indications on write
241  * operations.
242  */
243 WS_DLL_PUBLIC const char *file_write_error_message(int err);
244
245 /*
246  * Given a pathname, return the last component.
247  */
248 WS_DLL_PUBLIC const char *get_basename(const char *);
249
250  /*
251   * Given a pathname, return a pointer to the last pathname separator
252   * character in the pathname, or NULL if the pathname contains no
253   * separators.
254   */
255 WS_DLL_PUBLIC char *find_last_pathname_separator(const char *path);
256
257 /*
258  * Given a pathname, return a string containing everything but the
259  * last component.  NOTE: this overwrites the pathname handed into
260  * it....
261  */
262 WS_DLL_PUBLIC char *get_dirname(char *);
263
264 /*
265  * Given a pathname, return:
266  *
267  *      the errno, if an attempt to "stat()" the file fails;
268  *
269  *      EISDIR, if the attempt succeeded and the file turned out
270  *      to be a directory;
271  *
272  *      0, if the attempt succeeded and the file turned out not
273  *      to be a directory.
274  */
275 WS_DLL_PUBLIC int test_for_directory(const char *);
276
277 /*
278  * Given a pathname, return:
279  *
280  *      the errno, if an attempt to "stat()" the file fails;
281  *
282  *      ESPIPE, if the attempt succeeded and the file turned out
283  *      to be a FIFO;
284  *
285  *      0, if the attempt succeeded and the file turned out not
286  *      to be a FIFO.
287  */
288 WS_DLL_PUBLIC int test_for_fifo(const char *);
289
290 /*
291  * Check, if file is existing.
292  */
293 WS_DLL_PUBLIC gboolean file_exists(const char *fname);
294
295 /*
296  * Check if two filenames are identical (with absolute and relative paths).
297  */
298 WS_DLL_PUBLIC gboolean files_identical(const char *fname1, const char *fname2);
299
300 /*
301  * Copy a file in binary mode, for those operating systems that care about
302  * such things.  This should be OK for all files, even text files, as
303  * we'll copy the raw bytes, and we don't look at the bytes as we copy
304  * them.
305  *
306  * Returns TRUE on success, FALSE on failure. If a failure, it also
307  * displays a simple dialog window with the error message.
308  */
309 WS_DLL_PUBLIC gboolean copy_file_binary_mode(const char *from_filename,
310     const char *to_filename);
311
312
313 /*
314  * Given a filename return a filesystem URL. Relative paths are prefixed with
315  * the datafile directory path.
316  *
317  * @param filename A file name or path. Relative paths will be prefixed with
318  * the data file directory path.
319  * @return A filesystem URL for the file or NULL on failure. A non-NULL return
320  * value must be freed with g_free().
321  */
322 WS_DLL_PUBLIC gchar* data_file_url(const gchar *filename);
323
324 /*
325  * Free the internal structtures
326  */
327 WS_DLL_PUBLIC void free_progdirs(void);
328
329 #ifdef __cplusplus
330 }
331 #endif /* __cplusplus */
332
333 #endif /* FILESYSTEM_H */