1 /* gbookmarkfile.h: parsing and building desktop bookmarks
2 *
3 * Copyright (C) 2005-2006 Emmanuele Bassi
4 *
5 * SPDX-License-Identifier: LGPL-2.1-or-later
6 *
7 * This library is free software; you can redistribute it and/or
8 * modify it under the terms of the GNU Lesser General Public
9 * License as published by the Free Software Foundation; either
10 * version 2.1 of the License, or (at your option) any later version.
11 *
12 * This library is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 * Lesser General Public License for more details.
16 *
17 * You should have received a copy of the GNU Lesser General Public License
18 * along with this library; if not, see <http://www.gnu.org/licenses/>.
19 */
20
21 #ifndef __G_BOOKMARK_FILE_H__
22 #define __G_BOOKMARK_FILE_H__
23
24 #if !defined (__GLIB_H_INSIDE__) && !defined (GLIB_COMPILATION)
25 #error "Only <glib.h> can be included directly."
26 #endif
27
28 #include <glib/gdatetime.h>
29 #include <glib/gerror.h>
30 #include <time.h>
31
32 G_BEGIN_DECLS
33
34 /**
35 * G_BOOKMARK_FILE_ERROR:
36 *
37 * Error domain for bookmark file parsing.
38 *
39 * Errors in this domain will be from the #GBookmarkFileError
40 * enumeration. See #GError for information on error domains.
41 */
42 #define G_BOOKMARK_FILE_ERROR (g_bookmark_file_error_quark ())
43
44
45 /**
46 * GBookmarkFileError:
47 * @G_BOOKMARK_FILE_ERROR_INVALID_URI: URI was ill-formed
48 * @G_BOOKMARK_FILE_ERROR_INVALID_VALUE: a requested field was not found
49 * @G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED: a requested application did
50 * not register a bookmark
51 * @G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND: a requested URI was not found
52 * @G_BOOKMARK_FILE_ERROR_READ: document was ill formed
53 * @G_BOOKMARK_FILE_ERROR_UNKNOWN_ENCODING: the text being parsed was
54 * in an unknown encoding
55 * @G_BOOKMARK_FILE_ERROR_WRITE: an error occurred while writing
56 * @G_BOOKMARK_FILE_ERROR_FILE_NOT_FOUND: requested file was not found
57 *
58 * Error codes returned by bookmark file parsing.
59 */
60 typedef enum
61 {
62 G_BOOKMARK_FILE_ERROR_INVALID_URI,
63 G_BOOKMARK_FILE_ERROR_INVALID_VALUE,
64 G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED,
65 G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND,
66 G_BOOKMARK_FILE_ERROR_READ,
67 G_BOOKMARK_FILE_ERROR_UNKNOWN_ENCODING,
68 G_BOOKMARK_FILE_ERROR_WRITE,
69 G_BOOKMARK_FILE_ERROR_FILE_NOT_FOUND
70 } GBookmarkFileError;
71
72 GLIB_AVAILABLE_IN_ALL
73 GQuark g_bookmark_file_error_quark (void);
74
75 /**
76 * GBookmarkFile:
77 *
78 * `GBookmarkFile` lets you parse, edit or create files containing bookmarks.
79 *
80 * Bookmarks refer to a URI, along with some meta-data about the resource
81 * pointed by the URI like its MIME type, the application that is registering
82 * the bookmark and the icon that should be used to represent the bookmark.
83 * The data is stored using the
84 * [Desktop Bookmark Specification](http://www.gnome.org/~ebassi/bookmark-spec).
85 *
86 * The syntax of the bookmark files is described in detail inside the
87 * Desktop Bookmark Specification, here is a quick summary: bookmark
88 * files use a sub-class of the XML Bookmark Exchange Language
89 * specification, consisting of valid UTF-8 encoded XML, under the
90 * `<xbel>` root element; each bookmark is stored inside a
91 * `<bookmark>` element, using its URI: no relative paths can
92 * be used inside a bookmark file. The bookmark may have a user defined
93 * title and description, to be used instead of the URI. Under the
94 * `<metadata>` element, with its owner attribute set to
95 * `http://freedesktop.org`, is stored the meta-data about a resource
96 * pointed by its URI. The meta-data consists of the resource's MIME
97 * type; the applications that have registered a bookmark; the groups
98 * to which a bookmark belongs to; a visibility flag, used to set the
99 * bookmark as "private" to the applications and groups that has it
100 * registered; the URI and MIME type of an icon, to be used when
101 * displaying the bookmark inside a GUI.
102 *
103 * Here is an example of a bookmark file:
104 * [bookmarks.xbel](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/glib/tests/bookmarks.xbel)
105 *
106 * A bookmark file might contain more than one bookmark; each bookmark
107 * is accessed through its URI.
108 *
109 * The important caveat of bookmark files is that when you add a new
110 * bookmark you must also add the application that is registering it, using
111 * [method@GLib.BookmarkFile.add_application] or [method@GLib.BookmarkFile.set_application_info].
112 * If a bookmark has no applications then it won't be dumped when creating
113 * the on disk representation, using [method@GLib.BookmarkFile.to_data] or
114 * [method@GLib.BookmarkFile.to_file].
115 *
116 * Since: 2.12
117 */
118 typedef struct _GBookmarkFile GBookmarkFile;
119
120 GLIB_AVAILABLE_IN_ALL
121 GBookmarkFile *g_bookmark_file_new (void);
122 GLIB_AVAILABLE_IN_ALL
123 void g_bookmark_file_free (GBookmarkFile *bookmark);
124
125 GLIB_AVAILABLE_IN_2_76
126 GBookmarkFile *g_bookmark_file_copy (GBookmarkFile *bookmark);
127
128 GLIB_AVAILABLE_IN_ALL
129 gboolean g_bookmark_file_load_from_file (GBookmarkFile *bookmark,
130 const gchar *filename,
131 GError **error);
132 GLIB_AVAILABLE_IN_ALL
133 gboolean g_bookmark_file_load_from_data (GBookmarkFile *bookmark,
134 const gchar *data,
135 gsize length,
136 GError **error);
137 GLIB_AVAILABLE_IN_ALL
138 gboolean g_bookmark_file_load_from_data_dirs (GBookmarkFile *bookmark,
139 const gchar *file,
140 gchar **full_path,
141 GError **error);
142 GLIB_AVAILABLE_IN_ALL
143 gchar * g_bookmark_file_to_data (GBookmarkFile *bookmark,
144 gsize *length,
145 GError **error) G_GNUC_MALLOC;
146 GLIB_AVAILABLE_IN_ALL
147 gboolean g_bookmark_file_to_file (GBookmarkFile *bookmark,
148 const gchar *filename,
149 GError **error);
150
151 GLIB_AVAILABLE_IN_ALL
152 void g_bookmark_file_set_title (GBookmarkFile *bookmark,
153 const gchar *uri,
154 const gchar *title);
155 GLIB_AVAILABLE_IN_ALL
156 gchar * g_bookmark_file_get_title (GBookmarkFile *bookmark,
157 const gchar *uri,
158 GError **error) G_GNUC_MALLOC;
159 GLIB_AVAILABLE_IN_ALL
160 void g_bookmark_file_set_description (GBookmarkFile *bookmark,
161 const gchar *uri,
162 const gchar *description);
163 GLIB_AVAILABLE_IN_ALL
164 gchar * g_bookmark_file_get_description (GBookmarkFile *bookmark,
165 const gchar *uri,
166 GError **error) G_GNUC_MALLOC;
167 GLIB_AVAILABLE_IN_ALL
168 void g_bookmark_file_set_mime_type (GBookmarkFile *bookmark,
169 const gchar *uri,
170 const gchar *mime_type);
171 GLIB_AVAILABLE_IN_ALL
172 gchar * g_bookmark_file_get_mime_type (GBookmarkFile *bookmark,
173 const gchar *uri,
174 GError **error) G_GNUC_MALLOC;
175 GLIB_AVAILABLE_IN_ALL
176 void g_bookmark_file_set_groups (GBookmarkFile *bookmark,
177 const gchar *uri,
178 const gchar **groups,
179 gsize length);
180 GLIB_AVAILABLE_IN_ALL
181 void g_bookmark_file_add_group (GBookmarkFile *bookmark,
182 const gchar *uri,
183 const gchar *group);
184 GLIB_AVAILABLE_IN_ALL
185 gboolean g_bookmark_file_has_group (GBookmarkFile *bookmark,
186 const gchar *uri,
187 const gchar *group,
188 GError **error);
189 GLIB_AVAILABLE_IN_ALL
190 gchar ** g_bookmark_file_get_groups (GBookmarkFile *bookmark,
191 const gchar *uri,
192 gsize *length,
193 GError **error);
194 GLIB_AVAILABLE_IN_ALL
195 void g_bookmark_file_add_application (GBookmarkFile *bookmark,
196 const gchar *uri,
197 const gchar *name,
198 const gchar *exec);
199 GLIB_AVAILABLE_IN_ALL
200 gboolean g_bookmark_file_has_application (GBookmarkFile *bookmark,
201 const gchar *uri,
202 const gchar *name,
203 GError **error);
204 GLIB_AVAILABLE_IN_ALL
205 gchar ** g_bookmark_file_get_applications (GBookmarkFile *bookmark,
206 const gchar *uri,
207 gsize *length,
208 GError **error);
209 GLIB_DEPRECATED_IN_2_66_FOR(g_bookmark_file_set_application_info)
210 gboolean g_bookmark_file_set_app_info (GBookmarkFile *bookmark,
211 const gchar *uri,
212 const gchar *name,
213 const gchar *exec,
214 gint count,
215 time_t stamp,
216 GError **error);
217 GLIB_AVAILABLE_IN_2_66
218 gboolean g_bookmark_file_set_application_info (GBookmarkFile *bookmark,
219 const char *uri,
220 const char *name,
221 const char *exec,
222 int count,
223 GDateTime *stamp,
224 GError **error);
225 GLIB_DEPRECATED_IN_2_66_FOR(g_bookmark_file_get_application_info)
226 gboolean g_bookmark_file_get_app_info (GBookmarkFile *bookmark,
227 const gchar *uri,
228 const gchar *name,
229 gchar **exec,
230 guint *count,
231 time_t *stamp,
232 GError **error);
233 GLIB_AVAILABLE_IN_2_66
234 gboolean g_bookmark_file_get_application_info (GBookmarkFile *bookmark,
235 const char *uri,
236 const char *name,
237 char **exec,
238 unsigned int *count,
239 GDateTime **stamp,
240 GError **error);
241 GLIB_AVAILABLE_IN_ALL
242 void g_bookmark_file_set_is_private (GBookmarkFile *bookmark,
243 const gchar *uri,
244 gboolean is_private);
245 GLIB_AVAILABLE_IN_ALL
246 gboolean g_bookmark_file_get_is_private (GBookmarkFile *bookmark,
247 const gchar *uri,
248 GError **error);
249 GLIB_AVAILABLE_IN_ALL
250 void g_bookmark_file_set_icon (GBookmarkFile *bookmark,
251 const gchar *uri,
252 const gchar *href,
253 const gchar *mime_type);
254 GLIB_AVAILABLE_IN_ALL
255 gboolean g_bookmark_file_get_icon (GBookmarkFile *bookmark,
256 const gchar *uri,
257 gchar **href,
258 gchar **mime_type,
259 GError **error);
260 GLIB_DEPRECATED_IN_2_66_FOR(g_bookmark_file_set_added_date_time)
261 void g_bookmark_file_set_added (GBookmarkFile *bookmark,
262 const gchar *uri,
263 time_t added);
264 GLIB_AVAILABLE_IN_2_66
265 void g_bookmark_file_set_added_date_time (GBookmarkFile *bookmark,
266 const char *uri,
267 GDateTime *added);
268 GLIB_DEPRECATED_IN_2_66_FOR(g_bookmark_file_get_added_date_time)
269 time_t g_bookmark_file_get_added (GBookmarkFile *bookmark,
270 const gchar *uri,
271 GError **error);
272 GLIB_AVAILABLE_IN_2_66
273 GDateTime *g_bookmark_file_get_added_date_time (GBookmarkFile *bookmark,
274 const char *uri,
275 GError **error);
276 GLIB_DEPRECATED_IN_2_66_FOR(g_bookmark_file_set_modified_date_time)
277 void g_bookmark_file_set_modified (GBookmarkFile *bookmark,
278 const gchar *uri,
279 time_t modified);
280 GLIB_AVAILABLE_IN_2_66
281 void g_bookmark_file_set_modified_date_time (GBookmarkFile *bookmark,
282 const char *uri,
283 GDateTime *modified);
284 GLIB_DEPRECATED_IN_2_66_FOR(g_bookmark_file_get_modified_date_time)
285 time_t g_bookmark_file_get_modified (GBookmarkFile *bookmark,
286 const gchar *uri,
287 GError **error);
288 GLIB_AVAILABLE_IN_2_66
289 GDateTime *g_bookmark_file_get_modified_date_time (GBookmarkFile *bookmark,
290 const char *uri,
291 GError **error);
292 GLIB_DEPRECATED_IN_2_66_FOR(g_bookmark_file_set_visited_date_time)
293 void g_bookmark_file_set_visited (GBookmarkFile *bookmark,
294 const gchar *uri,
295 time_t visited);
296 GLIB_AVAILABLE_IN_2_66
297 void g_bookmark_file_set_visited_date_time (GBookmarkFile *bookmark,
298 const char *uri,
299 GDateTime *visited);
300 GLIB_DEPRECATED_IN_2_66_FOR(g_bookmark_file_get_visited_date_time)
301 time_t g_bookmark_file_get_visited (GBookmarkFile *bookmark,
302 const gchar *uri,
303 GError **error);
304 GLIB_AVAILABLE_IN_2_66
305 GDateTime *g_bookmark_file_get_visited_date_time (GBookmarkFile *bookmark,
306 const char *uri,
307 GError **error);
308 GLIB_AVAILABLE_IN_ALL
309 gboolean g_bookmark_file_has_item (GBookmarkFile *bookmark,
310 const gchar *uri);
311 GLIB_AVAILABLE_IN_ALL
312 gint g_bookmark_file_get_size (GBookmarkFile *bookmark);
313 GLIB_AVAILABLE_IN_ALL
314 gchar ** g_bookmark_file_get_uris (GBookmarkFile *bookmark,
315 gsize *length);
316 GLIB_AVAILABLE_IN_ALL
317 gboolean g_bookmark_file_remove_group (GBookmarkFile *bookmark,
318 const gchar *uri,
319 const gchar *group,
320 GError **error);
321 GLIB_AVAILABLE_IN_ALL
322 gboolean g_bookmark_file_remove_application (GBookmarkFile *bookmark,
323 const gchar *uri,
324 const gchar *name,
325 GError **error);
326 GLIB_AVAILABLE_IN_ALL
327 gboolean g_bookmark_file_remove_item (GBookmarkFile *bookmark,
328 const gchar *uri,
329 GError **error);
330 GLIB_AVAILABLE_IN_ALL
331 gboolean g_bookmark_file_move_item (GBookmarkFile *bookmark,
332 const gchar *old_uri,
333 const gchar *new_uri,
334 GError **error);
335
336 G_END_DECLS
337
338 #endif /* __G_BOOKMARK_FILE_H__ */