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__ */ |
339 | |