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
32G_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 */
60typedef 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
72GLIB_AVAILABLE_IN_ALL
73GQuark 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 */
118typedef struct _GBookmarkFile GBookmarkFile;
119
120GLIB_AVAILABLE_IN_ALL
121GBookmarkFile *g_bookmark_file_new (void);
122GLIB_AVAILABLE_IN_ALL
123void g_bookmark_file_free (GBookmarkFile *bookmark);
124
125GLIB_AVAILABLE_IN_2_76
126GBookmarkFile *g_bookmark_file_copy (GBookmarkFile *bookmark);
127
128GLIB_AVAILABLE_IN_ALL
129gboolean g_bookmark_file_load_from_file (GBookmarkFile *bookmark,
130 const gchar *filename,
131 GError **error);
132GLIB_AVAILABLE_IN_ALL
133gboolean g_bookmark_file_load_from_data (GBookmarkFile *bookmark,
134 const gchar *data,
135 gsize length,
136 GError **error);
137GLIB_AVAILABLE_IN_ALL
138gboolean g_bookmark_file_load_from_data_dirs (GBookmarkFile *bookmark,
139 const gchar *file,
140 gchar **full_path,
141 GError **error);
142GLIB_AVAILABLE_IN_ALL
143gchar * g_bookmark_file_to_data (GBookmarkFile *bookmark,
144 gsize *length,
145 GError **error) G_GNUC_MALLOC;
146GLIB_AVAILABLE_IN_ALL
147gboolean g_bookmark_file_to_file (GBookmarkFile *bookmark,
148 const gchar *filename,
149 GError **error);
150
151GLIB_AVAILABLE_IN_ALL
152void g_bookmark_file_set_title (GBookmarkFile *bookmark,
153 const gchar *uri,
154 const gchar *title);
155GLIB_AVAILABLE_IN_ALL
156gchar * g_bookmark_file_get_title (GBookmarkFile *bookmark,
157 const gchar *uri,
158 GError **error) G_GNUC_MALLOC;
159GLIB_AVAILABLE_IN_ALL
160void g_bookmark_file_set_description (GBookmarkFile *bookmark,
161 const gchar *uri,
162 const gchar *description);
163GLIB_AVAILABLE_IN_ALL
164gchar * g_bookmark_file_get_description (GBookmarkFile *bookmark,
165 const gchar *uri,
166 GError **error) G_GNUC_MALLOC;
167GLIB_AVAILABLE_IN_ALL
168void g_bookmark_file_set_mime_type (GBookmarkFile *bookmark,
169 const gchar *uri,
170 const gchar *mime_type);
171GLIB_AVAILABLE_IN_ALL
172gchar * g_bookmark_file_get_mime_type (GBookmarkFile *bookmark,
173 const gchar *uri,
174 GError **error) G_GNUC_MALLOC;
175GLIB_AVAILABLE_IN_ALL
176void g_bookmark_file_set_groups (GBookmarkFile *bookmark,
177 const gchar *uri,
178 const gchar **groups,
179 gsize length);
180GLIB_AVAILABLE_IN_ALL
181void g_bookmark_file_add_group (GBookmarkFile *bookmark,
182 const gchar *uri,
183 const gchar *group);
184GLIB_AVAILABLE_IN_ALL
185gboolean g_bookmark_file_has_group (GBookmarkFile *bookmark,
186 const gchar *uri,
187 const gchar *group,
188 GError **error);
189GLIB_AVAILABLE_IN_ALL
190gchar ** g_bookmark_file_get_groups (GBookmarkFile *bookmark,
191 const gchar *uri,
192 gsize *length,
193 GError **error);
194GLIB_AVAILABLE_IN_ALL
195void g_bookmark_file_add_application (GBookmarkFile *bookmark,
196 const gchar *uri,
197 const gchar *name,
198 const gchar *exec);
199GLIB_AVAILABLE_IN_ALL
200gboolean g_bookmark_file_has_application (GBookmarkFile *bookmark,
201 const gchar *uri,
202 const gchar *name,
203 GError **error);
204GLIB_AVAILABLE_IN_ALL
205gchar ** g_bookmark_file_get_applications (GBookmarkFile *bookmark,
206 const gchar *uri,
207 gsize *length,
208 GError **error);
209GLIB_DEPRECATED_IN_2_66_FOR(g_bookmark_file_set_application_info)
210gboolean 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);
217GLIB_AVAILABLE_IN_2_66
218gboolean 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);
225GLIB_DEPRECATED_IN_2_66_FOR(g_bookmark_file_get_application_info)
226gboolean 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);
233GLIB_AVAILABLE_IN_2_66
234gboolean 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);
241GLIB_AVAILABLE_IN_ALL
242void g_bookmark_file_set_is_private (GBookmarkFile *bookmark,
243 const gchar *uri,
244 gboolean is_private);
245GLIB_AVAILABLE_IN_ALL
246gboolean g_bookmark_file_get_is_private (GBookmarkFile *bookmark,
247 const gchar *uri,
248 GError **error);
249GLIB_AVAILABLE_IN_ALL
250void g_bookmark_file_set_icon (GBookmarkFile *bookmark,
251 const gchar *uri,
252 const gchar *href,
253 const gchar *mime_type);
254GLIB_AVAILABLE_IN_ALL
255gboolean g_bookmark_file_get_icon (GBookmarkFile *bookmark,
256 const gchar *uri,
257 gchar **href,
258 gchar **mime_type,
259 GError **error);
260GLIB_DEPRECATED_IN_2_66_FOR(g_bookmark_file_set_added_date_time)
261void g_bookmark_file_set_added (GBookmarkFile *bookmark,
262 const gchar *uri,
263 time_t added);
264GLIB_AVAILABLE_IN_2_66
265void g_bookmark_file_set_added_date_time (GBookmarkFile *bookmark,
266 const char *uri,
267 GDateTime *added);
268GLIB_DEPRECATED_IN_2_66_FOR(g_bookmark_file_get_added_date_time)
269time_t g_bookmark_file_get_added (GBookmarkFile *bookmark,
270 const gchar *uri,
271 GError **error);
272GLIB_AVAILABLE_IN_2_66
273GDateTime *g_bookmark_file_get_added_date_time (GBookmarkFile *bookmark,
274 const char *uri,
275 GError **error);
276GLIB_DEPRECATED_IN_2_66_FOR(g_bookmark_file_set_modified_date_time)
277void g_bookmark_file_set_modified (GBookmarkFile *bookmark,
278 const gchar *uri,
279 time_t modified);
280GLIB_AVAILABLE_IN_2_66
281void g_bookmark_file_set_modified_date_time (GBookmarkFile *bookmark,
282 const char *uri,
283 GDateTime *modified);
284GLIB_DEPRECATED_IN_2_66_FOR(g_bookmark_file_get_modified_date_time)
285time_t g_bookmark_file_get_modified (GBookmarkFile *bookmark,
286 const gchar *uri,
287 GError **error);
288GLIB_AVAILABLE_IN_2_66
289GDateTime *g_bookmark_file_get_modified_date_time (GBookmarkFile *bookmark,
290 const char *uri,
291 GError **error);
292GLIB_DEPRECATED_IN_2_66_FOR(g_bookmark_file_set_visited_date_time)
293void g_bookmark_file_set_visited (GBookmarkFile *bookmark,
294 const gchar *uri,
295 time_t visited);
296GLIB_AVAILABLE_IN_2_66
297void g_bookmark_file_set_visited_date_time (GBookmarkFile *bookmark,
298 const char *uri,
299 GDateTime *visited);
300GLIB_DEPRECATED_IN_2_66_FOR(g_bookmark_file_get_visited_date_time)
301time_t g_bookmark_file_get_visited (GBookmarkFile *bookmark,
302 const gchar *uri,
303 GError **error);
304GLIB_AVAILABLE_IN_2_66
305GDateTime *g_bookmark_file_get_visited_date_time (GBookmarkFile *bookmark,
306 const char *uri,
307 GError **error);
308GLIB_AVAILABLE_IN_ALL
309gboolean g_bookmark_file_has_item (GBookmarkFile *bookmark,
310 const gchar *uri);
311GLIB_AVAILABLE_IN_ALL
312gint g_bookmark_file_get_size (GBookmarkFile *bookmark);
313GLIB_AVAILABLE_IN_ALL
314gchar ** g_bookmark_file_get_uris (GBookmarkFile *bookmark,
315 gsize *length);
316GLIB_AVAILABLE_IN_ALL
317gboolean g_bookmark_file_remove_group (GBookmarkFile *bookmark,
318 const gchar *uri,
319 const gchar *group,
320 GError **error);
321GLIB_AVAILABLE_IN_ALL
322gboolean g_bookmark_file_remove_application (GBookmarkFile *bookmark,
323 const gchar *uri,
324 const gchar *name,
325 GError **error);
326GLIB_AVAILABLE_IN_ALL
327gboolean g_bookmark_file_remove_item (GBookmarkFile *bookmark,
328 const gchar *uri,
329 GError **error);
330GLIB_AVAILABLE_IN_ALL
331gboolean g_bookmark_file_move_item (GBookmarkFile *bookmark,
332 const gchar *old_uri,
333 const gchar *new_uri,
334 GError **error);
335
336G_END_DECLS
337
338#endif /* __G_BOOKMARK_FILE_H__ */
339