NetSurf
file.h
Go to the documentation of this file.
1/*
2 * Copyright 2014 Vincent Sanders <vince@netsurf-browser.org>
3 *
4 * This file is part of NetSurf, http://www.netsurf-browser.org/
5 *
6 * NetSurf is free software; you can redistribute it and/or modify
7 * it under the terms of the GNU General Public License as published by
8 * the Free Software Foundation; version 2 of the License.
9 *
10 * NetSurf 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
16 * along with this program. If not, see <http://www.gnu.org/licenses/>.
17 */
18
19/**
20 * \file utils/file.h
21 * \brief Default operations table for files.
22 *
23 * These are file operations that depend upon the filesystem the
24 * browser is operating on. These allow the core browser functionality
25 * to be filesystem agnostic.
26 *
27 * The provided defaults operate on POSIX path names with / as a
28 * directory separator in a single hieracy from a root directory.
29 *
30 * Other path conventions require the default operations to be
31 * overridden. For example windows frontend runs on a filesystem with
32 * drive letter and a \\ as a separator.
33 */
34
35#ifndef NETSURF_UTILS_FILE_H
36#define NETSURF_UTILS_FILE_H
37
38#include <stdarg.h>
39
40struct nsurl;
41
42/**
43 * /brief function table for file and filename operations.
44 *
45 * function table implementing an interface to file and filename
46 * functionality appropriate for the OS filesystem. All paths are in
47 * terms of the OS filesystem convention and must not require additional
48 * system specific changes.
49 */
50struct gui_file_table {
51 /* Mandantory entries */
52
53 /**
54 * Generate a path from one or more component elemnts.
55 *
56 * If a string is allocated it must be freed by the caller.
57 *
58 * @param[in,out] str pointer to string pointer if this is NULL enough
59 * storage will be allocated for the complete path.
60 * @param[in,out] size The size of the space available if \a str not
61 * NULL on input and if not NULL set to the total
62 * output length on output.
63 * @param[in] nemb The number of elements.
64 * @param[in] ap The elements of the path as string pointers.
65 * @return NSERROR_OK and the complete path is written to str
66 * or error code on faliure.
67 */
68 nserror (*mkpath)(char **str, size_t *size, size_t nemb, va_list ap);
69
70 /**
71 * Get the basename of a file.
72 *
73 * This gets the last element of a path and returns it.
74 *
75 * @param[in] path The path to extract the name from.
76 * @param[in,out] str Pointer to string pointer if this is NULL enough
77 * storage will be allocated for the path element.
78 * @param[in,out] size The size of the space available if \a
79 * str not NULL on input and set to the total
80 * output length on output.
81 * @return NSERROR_OK and the complete path is written to \a str
82 * or error code on faliure.
83 */
84 nserror (*basename)(const char *path, char **str, size_t *size);
85
86 /**
87 * Create a path from a nsurl.
88 *
89 * @param[in] url The url to encode.
90 * @param[out] path A string containing the result path which
91 * must be freed by the caller.
92 * @return NSERROR_OK and the path is written to \a path
93 * or error code on faliure.
94 */
95 nserror (*nsurl_to_path)(struct nsurl *url, char **path);
96
97 /**
98 * Create a nsurl from a path.
99 *
100 * Perform the necessary operations on a path to generate a nsurl.
101 *
102 * @param[in] path The path to convert.
103 * @param[out] url pointer to recive the nsurl, The returned
104 * url should be unreferenced by the caller.
105 * @return NSERROR_OK and the url is placed in \a url or error
106 * code on faliure.
107 */
108 nserror (*path_to_nsurl)(const char *path, struct nsurl **url);
109
110 /**
111 * Ensure that all directory elements needed to store a filename exist.
112 *
113 * @param[in] fname The filename to ensure the path to exists.
114 * @return NSERROR_OK on success or error code on failure.
115 */
116 nserror (*mkdir_all)(const char *fname);
117};
118
119/** Default (posix) file operation table. */
120extern struct gui_file_table *default_file_table;
121
122/**
123 * Generate a path from one or more component elemnts.
124 *
125 * If a string is allocated it must be freed by the caller.
126 *
127 * @warning If this is called before the gui operation tables are
128 * initialised the behaviour defaults to posix paths. Ensure this is
129 * the required behaviour.
130 *
131 * @param[in,out] str pointer to string pointer if this is NULL enough
132 * storage will be allocated for the complete path.
133 * @param[in,out] size The size of the space available if \a str not
134 * NULL on input and if not NULL set to the total
135 * output length on output.
136 * @param[in] nelm The number of elements.
137 * @param[in] ... The elements of the path as string pointers.
138 * @return NSERROR_OK and the complete path is written to str
139 * or error code on faliure.
140 */
141nserror netsurf_mkpath(char **str, size_t *size, size_t nelm, ...);
142
143/**
144 * Create a path from a nsurl.
145 *
146 * @param[in] url The url to encode.
147 * @param[out] path_out A string containing the result path which must be
148 * freed by the caller.
149 * @return NSERROR_OK and the path is written to \a path_out or error code on
150 * faliure.
151 */
152nserror netsurf_nsurl_to_path(struct nsurl *url, char **path_out);
153
154/**
155 * Create a nsurl from a path.
156 *
157 * Perform the necessary operations on a path to generate a nsurl.
158 *
159 * @param[in] path The path to convert.
160 * @param[out] url pointer to recive the nsurl, The returned
161 * url should be unreferenced by the caller.
162 * @return NSERROR_OK and the url is placed in \a url or error
163 * code on faliure.
164 */
165nserror netsurf_path_to_nsurl(const char *path, struct nsurl **url);
166
167/**
168 * Ensure that all directory elements needed to store a filename exist.
169 *
170 * @param fname The filename to ensure the path to exists.
171 * @return NSERROR_OK on success or error code on failure.
172 */
173nserror netsurf_mkdir_all(const char *fname);
174
175/**
176 * Recursively remove a directory
177 *
178 * If this returns a failure code, there's an unpredictable amount left
179 * unremoved.
180 *
181 * @param path The path to recursively remove
182 * @return NSERROR_OK on success, or an error code on failure.
183 */
184nserror netsurf_recursive_rm(const char *path);
185
186#endif
nserror
nserror
Enumeration of error codes.
Definition: errors.h:29
nsurl
struct nsurl nsurl
NetSurf URL object.
Definition: nsurl.h:31
gui_file_table
/brief function table for file and filename operations.
Definition: file.h:50
gui_file_table::basename
nserror(* basename)(const char *path, char **str, size_t *size)
Get the basename of a file.
Definition: file.h:84
gui_file_table::mkdir_all
nserror(* mkdir_all)(const char *fname)
Ensure that all directory elements needed to store a filename exist.
Definition: file.h:116
gui_file_table::nsurl_to_path
nserror(* nsurl_to_path)(struct nsurl *url, char **path)
Create a path from a nsurl.
Definition: file.h:95
gui_file_table::mkpath
nserror(* mkpath)(char **str, size_t *size, size_t nemb, va_list ap)
Generate a path from one or more component elemnts.
Definition: file.h:68
gui_file_table::path_to_nsurl
nserror(* path_to_nsurl)(const char *path, struct nsurl **url)
Create a nsurl from a path.
Definition: file.h:108
netsurf_mkdir_all
nserror netsurf_mkdir_all(const char *fname)
Ensure that all directory elements needed to store a filename exist.
Definition: file.c:313
netsurf_nsurl_to_path
nserror netsurf_nsurl_to_path(struct nsurl *url, char **path_out)
Create a path from a nsurl.
Definition: file.c:301
default_file_table
struct gui_file_table * default_file_table
Default (posix) file operation table.
Definition: file.c:285
netsurf_path_to_nsurl
nserror netsurf_path_to_nsurl(const char *path, struct nsurl **url)
Create a nsurl from a path.
Definition: file.c:307
netsurf_mkpath
nserror netsurf_mkpath(char **str, size_t *size, size_t nelm,...)
Generate a path from one or more component elemnts.
Definition: file.c:288
netsurf_recursive_rm
nserror netsurf_recursive_rm(const char *path)
Recursively remove a directory.
Definition: file.c:320
path
static nserror path(const struct redraw_context *ctx, const plot_style_t *pstyle, const float *p, unsigned int n, const float transform[6])
Plots a path.
Definition: plot.c:821
Generated on Wed May 8 2024 18:38:49 for NetSurf by doxygen 1.9.4