1 /* gbookmarkfile.c: parsing and building desktop bookmarks
3 * Copyright (C) 2005-2006 Emmanuele Bassi
5 * This library is free software; you can redistribute it and/or
6 * modify it under the terms of the GNU Library General Public
7 * License as published by the Free Software Foundation; either
8 * version 2 of the License, or (at your option) any later version.
10 * This library 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 GNU
13 * Library General Public License for more details.
15 * You should have received a copy of the GNU Library General Public
16 * License along with this library; if not, write to the
17 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
22 #include "gbookmarkfile.h"
32 #include <sys/types.h>
41 #include "gfileutils.h"
49 #include "gmessages.h"
54 #include "gstrfuncs.h"
60 * SECTION:bookmarkfile
61 * @title: Bookmark file parser
62 * @short_description: parses files containing bookmarks
64 * GBookmarkFile lets you parse, edit or create files containing bookmarks
65 * to URI, along with some meta-data about the resource pointed by the URI
66 * like its MIME type, the application that is registering the bookmark and
67 * the icon that should be used to represent the bookmark. The data is stored
69 * <ulink url="http://www.gnome.org/~ebassi/bookmark-spec">Desktop Bookmark
70 * Specification</ulink>.
72 * The syntax of the bookmark files is described in detail inside the Desktop
73 * Bookmark Specification, here is a quick summary: bookmark files use a
74 * sub-class of the <ulink url="">XML Bookmark Exchange Language</ulink>
75 * specification, consisting of valid UTF-8 encoded XML, under the
76 * <literal>xbel</literal> root element; each bookmark is stored inside a
77 * <literal>bookmark</literal> element, using its URI: no relative paths can
78 * be used inside a bookmark file. The bookmark may have a user defined title
79 * and description, to be used instead of the URI. Under the
80 * <literal>metadata</literal> element, with its <literal>owner</literal>
81 * attribute set to <literal>http://freedesktop.org</literal>, is stored the
82 * meta-data about a resource pointed by its URI. The meta-data consists of
83 * the resource's MIME type; the applications that have registered a bookmark;
84 * the groups to which a bookmark belongs to; a visibility flag, used to set
85 * the bookmark as "private" to the applications and groups that has it
86 * registered; the URI and MIME type of an icon, to be used when displaying
87 * the bookmark inside a GUI.
88 * |[<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../glib/tests/bookmarks.xbel"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include>]|
90 * A bookmark file might contain more than one bookmark; each bookmark
91 * is accessed through its URI.
93 * The important caveat of bookmark files is that when you add a new
94 * bookmark you must also add the application that is registering it, using
95 * g_bookmark_file_add_application() or g_bookmark_file_set_app_info().
96 * If a bookmark has no applications then it won't be dumped when creating
97 * the on disk representation, using g_bookmark_file_to_data() or
98 * g_bookmark_file_to_file().
100 * The #GBookmarkFile parser was added in GLib 2.12.
103 /* XBEL 1.0 standard entities */
104 #define XBEL_VERSION "1.0"
105 #define XBEL_DTD_NICK "xbel"
106 #define XBEL_DTD_SYSTEM "+//IDN python.org//DTD XML Bookmark " \
107 "Exchange Language 1.0//EN//XML"
109 #define XBEL_DTD_URI "http://www.python.org/topics/xml/dtds/xbel-1.0.dtd"
111 #define XBEL_ROOT_ELEMENT "xbel"
112 #define XBEL_FOLDER_ELEMENT "folder" /* unused */
113 #define XBEL_BOOKMARK_ELEMENT "bookmark"
114 #define XBEL_ALIAS_ELEMENT "alias" /* unused */
115 #define XBEL_SEPARATOR_ELEMENT "separator" /* unused */
116 #define XBEL_TITLE_ELEMENT "title"
117 #define XBEL_DESC_ELEMENT "desc"
118 #define XBEL_INFO_ELEMENT "info"
119 #define XBEL_METADATA_ELEMENT "metadata"
121 #define XBEL_VERSION_ATTRIBUTE "version"
122 #define XBEL_FOLDED_ATTRIBUTE "folded" /* unused */
123 #define XBEL_OWNER_ATTRIBUTE "owner"
124 #define XBEL_ADDED_ATTRIBUTE "added"
125 #define XBEL_VISITED_ATTRIBUTE "visited"
126 #define XBEL_MODIFIED_ATTRIBUTE "modified"
127 #define XBEL_ID_ATTRIBUTE "id"
128 #define XBEL_HREF_ATTRIBUTE "href"
129 #define XBEL_REF_ATTRIBUTE "ref" /* unused */
131 #define XBEL_YES_VALUE "yes"
132 #define XBEL_NO_VALUE "no"
134 /* Desktop bookmark spec entities */
135 #define BOOKMARK_METADATA_OWNER "http://freedesktop.org"
137 #define BOOKMARK_NAMESPACE_NAME "bookmark"
138 #define BOOKMARK_NAMESPACE_URI "http://www.freedesktop.org/standards/desktop-bookmarks"
140 #define BOOKMARK_GROUPS_ELEMENT "groups"
141 #define BOOKMARK_GROUP_ELEMENT "group"
142 #define BOOKMARK_APPLICATIONS_ELEMENT "applications"
143 #define BOOKMARK_APPLICATION_ELEMENT "application"
144 #define BOOKMARK_ICON_ELEMENT "icon"
145 #define BOOKMARK_PRIVATE_ELEMENT "private"
147 #define BOOKMARK_NAME_ATTRIBUTE "name"
148 #define BOOKMARK_EXEC_ATTRIBUTE "exec"
149 #define BOOKMARK_COUNT_ATTRIBUTE "count"
150 #define BOOKMARK_TIMESTAMP_ATTRIBUTE "timestamp" /* deprecated by "modified" */
151 #define BOOKMARK_MODIFIED_ATTRIBUTE "modified"
152 #define BOOKMARK_HREF_ATTRIBUTE "href"
153 #define BOOKMARK_TYPE_ATTRIBUTE "type"
155 /* Shared MIME Info entities */
156 #define MIME_NAMESPACE_NAME "mime"
157 #define MIME_NAMESPACE_URI "http://www.freedesktop.org/standards/shared-mime-info"
158 #define MIME_TYPE_ELEMENT "mime-type"
159 #define MIME_TYPE_ATTRIBUTE "type"
162 typedef struct _BookmarkAppInfo BookmarkAppInfo
;
163 typedef struct _BookmarkMetadata BookmarkMetadata
;
164 typedef struct _BookmarkItem BookmarkItem
;
165 typedef struct _ParseData ParseData
;
167 struct _BookmarkAppInfo
177 struct _BookmarkMetadata
184 GHashTable
*apps_by_name
;
189 guint is_private
: 1;
203 BookmarkMetadata
*metadata
;
206 struct _GBookmarkFile
211 /* we store our items in a list and keep a copy inside
212 * an hash table for faster lookup performances
215 GHashTable
*items_by_uri
;
218 /* parser state machine */
239 static void g_bookmark_file_init (GBookmarkFile
*bookmark
);
240 static void g_bookmark_file_clear (GBookmarkFile
*bookmark
);
241 static gboolean
g_bookmark_file_parse (GBookmarkFile
*bookmark
,
245 static gchar
* g_bookmark_file_dump (GBookmarkFile
*bookmark
,
248 static BookmarkItem
*g_bookmark_file_lookup_item (GBookmarkFile
*bookmark
,
250 static void g_bookmark_file_add_item (GBookmarkFile
*bookmark
,
254 static time_t timestamp_from_iso8601 (const gchar
*iso_date
);
255 static gchar
* timestamp_to_iso8601 (time_t timestamp
);
257 /********************************
260 * Application metadata storage *
261 ********************************/
262 static BookmarkAppInfo
*
263 bookmark_app_info_new (const gchar
*name
)
265 BookmarkAppInfo
*retval
;
267 g_warn_if_fail (name
!= NULL
);
269 retval
= g_slice_new (BookmarkAppInfo
);
271 retval
->name
= g_strdup (name
);
280 bookmark_app_info_free (BookmarkAppInfo
*app_info
)
285 g_free (app_info
->name
);
286 g_free (app_info
->exec
);
288 g_slice_free (BookmarkAppInfo
, app_info
);
292 bookmark_app_info_dump (BookmarkAppInfo
*app_info
)
295 gchar
*name
, *exec
, *modified
, *count
;
297 g_warn_if_fail (app_info
!= NULL
);
299 if (app_info
->count
== 0)
302 name
= g_markup_escape_text (app_info
->name
, -1);
303 exec
= g_markup_escape_text (app_info
->exec
, -1);
304 modified
= timestamp_to_iso8601 (app_info
->stamp
);
305 count
= g_strdup_printf ("%u", app_info
->count
);
307 retval
= g_strconcat (" "
308 "<" BOOKMARK_NAMESPACE_NAME
":" BOOKMARK_APPLICATION_ELEMENT
309 " " BOOKMARK_NAME_ATTRIBUTE
"=\"", name
, "\""
310 " " BOOKMARK_EXEC_ATTRIBUTE
"=\"", exec
, "\""
311 " " BOOKMARK_MODIFIED_ATTRIBUTE
"=\"", modified
, "\""
312 " " BOOKMARK_COUNT_ATTRIBUTE
"=\"", count
, "\"/>\n",
324 /***********************
328 ***********************/
329 static BookmarkMetadata
*
330 bookmark_metadata_new (void)
332 BookmarkMetadata
*retval
;
334 retval
= g_slice_new (BookmarkMetadata
);
336 retval
->mime_type
= NULL
;
338 retval
->groups
= NULL
;
340 retval
->applications
= NULL
;
341 retval
->apps_by_name
= g_hash_table_new_full (g_str_hash
,
346 retval
->is_private
= FALSE
;
348 retval
->icon_href
= NULL
;
349 retval
->icon_mime
= NULL
;
355 bookmark_metadata_free (BookmarkMetadata
*metadata
)
360 g_free (metadata
->mime_type
);
362 if (metadata
->groups
)
364 g_list_foreach (metadata
->groups
,
367 g_list_free (metadata
->groups
);
370 if (metadata
->applications
)
372 g_list_foreach (metadata
->applications
,
373 (GFunc
) bookmark_app_info_free
,
375 g_list_free (metadata
->applications
);
378 g_hash_table_destroy (metadata
->apps_by_name
);
380 g_free (metadata
->icon_href
);
381 g_free (metadata
->icon_mime
);
383 g_slice_free (BookmarkMetadata
, metadata
);
387 bookmark_metadata_dump (BookmarkMetadata
*metadata
)
392 if (!metadata
->applications
)
395 retval
= g_string_sized_new (1024);
397 /* metadata container */
398 g_string_append (retval
,
400 "<" XBEL_METADATA_ELEMENT
401 " " XBEL_OWNER_ATTRIBUTE
"=\"" BOOKMARK_METADATA_OWNER
405 if (metadata
->mime_type
) {
406 buffer
= g_strconcat (" "
407 "<" MIME_NAMESPACE_NAME
":" MIME_TYPE_ELEMENT
" "
408 MIME_TYPE_ATTRIBUTE
"=\"", metadata
->mime_type
, "\"/>\n",
410 g_string_append (retval
, buffer
);
414 if (metadata
->groups
)
418 /* open groups container */
419 g_string_append (retval
,
421 "<" BOOKMARK_NAMESPACE_NAME
422 ":" BOOKMARK_GROUPS_ELEMENT
">\n");
424 for (l
= g_list_last (metadata
->groups
); l
!= NULL
; l
= l
->prev
)
428 group_name
= g_markup_escape_text ((gchar
*) l
->data
, -1);
429 buffer
= g_strconcat (" "
430 "<" BOOKMARK_NAMESPACE_NAME
431 ":" BOOKMARK_GROUP_ELEMENT
">",
433 "</" BOOKMARK_NAMESPACE_NAME
434 ":" BOOKMARK_GROUP_ELEMENT
">\n", NULL
);
435 g_string_append (retval
, buffer
);
441 /* close groups container */
442 g_string_append (retval
,
444 "</" BOOKMARK_NAMESPACE_NAME
445 ":" BOOKMARK_GROUPS_ELEMENT
">\n");
448 if (metadata
->applications
)
452 /* open applications container */
453 g_string_append (retval
,
455 "<" BOOKMARK_NAMESPACE_NAME
456 ":" BOOKMARK_APPLICATIONS_ELEMENT
">\n");
458 for (l
= g_list_last (metadata
->applications
); l
!= NULL
; l
= l
->prev
)
460 BookmarkAppInfo
*app_info
= (BookmarkAppInfo
*) l
->data
;
463 g_warn_if_fail (app_info
!= NULL
);
465 app_data
= bookmark_app_info_dump (app_info
);
469 retval
= g_string_append (retval
, app_data
);
475 /* close applications container */
476 g_string_append (retval
,
478 "</" BOOKMARK_NAMESPACE_NAME
479 ":" BOOKMARK_APPLICATIONS_ELEMENT
">\n");
483 if (metadata
->icon_href
)
485 if (!metadata
->icon_mime
)
486 metadata
->icon_mime
= g_strdup ("application/octet-stream");
488 buffer
= g_strconcat (" "
489 "<" BOOKMARK_NAMESPACE_NAME
490 ":" BOOKMARK_ICON_ELEMENT
491 " " BOOKMARK_HREF_ATTRIBUTE
"=\"", metadata
->icon_href
,
492 "\" " BOOKMARK_TYPE_ATTRIBUTE
"=\"", metadata
->icon_mime
, "\"/>\n", NULL
);
493 g_string_append (retval
, buffer
);
499 if (metadata
->is_private
)
500 g_string_append (retval
,
502 "<" BOOKMARK_NAMESPACE_NAME
503 ":" BOOKMARK_PRIVATE_ELEMENT
"/>\n");
505 /* close metadata container */
506 g_string_append (retval
,
508 "</" XBEL_METADATA_ELEMENT
">\n");
510 return g_string_free (retval
, FALSE
);
513 /******************************************************
516 * Storage for a single bookmark item inside the list *
517 ******************************************************/
518 static BookmarkItem
*
519 bookmark_item_new (const gchar
*uri
)
523 g_warn_if_fail (uri
!= NULL
);
525 item
= g_slice_new (BookmarkItem
);
526 item
->uri
= g_strdup (uri
);
529 item
->description
= NULL
;
531 item
->added
= (time_t) -1;
532 item
->modified
= (time_t) -1;
533 item
->visited
= (time_t) -1;
535 item
->metadata
= NULL
;
541 bookmark_item_free (BookmarkItem
*item
)
547 g_free (item
->title
);
548 g_free (item
->description
);
551 bookmark_metadata_free (item
->metadata
);
553 g_slice_free (BookmarkItem
, item
);
557 bookmark_item_dump (BookmarkItem
*item
)
560 gchar
*added
, *visited
, *modified
;
564 /* at this point, we must have at least a registered application; if we don't
565 * we don't screw up the bookmark file, and just skip this item
567 if (!item
->metadata
|| !item
->metadata
->applications
)
569 g_warning ("Item for URI '%s' has no registered applications: skipping.\n", item
->uri
);
573 retval
= g_string_sized_new (4096);
575 added
= timestamp_to_iso8601 (item
->added
);
576 modified
= timestamp_to_iso8601 (item
->modified
);
577 visited
= timestamp_to_iso8601 (item
->visited
);
579 escaped_uri
= g_markup_escape_text (item
->uri
, -1);
581 buffer
= g_strconcat (" <"
582 XBEL_BOOKMARK_ELEMENT
584 XBEL_HREF_ATTRIBUTE
"=\"", escaped_uri
, "\" "
585 XBEL_ADDED_ATTRIBUTE
"=\"", added
, "\" "
586 XBEL_MODIFIED_ATTRIBUTE
"=\"", modified
, "\" "
587 XBEL_VISITED_ATTRIBUTE
"=\"", visited
, "\">\n",
590 g_string_append (retval
, buffer
);
592 g_free (escaped_uri
);
600 gchar
*escaped_title
;
602 escaped_title
= g_markup_escape_text (item
->title
, -1);
603 buffer
= g_strconcat (" "
604 "<" XBEL_TITLE_ELEMENT
">",
606 "</" XBEL_TITLE_ELEMENT
">\n",
608 g_string_append (retval
, buffer
);
610 g_free (escaped_title
);
614 if (item
->description
)
618 escaped_desc
= g_markup_escape_text (item
->description
, -1);
619 buffer
= g_strconcat (" "
620 "<" XBEL_DESC_ELEMENT
">",
622 "</" XBEL_DESC_ELEMENT
">\n",
624 g_string_append (retval
, buffer
);
626 g_free (escaped_desc
);
634 metadata
= bookmark_metadata_dump (item
->metadata
);
637 buffer
= g_strconcat (" "
638 "<" XBEL_INFO_ELEMENT
">\n",
641 "</" XBEL_INFO_ELEMENT
">\n",
643 retval
= g_string_append (retval
, buffer
);
650 g_string_append (retval
, " </" XBEL_BOOKMARK_ELEMENT
">\n");
652 return g_string_free (retval
, FALSE
);
655 static BookmarkAppInfo
*
656 bookmark_item_lookup_app_info (BookmarkItem
*item
,
657 const gchar
*app_name
)
659 g_warn_if_fail (item
!= NULL
&& app_name
!= NULL
);
664 return g_hash_table_lookup (item
->metadata
->apps_by_name
, app_name
);
667 /*************************
669 *************************/
672 g_bookmark_file_init (GBookmarkFile
*bookmark
)
674 bookmark
->title
= NULL
;
675 bookmark
->description
= NULL
;
677 bookmark
->items
= NULL
;
678 bookmark
->items_by_uri
= g_hash_table_new_full (g_str_hash
,
685 g_bookmark_file_clear (GBookmarkFile
*bookmark
)
687 g_free (bookmark
->title
);
688 g_free (bookmark
->description
);
692 g_list_foreach (bookmark
->items
,
693 (GFunc
) bookmark_item_free
,
695 g_list_free (bookmark
->items
);
697 bookmark
->items
= NULL
;
700 if (bookmark
->items_by_uri
)
702 g_hash_table_destroy (bookmark
->items_by_uri
);
704 bookmark
->items_by_uri
= NULL
;
712 GHashTable
*namespaces
;
714 GBookmarkFile
*bookmark_file
;
715 BookmarkItem
*current_item
;
719 parse_data_new (void)
723 retval
= g_new (ParseData
, 1);
725 retval
->state
= STATE_STARTED
;
726 retval
->namespaces
= g_hash_table_new_full (g_str_hash
, g_str_equal
,
727 (GDestroyNotify
) g_free
,
728 (GDestroyNotify
) g_free
);
729 retval
->bookmark_file
= NULL
;
730 retval
->current_item
= NULL
;
736 parse_data_free (ParseData
*parse_data
)
738 g_hash_table_destroy (parse_data
->namespaces
);
743 #define IS_ATTRIBUTE(s,a) ((0 == strcmp ((s), (a))))
746 parse_bookmark_element (GMarkupParseContext
*context
,
747 ParseData
*parse_data
,
748 const gchar
**attribute_names
,
749 const gchar
**attribute_values
,
752 const gchar
*uri
, *added
, *modified
, *visited
;
758 g_warn_if_fail ((parse_data
!= NULL
) && (parse_data
->state
== STATE_BOOKMARK
));
761 uri
= added
= modified
= visited
= NULL
;
762 for (attr
= attribute_names
[i
]; attr
!= NULL
; attr
= attribute_names
[++i
])
764 if (IS_ATTRIBUTE (attr
, XBEL_HREF_ATTRIBUTE
))
765 uri
= attribute_values
[i
];
766 else if (IS_ATTRIBUTE (attr
, XBEL_ADDED_ATTRIBUTE
))
767 added
= attribute_values
[i
];
768 else if (IS_ATTRIBUTE (attr
, XBEL_MODIFIED_ATTRIBUTE
))
769 modified
= attribute_values
[i
];
770 else if (IS_ATTRIBUTE (attr
, XBEL_VISITED_ATTRIBUTE
))
771 visited
= attribute_values
[i
];
774 /* bookmark is defined by the XBEL spec, so we need
775 * to error out if the element has different or
778 g_set_error (error
, G_MARKUP_ERROR
,
779 G_MARKUP_ERROR_UNKNOWN_ATTRIBUTE
,
780 _("Unexpected attribute '%s' for element '%s'"),
782 XBEL_BOOKMARK_ELEMENT
);
789 g_set_error (error
, G_MARKUP_ERROR
,
790 G_MARKUP_ERROR_INVALID_CONTENT
,
791 _("Attribute '%s' of element '%s' not found"),
793 XBEL_BOOKMARK_ELEMENT
);
797 g_warn_if_fail (parse_data
->current_item
== NULL
);
799 item
= bookmark_item_new (uri
);
802 item
->added
= timestamp_from_iso8601 (added
);
805 item
->modified
= timestamp_from_iso8601 (modified
);
808 item
->visited
= timestamp_from_iso8601 (visited
);
811 g_bookmark_file_add_item (parse_data
->bookmark_file
,
816 bookmark_item_free (item
);
818 g_propagate_error (error
, add_error
);
823 parse_data
->current_item
= item
;
827 parse_application_element (GMarkupParseContext
*context
,
828 ParseData
*parse_data
,
829 const gchar
**attribute_names
,
830 const gchar
**attribute_values
,
833 const gchar
*name
, *exec
, *count
, *stamp
, *modified
;
839 g_warn_if_fail ((parse_data
!= NULL
) && (parse_data
->state
== STATE_APPLICATION
));
842 name
= exec
= count
= stamp
= modified
= NULL
;
843 for (attr
= attribute_names
[i
]; attr
!= NULL
; attr
= attribute_names
[++i
])
845 if (IS_ATTRIBUTE (attr
, BOOKMARK_NAME_ATTRIBUTE
))
846 name
= attribute_values
[i
];
847 else if (IS_ATTRIBUTE (attr
, BOOKMARK_EXEC_ATTRIBUTE
))
848 exec
= attribute_values
[i
];
849 else if (IS_ATTRIBUTE (attr
, BOOKMARK_COUNT_ATTRIBUTE
))
850 count
= attribute_values
[i
];
851 else if (IS_ATTRIBUTE (attr
, BOOKMARK_TIMESTAMP_ATTRIBUTE
))
852 stamp
= attribute_values
[i
];
853 else if (IS_ATTRIBUTE (attr
, BOOKMARK_MODIFIED_ATTRIBUTE
))
854 modified
= attribute_values
[i
];
857 /* the "name" and "exec" attributes are mandatory */
860 g_set_error (error
, G_MARKUP_ERROR
,
861 G_MARKUP_ERROR_INVALID_CONTENT
,
862 _("Attribute '%s' of element '%s' not found"),
863 BOOKMARK_NAME_ATTRIBUTE
,
864 BOOKMARK_APPLICATION_ELEMENT
);
870 g_set_error (error
, G_MARKUP_ERROR
,
871 G_MARKUP_ERROR_INVALID_CONTENT
,
872 _("Attribute '%s' of element '%s' not found"),
873 BOOKMARK_EXEC_ATTRIBUTE
,
874 BOOKMARK_APPLICATION_ELEMENT
);
878 g_warn_if_fail (parse_data
->current_item
!= NULL
);
879 item
= parse_data
->current_item
;
881 ai
= bookmark_item_lookup_app_info (item
, name
);
884 ai
= bookmark_app_info_new (name
);
887 item
->metadata
= bookmark_metadata_new ();
889 item
->metadata
->applications
= g_list_prepend (item
->metadata
->applications
, ai
);
890 g_hash_table_replace (item
->metadata
->apps_by_name
, ai
->name
, ai
);
893 ai
->exec
= g_strdup (exec
);
896 ai
->count
= atoi (count
);
901 ai
->stamp
= timestamp_from_iso8601 (modified
);
904 /* the timestamp attribute has been deprecated but we still parse
905 * it for backward compatibility
908 ai
->stamp
= (time_t) atol (stamp
);
910 ai
->stamp
= time (NULL
);
915 parse_mime_type_element (GMarkupParseContext
*context
,
916 ParseData
*parse_data
,
917 const gchar
**attribute_names
,
918 const gchar
**attribute_values
,
926 g_warn_if_fail ((parse_data
!= NULL
) && (parse_data
->state
== STATE_MIME
));
930 for (attr
= attribute_names
[i
]; attr
!= NULL
; attr
= attribute_names
[++i
])
932 if (IS_ATTRIBUTE (attr
, MIME_TYPE_ATTRIBUTE
))
933 type
= attribute_values
[i
];
937 type
= "application/octet-stream";
939 g_warn_if_fail (parse_data
->current_item
!= NULL
);
940 item
= parse_data
->current_item
;
943 item
->metadata
= bookmark_metadata_new ();
945 item
->metadata
->mime_type
= g_strdup (type
);
949 parse_icon_element (GMarkupParseContext
*context
,
950 ParseData
*parse_data
,
951 const gchar
**attribute_names
,
952 const gchar
**attribute_values
,
961 g_warn_if_fail ((parse_data
!= NULL
) && (parse_data
->state
== STATE_ICON
));
966 for (attr
= attribute_names
[i
]; attr
!= NULL
; attr
= attribute_names
[++i
])
968 if (IS_ATTRIBUTE (attr
, BOOKMARK_HREF_ATTRIBUTE
))
969 href
= attribute_values
[i
];
970 else if (IS_ATTRIBUTE (attr
, BOOKMARK_TYPE_ATTRIBUTE
))
971 type
= attribute_values
[i
];
974 /* the "href" attribute is mandatory */
977 g_set_error (error
, G_MARKUP_ERROR
,
978 G_MARKUP_ERROR_INVALID_CONTENT
,
979 _("Attribute '%s' of element '%s' not found"),
980 BOOKMARK_HREF_ATTRIBUTE
,
981 BOOKMARK_ICON_ELEMENT
);
986 type
= "application/octet-stream";
988 g_warn_if_fail (parse_data
->current_item
!= NULL
);
989 item
= parse_data
->current_item
;
992 item
->metadata
= bookmark_metadata_new ();
994 item
->metadata
->icon_href
= g_strdup (href
);
995 item
->metadata
->icon_mime
= g_strdup (type
);
998 /* scans through the attributes of an element for the "xmlns" pragma, and
999 * adds any resulting namespace declaration to a per-parser hashtable, using
1000 * the namespace name as a key for the namespace URI; if no key was found,
1001 * the namespace is considered as default, and stored under the "default" key.
1003 * FIXME: this works on the assumption that the generator of the XBEL file
1004 * is either this code or is smart enough to place the namespace declarations
1005 * inside the main root node or inside the metadata node and does not redefine
1006 * a namespace inside an inner node; this does *not* conform to the
1007 * XML-NS standard, although is a close approximation. In order to make this
1008 * conformant to the XML-NS specification we should use a per-element
1009 * namespace table inside GMarkup and ask it to resolve the namespaces for us.
1012 map_namespace_to_name (ParseData
*parse_data
,
1013 const gchar
**attribute_names
,
1014 const gchar
**attribute_values
)
1019 g_warn_if_fail (parse_data
!= NULL
);
1021 if (!attribute_names
|| !attribute_names
[0])
1025 for (attr
= attribute_names
[i
]; attr
; attr
= attribute_names
[++i
])
1027 if (g_str_has_prefix (attr
, "xmlns"))
1029 gchar
*namespace_name
, *namespace_uri
;
1032 p
= g_utf8_strchr (attr
, -1, ':');
1034 p
= g_utf8_next_char (p
);
1038 namespace_name
= g_strdup (p
);
1039 namespace_uri
= g_strdup (attribute_values
[i
]);
1041 g_hash_table_replace (parse_data
->namespaces
,
1048 /* checks whether @element_full is equal to @element.
1050 * if @namespace is set, it tries to resolve the namespace to a known URI,
1051 * and if found is prepended to the element name, from which is separated
1052 * using the character specified in the @sep parameter.
1055 is_element_full (ParseData
*parse_data
,
1056 const gchar
*element_full
,
1057 const gchar
*namespace,
1058 const gchar
*element
,
1061 gchar
*ns_uri
, *ns_name
;
1062 const gchar
*p
, *element_name
;
1065 g_warn_if_fail (parse_data
!= NULL
);
1066 g_warn_if_fail (element_full
!= NULL
);
1071 /* no namespace requested: dumb element compare */
1073 return (0 == strcmp (element_full
, element
));
1075 /* search for namespace separator; if none found, assume we are under the
1076 * default namespace, and set ns_name to our "default" marker; if no default
1077 * namespace has been set, just do a plain comparison between @full_element
1080 p
= g_utf8_strchr (element_full
, -1, ':');
1083 ns_name
= g_strndup (element_full
, p
- element_full
);
1084 element_name
= g_utf8_next_char (p
);
1088 ns_name
= g_strdup ("default");
1089 element_name
= element_full
;
1092 ns_uri
= g_hash_table_lookup (parse_data
->namespaces
, ns_name
);
1095 /* no default namespace found */
1098 return (0 == strcmp (element_full
, element
));
1101 retval
= (0 == strcmp (ns_uri
, namespace) &&
1102 0 == strcmp (element_name
, element
));
1109 #define IS_ELEMENT(p,s,e) (is_element_full ((p), (s), NULL, (e), '\0'))
1110 #define IS_ELEMENT_NS(p,s,n,e) (is_element_full ((p), (s), (n), (e), '|'))
1113 start_element_raw_cb (GMarkupParseContext
*context
,
1114 const gchar
*element_name
,
1115 const gchar
**attribute_names
,
1116 const gchar
**attribute_values
,
1120 ParseData
*parse_data
= (ParseData
*) user_data
;
1122 /* we must check for namespace declarations first
1124 * XXX - we could speed up things by checking for namespace declarations
1125 * only on the root node, where they usually are; this would probably break
1126 * on streams not produced by us or by "smart" generators
1128 map_namespace_to_name (parse_data
, attribute_names
, attribute_values
);
1130 switch (parse_data
->state
)
1133 if (IS_ELEMENT (parse_data
, element_name
, XBEL_ROOT_ELEMENT
))
1139 for (attr
= attribute_names
[i
]; attr
; attr
= attribute_names
[++i
])
1141 if ((IS_ATTRIBUTE (attr
, XBEL_VERSION_ATTRIBUTE
)) &&
1142 (0 == strcmp (attribute_values
[i
], XBEL_VERSION
)))
1143 parse_data
->state
= STATE_ROOT
;
1147 g_set_error (error
, G_MARKUP_ERROR
,
1148 G_MARKUP_ERROR_INVALID_CONTENT
,
1149 _("Unexpected tag '%s', tag '%s' expected"),
1150 element_name
, XBEL_ROOT_ELEMENT
);
1153 if (IS_ELEMENT (parse_data
, element_name
, XBEL_TITLE_ELEMENT
))
1154 parse_data
->state
= STATE_TITLE
;
1155 else if (IS_ELEMENT (parse_data
, element_name
, XBEL_DESC_ELEMENT
))
1156 parse_data
->state
= STATE_DESC
;
1157 else if (IS_ELEMENT (parse_data
, element_name
, XBEL_BOOKMARK_ELEMENT
))
1159 GError
*inner_error
= NULL
;
1161 parse_data
->state
= STATE_BOOKMARK
;
1163 parse_bookmark_element (context
,
1169 g_propagate_error (error
, inner_error
);
1172 g_set_error (error
, G_MARKUP_ERROR
,
1173 G_MARKUP_ERROR_INVALID_CONTENT
,
1174 _("Unexpected tag '%s' inside '%s'"),
1178 case STATE_BOOKMARK
:
1179 if (IS_ELEMENT (parse_data
, element_name
, XBEL_TITLE_ELEMENT
))
1180 parse_data
->state
= STATE_TITLE
;
1181 else if (IS_ELEMENT (parse_data
, element_name
, XBEL_DESC_ELEMENT
))
1182 parse_data
->state
= STATE_DESC
;
1183 else if (IS_ELEMENT (parse_data
, element_name
, XBEL_INFO_ELEMENT
))
1184 parse_data
->state
= STATE_INFO
;
1186 g_set_error (error
, G_MARKUP_ERROR
,
1187 G_MARKUP_ERROR_INVALID_CONTENT
,
1188 _("Unexpected tag '%s' inside '%s'"),
1190 XBEL_BOOKMARK_ELEMENT
);
1193 if (IS_ELEMENT (parse_data
, element_name
, XBEL_METADATA_ELEMENT
))
1199 for (attr
= attribute_names
[i
]; attr
; attr
= attribute_names
[++i
])
1201 if ((IS_ATTRIBUTE (attr
, XBEL_OWNER_ATTRIBUTE
)) &&
1202 (0 == strcmp (attribute_values
[i
], BOOKMARK_METADATA_OWNER
)))
1204 parse_data
->state
= STATE_METADATA
;
1206 if (!parse_data
->current_item
->metadata
)
1207 parse_data
->current_item
->metadata
= bookmark_metadata_new ();
1212 g_set_error (error
, G_MARKUP_ERROR
,
1213 G_MARKUP_ERROR_INVALID_CONTENT
,
1214 _("Unexpected tag '%s', tag '%s' expected"),
1216 XBEL_METADATA_ELEMENT
);
1218 case STATE_METADATA
:
1219 if (IS_ELEMENT_NS (parse_data
, element_name
, BOOKMARK_NAMESPACE_URI
, BOOKMARK_APPLICATIONS_ELEMENT
))
1220 parse_data
->state
= STATE_APPLICATIONS
;
1221 else if (IS_ELEMENT_NS (parse_data
, element_name
, BOOKMARK_NAMESPACE_URI
, BOOKMARK_GROUPS_ELEMENT
))
1222 parse_data
->state
= STATE_GROUPS
;
1223 else if (IS_ELEMENT_NS (parse_data
, element_name
, BOOKMARK_NAMESPACE_URI
, BOOKMARK_PRIVATE_ELEMENT
))
1224 parse_data
->current_item
->metadata
->is_private
= TRUE
;
1225 else if (IS_ELEMENT_NS (parse_data
, element_name
, BOOKMARK_NAMESPACE_URI
, BOOKMARK_ICON_ELEMENT
))
1227 GError
*inner_error
= NULL
;
1229 parse_data
->state
= STATE_ICON
;
1231 parse_icon_element (context
,
1237 g_propagate_error (error
, inner_error
);
1239 else if (IS_ELEMENT_NS (parse_data
, element_name
, MIME_NAMESPACE_URI
, MIME_TYPE_ELEMENT
))
1241 GError
*inner_error
= NULL
;
1243 parse_data
->state
= STATE_MIME
;
1245 parse_mime_type_element (context
,
1251 g_propagate_error (error
, inner_error
);
1254 g_set_error (error
, G_MARKUP_ERROR
,
1255 G_MARKUP_ERROR_UNKNOWN_ELEMENT
,
1256 _("Unexpected tag '%s' inside '%s'"),
1258 XBEL_METADATA_ELEMENT
);
1260 case STATE_APPLICATIONS
:
1261 if (IS_ELEMENT_NS (parse_data
, element_name
, BOOKMARK_NAMESPACE_URI
, BOOKMARK_APPLICATION_ELEMENT
))
1263 GError
*inner_error
= NULL
;
1265 parse_data
->state
= STATE_APPLICATION
;
1267 parse_application_element (context
,
1273 g_propagate_error (error
, inner_error
);
1276 g_set_error (error
, G_MARKUP_ERROR
,
1277 G_MARKUP_ERROR_INVALID_CONTENT
,
1278 _("Unexpected tag '%s', tag '%s' expected"),
1280 BOOKMARK_APPLICATION_ELEMENT
);
1283 if (IS_ELEMENT_NS (parse_data
, element_name
, BOOKMARK_NAMESPACE_URI
, BOOKMARK_GROUP_ELEMENT
))
1284 parse_data
->state
= STATE_GROUP
;
1286 g_set_error (error
, G_MARKUP_ERROR
,
1287 G_MARKUP_ERROR_INVALID_CONTENT
,
1288 _("Unexpected tag '%s', tag '%s' expected"),
1290 BOOKMARK_GROUP_ELEMENT
);
1293 if (IS_ELEMENT_NS (parse_data
, element_name
, BOOKMARK_NAMESPACE_URI
, BOOKMARK_ICON_ELEMENT
))
1295 GError
*inner_error
= NULL
;
1297 parse_icon_element (context
,
1303 g_propagate_error (error
, inner_error
);
1306 g_set_error (error
, G_MARKUP_ERROR
,
1307 G_MARKUP_ERROR_UNKNOWN_ELEMENT
,
1308 _("Unexpected tag '%s' inside '%s'"),
1310 XBEL_METADATA_ELEMENT
);
1313 g_warn_if_reached ();
1319 end_element_raw_cb (GMarkupParseContext
*context
,
1320 const gchar
*element_name
,
1324 ParseData
*parse_data
= (ParseData
*) user_data
;
1326 if (IS_ELEMENT (parse_data
, element_name
, XBEL_ROOT_ELEMENT
))
1327 parse_data
->state
= STATE_FINISHED
;
1328 else if (IS_ELEMENT (parse_data
, element_name
, XBEL_BOOKMARK_ELEMENT
))
1330 parse_data
->current_item
= NULL
;
1332 parse_data
->state
= STATE_ROOT
;
1334 else if ((IS_ELEMENT (parse_data
, element_name
, XBEL_INFO_ELEMENT
)) ||
1335 (IS_ELEMENT (parse_data
, element_name
, XBEL_TITLE_ELEMENT
)) ||
1336 (IS_ELEMENT (parse_data
, element_name
, XBEL_DESC_ELEMENT
)))
1338 if (parse_data
->current_item
)
1339 parse_data
->state
= STATE_BOOKMARK
;
1341 parse_data
->state
= STATE_ROOT
;
1343 else if (IS_ELEMENT (parse_data
, element_name
, XBEL_METADATA_ELEMENT
))
1344 parse_data
->state
= STATE_INFO
;
1345 else if (IS_ELEMENT_NS (parse_data
, element_name
,
1346 BOOKMARK_NAMESPACE_URI
,
1347 BOOKMARK_APPLICATION_ELEMENT
))
1348 parse_data
->state
= STATE_APPLICATIONS
;
1349 else if (IS_ELEMENT_NS (parse_data
, element_name
,
1350 BOOKMARK_NAMESPACE_URI
,
1351 BOOKMARK_GROUP_ELEMENT
))
1352 parse_data
->state
= STATE_GROUPS
;
1353 else if ((IS_ELEMENT_NS (parse_data
, element_name
, BOOKMARK_NAMESPACE_URI
, BOOKMARK_APPLICATIONS_ELEMENT
)) ||
1354 (IS_ELEMENT_NS (parse_data
, element_name
, BOOKMARK_NAMESPACE_URI
, BOOKMARK_GROUPS_ELEMENT
)) ||
1355 (IS_ELEMENT_NS (parse_data
, element_name
, BOOKMARK_NAMESPACE_URI
, BOOKMARK_PRIVATE_ELEMENT
)) ||
1356 (IS_ELEMENT_NS (parse_data
, element_name
, BOOKMARK_NAMESPACE_URI
, BOOKMARK_ICON_ELEMENT
)) ||
1357 (IS_ELEMENT_NS (parse_data
, element_name
, MIME_NAMESPACE_URI
, MIME_TYPE_ELEMENT
)))
1358 parse_data
->state
= STATE_METADATA
;
1362 text_raw_cb (GMarkupParseContext
*context
,
1368 ParseData
*parse_data
= (ParseData
*) user_data
;
1371 payload
= g_strndup (text
, length
);
1373 switch (parse_data
->state
)
1376 if (parse_data
->current_item
)
1378 g_free (parse_data
->current_item
->title
);
1379 parse_data
->current_item
->title
= g_strdup (payload
);
1383 g_free (parse_data
->bookmark_file
->title
);
1384 parse_data
->bookmark_file
->title
= g_strdup (payload
);
1388 if (parse_data
->current_item
)
1390 g_free (parse_data
->current_item
->description
);
1391 parse_data
->current_item
->description
= g_strdup (payload
);
1395 g_free (parse_data
->bookmark_file
->description
);
1396 parse_data
->bookmark_file
->description
= g_strdup (payload
);
1403 g_warn_if_fail (parse_data
->current_item
!= NULL
);
1405 if (!parse_data
->current_item
->metadata
)
1406 parse_data
->current_item
->metadata
= bookmark_metadata_new ();
1408 groups
= parse_data
->current_item
->metadata
->groups
;
1409 parse_data
->current_item
->metadata
->groups
= g_list_prepend (groups
, g_strdup (payload
));
1413 case STATE_BOOKMARK
:
1415 case STATE_METADATA
:
1416 case STATE_APPLICATIONS
:
1417 case STATE_APPLICATION
:
1423 g_warn_if_reached ();
1430 static const GMarkupParser markup_parser
=
1432 start_element_raw_cb
, /* start_element */
1433 end_element_raw_cb
, /* end_element */
1434 text_raw_cb
, /* text */
1435 NULL
, /* passthrough */
1440 g_bookmark_file_parse (GBookmarkFile
*bookmark
,
1441 const gchar
*buffer
,
1445 GMarkupParseContext
*context
;
1446 ParseData
*parse_data
;
1447 GError
*parse_error
, *end_error
;
1450 g_warn_if_fail (bookmark
!= NULL
);
1455 if (length
== (gsize
) -1)
1456 length
= strlen (buffer
);
1458 parse_data
= parse_data_new ();
1459 parse_data
->bookmark_file
= bookmark
;
1461 context
= g_markup_parse_context_new (&markup_parser
,
1464 (GDestroyNotify
) parse_data_free
);
1467 retval
= g_markup_parse_context_parse (context
,
1473 g_propagate_error (error
, parse_error
);
1479 retval
= g_markup_parse_context_end_parse (context
, &end_error
);
1482 g_propagate_error (error
, end_error
);
1487 g_markup_parse_context_free (context
);
1493 g_bookmark_file_dump (GBookmarkFile
*bookmark
,
1501 retval
= g_string_sized_new (4096);
1503 g_string_append (retval
,
1504 "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n"
1506 /* XXX - do we really need the doctype? */
1507 "<!DOCTYPE " XBEL_DTD_NICK
"\n"
1508 " PUBLIC \"" XBEL_DTD_SYSTEM
"\"\n"
1509 " \"" XBEL_DTD_URI
"\">\n"
1511 "<" XBEL_ROOT_ELEMENT
" " XBEL_VERSION_ATTRIBUTE
"=\"" XBEL_VERSION
"\"\n"
1512 " xmlns:" BOOKMARK_NAMESPACE_NAME
"=\"" BOOKMARK_NAMESPACE_URI
"\"\n"
1513 " xmlns:" MIME_NAMESPACE_NAME
"=\"" MIME_NAMESPACE_URI
"\"\n>");
1515 if (bookmark
->title
)
1517 gchar
*escaped_title
;
1519 escaped_title
= g_markup_escape_text (bookmark
->title
, -1);
1521 buffer
= g_strconcat (" "
1522 "<" XBEL_TITLE_ELEMENT
">",
1524 "</" XBEL_TITLE_ELEMENT
">\n", NULL
);
1526 g_string_append (retval
, buffer
);
1529 g_free (escaped_title
);
1532 if (bookmark
->description
)
1534 gchar
*escaped_desc
;
1536 escaped_desc
= g_markup_escape_text (bookmark
->description
, -1);
1538 buffer
= g_strconcat (" "
1539 "<" XBEL_DESC_ELEMENT
">",
1541 "</" XBEL_DESC_ELEMENT
">\n", NULL
);
1542 g_string_append (retval
, buffer
);
1545 g_free (escaped_desc
);
1548 if (!bookmark
->items
)
1551 retval
= g_string_append (retval
, "\n");
1553 /* the items are stored in reverse order */
1554 for (l
= g_list_last (bookmark
->items
);
1558 BookmarkItem
*item
= (BookmarkItem
*) l
->data
;
1561 item_dump
= bookmark_item_dump (item
);
1565 retval
= g_string_append (retval
, item_dump
);
1571 g_string_append (retval
, "</" XBEL_ROOT_ELEMENT
">");
1574 *length
= retval
->len
;
1576 return g_string_free (retval
, FALSE
);
1583 /* converts a Unix timestamp in a ISO 8601 compliant string; you
1584 * should free the returned string.
1587 timestamp_to_iso8601 (time_t timestamp
)
1591 if (timestamp
== (time_t) -1)
1592 g_get_current_time (&stamp
);
1595 stamp
.tv_sec
= timestamp
;
1599 return g_time_val_to_iso8601 (&stamp
);
1603 timestamp_from_iso8601 (const gchar
*iso_date
)
1607 if (!g_time_val_from_iso8601 (iso_date
, &stamp
))
1610 return (time_t) stamp
.tv_sec
;
1616 g_bookmark_file_error_quark (void)
1618 return g_quark_from_static_string ("g-bookmark-file-error-quark");
1623 /********************
1625 ********************/
1628 * g_bookmark_file_new:
1630 * Creates a new empty #GBookmarkFile object.
1632 * Use g_bookmark_file_load_from_file(), g_bookmark_file_load_from_data()
1633 * or g_bookmark_file_load_from_data_dirs() to read an existing bookmark
1636 * Return value: an empty #GBookmarkFile
1641 g_bookmark_file_new (void)
1643 GBookmarkFile
*bookmark
;
1645 bookmark
= g_new (GBookmarkFile
, 1);
1647 g_bookmark_file_init (bookmark
);
1653 * g_bookmark_file_free:
1654 * @bookmark: a #GBookmarkFile
1656 * Frees a #GBookmarkFile.
1661 g_bookmark_file_free (GBookmarkFile
*bookmark
)
1666 g_bookmark_file_clear (bookmark
);
1672 * g_bookmark_file_load_from_data:
1673 * @bookmark: an empty #GBookmarkFile struct
1674 * @data: desktop bookmarks loaded in memory
1675 * @length: the length of @data in bytes
1676 * @error: return location for a #GError, or %NULL
1678 * Loads a bookmark file from memory into an empty #GBookmarkFile
1679 * structure. If the object cannot be created then @error is set to a
1680 * #GBookmarkFileError.
1682 * Return value: %TRUE if a desktop bookmark could be loaded.
1687 g_bookmark_file_load_from_data (GBookmarkFile
*bookmark
,
1692 GError
*parse_error
;
1695 g_return_val_if_fail (bookmark
!= NULL
, FALSE
);
1697 if (length
== (gsize
) -1)
1698 length
= strlen (data
);
1700 if (bookmark
->items
)
1702 g_bookmark_file_clear (bookmark
);
1703 g_bookmark_file_init (bookmark
);
1707 retval
= g_bookmark_file_parse (bookmark
, data
, length
, &parse_error
);
1710 g_propagate_error (error
, parse_error
);
1719 * g_bookmark_file_load_from_file:
1720 * @bookmark: an empty #GBookmarkFile struct
1721 * @filename: the path of a filename to load, in the GLib file name encoding
1722 * @error: return location for a #GError, or %NULL
1724 * Loads a desktop bookmark file into an empty #GBookmarkFile structure.
1725 * If the file could not be loaded then @error is set to either a #GFileError
1726 * or #GBookmarkFileError.
1728 * Return value: %TRUE if a desktop bookmark file could be loaded
1733 g_bookmark_file_load_from_file (GBookmarkFile
*bookmark
,
1734 const gchar
*filename
,
1742 g_return_val_if_fail (bookmark
!= NULL
, FALSE
);
1743 g_return_val_if_fail (filename
!= NULL
, FALSE
);
1746 g_file_get_contents (filename
, &buffer
, &len
, &read_error
);
1749 g_propagate_error (error
, read_error
);
1755 retval
= g_bookmark_file_load_from_data (bookmark
,
1761 g_propagate_error (error
, read_error
);
1774 /* Iterates through all the directories in *dirs trying to
1775 * find file. When it successfully locates file, returns a
1776 * string its absolute path. It also leaves the unchecked
1777 * directories in *dirs. You should free the returned string
1779 * Adapted from gkeyfile.c
1782 find_file_in_data_dirs (const gchar
*file
,
1786 gchar
**data_dirs
, *data_dir
, *path
;
1795 while (data_dirs
&& (data_dir
= *data_dirs
) && !path
)
1797 gchar
*candidate_file
, *sub_dir
;
1799 candidate_file
= (gchar
*) file
;
1800 sub_dir
= g_strdup ("");
1801 while (candidate_file
!= NULL
&& !path
)
1805 path
= g_build_filename (data_dir
, sub_dir
,
1806 candidate_file
, NULL
);
1808 candidate_file
= strchr (candidate_file
, '-');
1810 if (candidate_file
== NULL
)
1816 sub_dir
= g_strndup (file
, candidate_file
- file
- 1);
1818 for (p
= sub_dir
; *p
!= '\0'; p
++)
1821 *p
= G_DIR_SEPARATOR
;
1832 g_set_error_literal (error
, G_BOOKMARK_FILE_ERROR
,
1833 G_BOOKMARK_FILE_ERROR_FILE_NOT_FOUND
,
1834 _("No valid bookmark file found in data dirs"));
1844 * g_bookmark_file_load_from_data_dirs:
1845 * @bookmark: a #GBookmarkFile
1846 * @file: a relative path to a filename to open and parse
1847 * @full_path: return location for a string containing the full path
1848 * of the file, or %NULL
1849 * @error: return location for a #GError, or %NULL
1851 * This function looks for a desktop bookmark file named @file in the
1852 * paths returned from g_get_user_data_dir() and g_get_system_data_dirs(),
1853 * loads the file into @bookmark and returns the file's full path in
1854 * @full_path. If the file could not be loaded then an %error is
1855 * set to either a #GFileError or #GBookmarkFileError.
1857 * Return value: %TRUE if a key file could be loaded, %FALSE othewise
1862 g_bookmark_file_load_from_data_dirs (GBookmarkFile
*bookmark
,
1867 GError
*file_error
= NULL
;
1868 gchar
**all_data_dirs
, **data_dirs
;
1869 const gchar
*user_data_dir
;
1870 const gchar
* const * system_data_dirs
;
1873 gboolean found_file
;
1875 g_return_val_if_fail (bookmark
!= NULL
, FALSE
);
1876 g_return_val_if_fail (!g_path_is_absolute (file
), FALSE
);
1878 user_data_dir
= g_get_user_data_dir ();
1879 system_data_dirs
= g_get_system_data_dirs ();
1880 all_data_dirs
= g_new0 (gchar
*, g_strv_length ((gchar
**)system_data_dirs
) + 2);
1883 all_data_dirs
[i
++] = g_strdup (user_data_dir
);
1886 while (system_data_dirs
[j
] != NULL
)
1887 all_data_dirs
[i
++] = g_strdup (system_data_dirs
[j
++]);
1890 data_dirs
= all_data_dirs
;
1892 while (*data_dirs
!= NULL
&& !found_file
)
1894 g_free (output_path
);
1896 output_path
= find_file_in_data_dirs (file
, &data_dirs
, &file_error
);
1900 g_propagate_error (error
, file_error
);
1904 found_file
= g_bookmark_file_load_from_file (bookmark
,
1909 g_propagate_error (error
, file_error
);
1914 if (found_file
&& full_path
)
1915 *full_path
= output_path
;
1917 g_free (output_path
);
1919 g_strfreev (all_data_dirs
);
1926 * g_bookmark_file_to_data:
1927 * @bookmark: a #GBookmarkFile
1928 * @length: return location for the length of the returned string, or %NULL
1929 * @error: return location for a #GError, or %NULL
1931 * This function outputs @bookmark as a string.
1933 * Return value: a newly allocated string holding
1934 * the contents of the #GBookmarkFile
1939 g_bookmark_file_to_data (GBookmarkFile
*bookmark
,
1943 GError
*write_error
= NULL
;
1946 g_return_val_if_fail (bookmark
!= NULL
, NULL
);
1948 retval
= g_bookmark_file_dump (bookmark
, length
, &write_error
);
1951 g_propagate_error (error
, write_error
);
1960 * g_bookmark_file_to_file:
1961 * @bookmark: a #GBookmarkFile
1962 * @filename: path of the output file
1963 * @error: return location for a #GError, or %NULL
1965 * This function outputs @bookmark into a file. The write process is
1966 * guaranteed to be atomic by using g_file_set_contents() internally.
1968 * Return value: %TRUE if the file was successfully written.
1973 g_bookmark_file_to_file (GBookmarkFile
*bookmark
,
1974 const gchar
*filename
,
1978 GError
*data_error
, *write_error
;
1982 g_return_val_if_fail (bookmark
!= NULL
, FALSE
);
1983 g_return_val_if_fail (filename
!= NULL
, FALSE
);
1986 data
= g_bookmark_file_to_data (bookmark
, &len
, &data_error
);
1989 g_propagate_error (error
, data_error
);
1995 g_file_set_contents (filename
, data
, len
, &write_error
);
1998 g_propagate_error (error
, write_error
);
2010 static BookmarkItem
*
2011 g_bookmark_file_lookup_item (GBookmarkFile
*bookmark
,
2014 g_warn_if_fail (bookmark
!= NULL
&& uri
!= NULL
);
2016 return g_hash_table_lookup (bookmark
->items_by_uri
, uri
);
2019 /* this function adds a new item to the list */
2021 g_bookmark_file_add_item (GBookmarkFile
*bookmark
,
2025 g_warn_if_fail (bookmark
!= NULL
);
2026 g_warn_if_fail (item
!= NULL
);
2028 /* this should never happen; and if it does, then we are
2029 * screwing up something big time.
2031 if (G_UNLIKELY (g_bookmark_file_has_item (bookmark
, item
->uri
)))
2033 g_set_error (error
, G_BOOKMARK_FILE_ERROR
,
2034 G_BOOKMARK_FILE_ERROR_INVALID_URI
,
2035 _("A bookmark for URI '%s' already exists"),
2040 bookmark
->items
= g_list_prepend (bookmark
->items
, item
);
2042 g_hash_table_replace (bookmark
->items_by_uri
,
2046 if (item
->added
== (time_t) -1)
2047 item
->added
= time (NULL
);
2049 if (item
->modified
== (time_t) -1)
2050 item
->modified
= time (NULL
);
2054 * g_bookmark_file_remove_item:
2055 * @bookmark: a #GBookmarkFile
2057 * @error: return location for a #GError, or %NULL
2059 * Removes the bookmark for @uri from the bookmark file @bookmark.
2061 * Return value: %TRUE if the bookmark was removed successfully.
2066 g_bookmark_file_remove_item (GBookmarkFile
*bookmark
,
2072 g_return_val_if_fail (bookmark
!= NULL
, FALSE
);
2073 g_return_val_if_fail (uri
!= NULL
, FALSE
);
2075 item
= g_bookmark_file_lookup_item (bookmark
, uri
);
2079 g_set_error (error
, G_BOOKMARK_FILE_ERROR
,
2080 G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND
,
2081 _("No bookmark found for URI '%s'"),
2086 bookmark
->items
= g_list_remove (bookmark
->items
, item
);
2087 g_hash_table_remove (bookmark
->items_by_uri
, item
->uri
);
2089 bookmark_item_free (item
);
2095 * g_bookmark_file_has_item:
2096 * @bookmark: a #GBookmarkFile
2099 * Looks whether the desktop bookmark has an item with its URI set to @uri.
2101 * Return value: %TRUE if @uri is inside @bookmark, %FALSE otherwise
2106 g_bookmark_file_has_item (GBookmarkFile
*bookmark
,
2109 g_return_val_if_fail (bookmark
!= NULL
, FALSE
);
2110 g_return_val_if_fail (uri
!= NULL
, FALSE
);
2112 return (NULL
!= g_hash_table_lookup (bookmark
->items_by_uri
, uri
));
2116 * g_bookmark_file_get_uris:
2117 * @bookmark: a #GBookmarkFile
2118 * @length: return location for the number of returned URIs, or %NULL
2120 * Returns all URIs of the bookmarks in the bookmark file @bookmark.
2121 * The array of returned URIs will be %NULL-terminated, so @length may
2122 * optionally be %NULL.
2124 * Return value: a newly allocated %NULL-terminated array of strings.
2125 * Use g_strfreev() to free it.
2130 g_bookmark_file_get_uris (GBookmarkFile
*bookmark
,
2137 g_return_val_if_fail (bookmark
!= NULL
, NULL
);
2139 n_items
= g_list_length (bookmark
->items
);
2140 uris
= g_new0 (gchar
*, n_items
+ 1);
2142 /* the items are stored in reverse order, so we walk the list backward */
2143 for (l
= g_list_last (bookmark
->items
), i
= 0; l
!= NULL
; l
= l
->prev
)
2145 BookmarkItem
*item
= (BookmarkItem
*) l
->data
;
2147 g_warn_if_fail (item
!= NULL
);
2149 uris
[i
++] = g_strdup (item
->uri
);
2160 * g_bookmark_file_set_title:
2161 * @bookmark: a #GBookmarkFile
2162 * @uri: a valid URI or %NULL
2163 * @title: a UTF-8 encoded string
2165 * Sets @title as the title of the bookmark for @uri inside the
2166 * bookmark file @bookmark.
2168 * If @uri is %NULL, the title of @bookmark is set.
2170 * If a bookmark for @uri cannot be found then it is created.
2175 g_bookmark_file_set_title (GBookmarkFile
*bookmark
,
2179 g_return_if_fail (bookmark
!= NULL
);
2183 g_free (bookmark
->title
);
2184 bookmark
->title
= g_strdup (title
);
2190 item
= g_bookmark_file_lookup_item (bookmark
, uri
);
2193 item
= bookmark_item_new (uri
);
2194 g_bookmark_file_add_item (bookmark
, item
, NULL
);
2197 g_free (item
->title
);
2198 item
->title
= g_strdup (title
);
2200 item
->modified
= time (NULL
);
2205 * g_bookmark_file_get_title:
2206 * @bookmark: a #GBookmarkFile
2207 * @uri: a valid URI or %NULL
2208 * @error: return location for a #GError, or %NULL
2210 * Returns the title of the bookmark for @uri.
2212 * If @uri is %NULL, the title of @bookmark is returned.
2214 * In the event the URI cannot be found, %NULL is returned and
2215 * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
2217 * Return value: a newly allocated string or %NULL if the specified
2218 * URI cannot be found.
2223 g_bookmark_file_get_title (GBookmarkFile
*bookmark
,
2229 g_return_val_if_fail (bookmark
!= NULL
, NULL
);
2232 return g_strdup (bookmark
->title
);
2234 item
= g_bookmark_file_lookup_item (bookmark
, uri
);
2237 g_set_error (error
, G_BOOKMARK_FILE_ERROR
,
2238 G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND
,
2239 _("No bookmark found for URI '%s'"),
2244 return g_strdup (item
->title
);
2248 * g_bookmark_file_set_description:
2249 * @bookmark: a #GBookmarkFile
2250 * @uri: a valid URI or %NULL
2251 * @description: a string
2253 * Sets @description as the description of the bookmark for @uri.
2255 * If @uri is %NULL, the description of @bookmark is set.
2257 * If a bookmark for @uri cannot be found then it is created.
2262 g_bookmark_file_set_description (GBookmarkFile
*bookmark
,
2264 const gchar
*description
)
2266 g_return_if_fail (bookmark
!= NULL
);
2270 g_free (bookmark
->description
);
2271 bookmark
->description
= g_strdup (description
);
2277 item
= g_bookmark_file_lookup_item (bookmark
, uri
);
2280 item
= bookmark_item_new (uri
);
2281 g_bookmark_file_add_item (bookmark
, item
, NULL
);
2284 g_free (item
->description
);
2285 item
->description
= g_strdup (description
);
2287 item
->modified
= time (NULL
);
2292 * g_bookmark_file_get_description:
2293 * @bookmark: a #GBookmarkFile
2295 * @error: return location for a #GError, or %NULL
2297 * Retrieves the description of the bookmark for @uri.
2299 * In the event the URI cannot be found, %NULL is returned and
2300 * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
2302 * Return value: a newly allocated string or %NULL if the specified
2303 * URI cannot be found.
2308 g_bookmark_file_get_description (GBookmarkFile
*bookmark
,
2314 g_return_val_if_fail (bookmark
!= NULL
, NULL
);
2317 return g_strdup (bookmark
->description
);
2319 item
= g_bookmark_file_lookup_item (bookmark
, uri
);
2322 g_set_error (error
, G_BOOKMARK_FILE_ERROR
,
2323 G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND
,
2324 _("No bookmark found for URI '%s'"),
2329 return g_strdup (item
->description
);
2333 * g_bookmark_file_set_mime_type:
2334 * @bookmark: a #GBookmarkFile
2336 * @mime_type: a MIME type
2338 * Sets @mime_type as the MIME type of the bookmark for @uri.
2340 * If a bookmark for @uri cannot be found then it is created.
2345 g_bookmark_file_set_mime_type (GBookmarkFile
*bookmark
,
2347 const gchar
*mime_type
)
2351 g_return_if_fail (bookmark
!= NULL
);
2352 g_return_if_fail (uri
!= NULL
);
2353 g_return_if_fail (mime_type
!= NULL
);
2355 item
= g_bookmark_file_lookup_item (bookmark
, uri
);
2358 item
= bookmark_item_new (uri
);
2359 g_bookmark_file_add_item (bookmark
, item
, NULL
);
2362 if (!item
->metadata
)
2363 item
->metadata
= bookmark_metadata_new ();
2365 g_free (item
->metadata
->mime_type
);
2367 item
->metadata
->mime_type
= g_strdup (mime_type
);
2368 item
->modified
= time (NULL
);
2372 * g_bookmark_file_get_mime_type:
2373 * @bookmark: a #GBookmarkFile
2375 * @error: return location for a #GError, or %NULL
2377 * Retrieves the MIME type of the resource pointed by @uri.
2379 * In the event the URI cannot be found, %NULL is returned and
2380 * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. In the
2381 * event that the MIME type cannot be found, %NULL is returned and
2382 * @error is set to #G_BOOKMARK_FILE_ERROR_INVALID_VALUE.
2384 * Return value: a newly allocated string or %NULL if the specified
2385 * URI cannot be found.
2390 g_bookmark_file_get_mime_type (GBookmarkFile
*bookmark
,
2396 g_return_val_if_fail (bookmark
!= NULL
, NULL
);
2397 g_return_val_if_fail (uri
!= NULL
, NULL
);
2399 item
= g_bookmark_file_lookup_item (bookmark
, uri
);
2402 g_set_error (error
, G_BOOKMARK_FILE_ERROR
,
2403 G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND
,
2404 _("No bookmark found for URI '%s'"),
2409 if (!item
->metadata
)
2411 g_set_error (error
, G_BOOKMARK_FILE_ERROR
,
2412 G_BOOKMARK_FILE_ERROR_INVALID_VALUE
,
2413 _("No MIME type defined in the bookmark for URI '%s'"),
2418 return g_strdup (item
->metadata
->mime_type
);
2422 * g_bookmark_file_set_is_private:
2423 * @bookmark: a #GBookmarkFile
2425 * @is_private: %TRUE if the bookmark should be marked as private
2427 * Sets the private flag of the bookmark for @uri.
2429 * If a bookmark for @uri cannot be found then it is created.
2434 g_bookmark_file_set_is_private (GBookmarkFile
*bookmark
,
2436 gboolean is_private
)
2440 g_return_if_fail (bookmark
!= NULL
);
2441 g_return_if_fail (uri
!= NULL
);
2443 item
= g_bookmark_file_lookup_item (bookmark
, uri
);
2446 item
= bookmark_item_new (uri
);
2447 g_bookmark_file_add_item (bookmark
, item
, NULL
);
2450 if (!item
->metadata
)
2451 item
->metadata
= bookmark_metadata_new ();
2453 item
->metadata
->is_private
= (is_private
== TRUE
);
2454 item
->modified
= time (NULL
);
2458 * g_bookmark_file_get_is_private:
2459 * @bookmark: a #GBookmarkFile
2461 * @error: return location for a #GError, or %NULL
2463 * Gets whether the private flag of the bookmark for @uri is set.
2465 * In the event the URI cannot be found, %FALSE is returned and
2466 * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. In the
2467 * event that the private flag cannot be found, %FALSE is returned and
2468 * @error is set to #G_BOOKMARK_FILE_ERROR_INVALID_VALUE.
2470 * Return value: %TRUE if the private flag is set, %FALSE otherwise.
2475 g_bookmark_file_get_is_private (GBookmarkFile
*bookmark
,
2481 g_return_val_if_fail (bookmark
!= NULL
, FALSE
);
2482 g_return_val_if_fail (uri
!= NULL
, FALSE
);
2484 item
= g_bookmark_file_lookup_item (bookmark
, uri
);
2487 g_set_error (error
, G_BOOKMARK_FILE_ERROR
,
2488 G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND
,
2489 _("No bookmark found for URI '%s'"),
2494 if (!item
->metadata
)
2496 g_set_error (error
, G_BOOKMARK_FILE_ERROR
,
2497 G_BOOKMARK_FILE_ERROR_INVALID_VALUE
,
2498 _("No private flag has been defined in bookmark for URI '%s'"),
2503 return item
->metadata
->is_private
;
2507 * g_bookmark_file_set_added:
2508 * @bookmark: a #GBookmarkFile
2510 * @added: a timestamp or -1 to use the current time
2512 * Sets the time the bookmark for @uri was added into @bookmark.
2514 * If no bookmark for @uri is found then it is created.
2519 g_bookmark_file_set_added (GBookmarkFile
*bookmark
,
2525 g_return_if_fail (bookmark
!= NULL
);
2526 g_return_if_fail (uri
!= NULL
);
2528 item
= g_bookmark_file_lookup_item (bookmark
, uri
);
2531 item
= bookmark_item_new (uri
);
2532 g_bookmark_file_add_item (bookmark
, item
, NULL
);
2535 if (added
== (time_t) -1)
2538 item
->added
= added
;
2539 item
->modified
= added
;
2543 * g_bookmark_file_get_added:
2544 * @bookmark: a #GBookmarkFile
2546 * @error: return location for a #GError, or %NULL
2548 * Gets the time the bookmark for @uri was added to @bookmark
2550 * In the event the URI cannot be found, -1 is returned and
2551 * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
2553 * Return value: a timestamp
2558 g_bookmark_file_get_added (GBookmarkFile
*bookmark
,
2564 g_return_val_if_fail (bookmark
!= NULL
, (time_t) -1);
2565 g_return_val_if_fail (uri
!= NULL
, (time_t) -1);
2567 item
= g_bookmark_file_lookup_item (bookmark
, uri
);
2570 g_set_error (error
, G_BOOKMARK_FILE_ERROR
,
2571 G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND
,
2572 _("No bookmark found for URI '%s'"),
2581 * g_bookmark_file_set_modified:
2582 * @bookmark: a #GBookmarkFile
2584 * @modified: a timestamp or -1 to use the current time
2586 * Sets the last time the bookmark for @uri was last modified.
2588 * If no bookmark for @uri is found then it is created.
2590 * The "modified" time should only be set when the bookmark's meta-data
2591 * was actually changed. Every function of #GBookmarkFile that
2592 * modifies a bookmark also changes the modification time, except for
2593 * g_bookmark_file_set_visited().
2598 g_bookmark_file_set_modified (GBookmarkFile
*bookmark
,
2604 g_return_if_fail (bookmark
!= NULL
);
2605 g_return_if_fail (uri
!= NULL
);
2607 item
= g_bookmark_file_lookup_item (bookmark
, uri
);
2610 item
= bookmark_item_new (uri
);
2611 g_bookmark_file_add_item (bookmark
, item
, NULL
);
2614 if (modified
== (time_t) -1)
2617 item
->modified
= modified
;
2621 * g_bookmark_file_get_modified:
2622 * @bookmark: a #GBookmarkFile
2624 * @error: return location for a #GError, or %NULL
2626 * Gets the time when the bookmark for @uri was last modified.
2628 * In the event the URI cannot be found, -1 is returned and
2629 * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
2631 * Return value: a timestamp
2636 g_bookmark_file_get_modified (GBookmarkFile
*bookmark
,
2642 g_return_val_if_fail (bookmark
!= NULL
, (time_t) -1);
2643 g_return_val_if_fail (uri
!= NULL
, (time_t) -1);
2645 item
= g_bookmark_file_lookup_item (bookmark
, uri
);
2648 g_set_error (error
, G_BOOKMARK_FILE_ERROR
,
2649 G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND
,
2650 _("No bookmark found for URI '%s'"),
2655 return item
->modified
;
2659 * g_bookmark_file_set_visited:
2660 * @bookmark: a #GBookmarkFile
2662 * @visited: a timestamp or -1 to use the current time
2664 * Sets the time the bookmark for @uri was last visited.
2666 * If no bookmark for @uri is found then it is created.
2668 * The "visited" time should only be set if the bookmark was launched,
2669 * either using the command line retrieved by g_bookmark_file_get_app_info()
2670 * or by the default application for the bookmark's MIME type, retrieved
2671 * using g_bookmark_file_get_mime_type(). Changing the "visited" time
2672 * does not affect the "modified" time.
2677 g_bookmark_file_set_visited (GBookmarkFile
*bookmark
,
2683 g_return_if_fail (bookmark
!= NULL
);
2684 g_return_if_fail (uri
!= NULL
);
2686 item
= g_bookmark_file_lookup_item (bookmark
, uri
);
2689 item
= bookmark_item_new (uri
);
2690 g_bookmark_file_add_item (bookmark
, item
, NULL
);
2693 if (visited
== (time_t) -1)
2696 item
->visited
= visited
;
2700 * g_bookmark_file_get_visited:
2701 * @bookmark: a #GBookmarkFile
2703 * @error: return location for a #GError, or %NULL
2705 * Gets the time the bookmark for @uri was last visited.
2707 * In the event the URI cannot be found, -1 is returned and
2708 * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
2710 * Return value: a timestamp.
2715 g_bookmark_file_get_visited (GBookmarkFile
*bookmark
,
2721 g_return_val_if_fail (bookmark
!= NULL
, (time_t) -1);
2722 g_return_val_if_fail (uri
!= NULL
, (time_t) -1);
2724 item
= g_bookmark_file_lookup_item (bookmark
, uri
);
2727 g_set_error (error
, G_BOOKMARK_FILE_ERROR
,
2728 G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND
,
2729 _("No bookmark found for URI '%s'"),
2734 return item
->visited
;
2738 * g_bookmark_file_has_group:
2739 * @bookmark: a #GBookmarkFile
2741 * @group: the group name to be searched
2742 * @error: return location for a #GError, or %NULL
2744 * Checks whether @group appears in the list of groups to which
2745 * the bookmark for @uri belongs to.
2747 * In the event the URI cannot be found, %FALSE is returned and
2748 * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
2750 * Return value: %TRUE if @group was found.
2755 g_bookmark_file_has_group (GBookmarkFile
*bookmark
,
2763 g_return_val_if_fail (bookmark
!= NULL
, FALSE
);
2764 g_return_val_if_fail (uri
!= NULL
, FALSE
);
2766 item
= g_bookmark_file_lookup_item (bookmark
, uri
);
2769 g_set_error (error
, G_BOOKMARK_FILE_ERROR
,
2770 G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND
,
2771 _("No bookmark found for URI '%s'"),
2776 if (!item
->metadata
)
2779 for (l
= item
->metadata
->groups
; l
!= NULL
; l
= l
->next
)
2781 if (strcmp (l
->data
, group
) == 0)
2790 * g_bookmark_file_add_group:
2791 * @bookmark: a #GBookmarkFile
2793 * @group: the group name to be added
2795 * Adds @group to the list of groups to which the bookmark for @uri
2798 * If no bookmark for @uri is found then it is created.
2803 g_bookmark_file_add_group (GBookmarkFile
*bookmark
,
2809 g_return_if_fail (bookmark
!= NULL
);
2810 g_return_if_fail (uri
!= NULL
);
2811 g_return_if_fail (group
!= NULL
&& group
[0] != '\0');
2813 item
= g_bookmark_file_lookup_item (bookmark
, uri
);
2816 item
= bookmark_item_new (uri
);
2817 g_bookmark_file_add_item (bookmark
, item
, NULL
);
2820 if (!item
->metadata
)
2821 item
->metadata
= bookmark_metadata_new ();
2823 if (!g_bookmark_file_has_group (bookmark
, uri
, group
, NULL
))
2825 item
->metadata
->groups
= g_list_prepend (item
->metadata
->groups
,
2828 item
->modified
= time (NULL
);
2833 * g_bookmark_file_remove_group:
2834 * @bookmark: a #GBookmarkFile
2836 * @group: the group name to be removed
2837 * @error: return location for a #GError, or %NULL
2839 * Removes @group from the list of groups to which the bookmark
2840 * for @uri belongs to.
2842 * In the event the URI cannot be found, %FALSE is returned and
2843 * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
2844 * In the event no group was defined, %FALSE is returned and
2845 * @error is set to #G_BOOKMARK_FILE_ERROR_INVALID_VALUE.
2847 * Return value: %TRUE if @group was successfully removed.
2852 g_bookmark_file_remove_group (GBookmarkFile
*bookmark
,
2860 g_return_val_if_fail (bookmark
!= NULL
, FALSE
);
2861 g_return_val_if_fail (uri
!= NULL
, FALSE
);
2863 item
= g_bookmark_file_lookup_item (bookmark
, uri
);
2866 g_set_error (error
, G_BOOKMARK_FILE_ERROR
,
2867 G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND
,
2868 _("No bookmark found for URI '%s'"),
2873 if (!item
->metadata
)
2875 g_set_error (error
, G_BOOKMARK_FILE_ERROR
,
2876 G_BOOKMARK_FILE_ERROR_INVALID_VALUE
,
2877 _("No groups set in bookmark for URI '%s'"),
2882 for (l
= item
->metadata
->groups
; l
!= NULL
; l
= l
->next
)
2884 if (strcmp (l
->data
, group
) == 0)
2886 item
->metadata
->groups
= g_list_remove_link (item
->metadata
->groups
, l
);
2890 item
->modified
= time (NULL
);
2900 * g_bookmark_file_set_groups:
2901 * @bookmark: a #GBookmarkFile
2902 * @uri: an item's URI
2903 * @groups: an array of group names, or %NULL to remove all groups
2904 * @length: number of group name values in @groups
2906 * Sets a list of group names for the item with URI @uri. Each previously
2907 * set group name list is removed.
2909 * If @uri cannot be found then an item for it is created.
2914 g_bookmark_file_set_groups (GBookmarkFile
*bookmark
,
2916 const gchar
**groups
,
2922 g_return_if_fail (bookmark
!= NULL
);
2923 g_return_if_fail (uri
!= NULL
);
2924 g_return_if_fail (groups
!= NULL
);
2926 item
= g_bookmark_file_lookup_item (bookmark
, uri
);
2929 item
= bookmark_item_new (uri
);
2930 g_bookmark_file_add_item (bookmark
, item
, NULL
);
2933 if (!item
->metadata
)
2934 item
->metadata
= bookmark_metadata_new ();
2936 if (item
->metadata
->groups
!= NULL
)
2938 g_list_foreach (item
->metadata
->groups
,
2941 g_list_free (item
->metadata
->groups
);
2942 item
->metadata
->groups
= NULL
;
2947 for (i
= 0; groups
[i
] != NULL
&& i
< length
; i
++)
2948 item
->metadata
->groups
= g_list_append (item
->metadata
->groups
,
2949 g_strdup (groups
[i
]));
2952 item
->modified
= time (NULL
);
2956 * g_bookmark_file_get_groups:
2957 * @bookmark: a #GBookmarkFile
2959 * @length: return location for the length of the returned string, or %NULL
2960 * @error: return location for a #GError, or %NULL
2962 * Retrieves the list of group names of the bookmark for @uri.
2964 * In the event the URI cannot be found, %NULL is returned and
2965 * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
2967 * The returned array is %NULL terminated, so @length may optionally
2970 * Return value: a newly allocated %NULL-terminated array of group names.
2971 * Use g_strfreev() to free it.
2976 g_bookmark_file_get_groups (GBookmarkFile
*bookmark
,
2986 g_return_val_if_fail (bookmark
!= NULL
, NULL
);
2987 g_return_val_if_fail (uri
!= NULL
, NULL
);
2989 item
= g_bookmark_file_lookup_item (bookmark
, uri
);
2992 g_set_error (error
, G_BOOKMARK_FILE_ERROR
,
2993 G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND
,
2994 _("No bookmark found for URI '%s'"),
2999 if (!item
->metadata
)
3007 len
= g_list_length (item
->metadata
->groups
);
3008 retval
= g_new0 (gchar
*, len
+ 1);
3009 for (l
= g_list_last (item
->metadata
->groups
), i
= 0;
3013 gchar
*group_name
= (gchar
*) l
->data
;
3015 g_warn_if_fail (group_name
!= NULL
);
3017 retval
[i
++] = g_strdup (group_name
);
3028 * g_bookmark_file_add_application:
3029 * @bookmark: a #GBookmarkFile
3031 * @name: the name of the application registering the bookmark
3033 * @exec: command line to be used to launch the bookmark or %NULL
3035 * Adds the application with @name and @exec to the list of
3036 * applications that have registered a bookmark for @uri into
3039 * Every bookmark inside a #GBookmarkFile must have at least an
3040 * application registered. Each application must provide a name, a
3041 * command line useful for launching the bookmark, the number of times
3042 * the bookmark has been registered by the application and the last
3043 * time the application registered this bookmark.
3045 * If @name is %NULL, the name of the application will be the
3046 * same returned by g_get_application_name(); if @exec is %NULL, the
3047 * command line will be a composition of the program name as
3048 * returned by g_get_prgname() and the "%u" modifier, which will be
3049 * expanded to the bookmark's URI.
3051 * This function will automatically take care of updating the
3052 * registrations count and timestamping in case an application
3053 * with the same @name had already registered a bookmark for
3054 * @uri inside @bookmark.
3056 * If no bookmark for @uri is found, one is created.
3061 g_bookmark_file_add_application (GBookmarkFile
*bookmark
,
3067 gchar
*app_name
, *app_exec
;
3069 g_return_if_fail (bookmark
!= NULL
);
3070 g_return_if_fail (uri
!= NULL
);
3072 item
= g_bookmark_file_lookup_item (bookmark
, uri
);
3075 item
= bookmark_item_new (uri
);
3076 g_bookmark_file_add_item (bookmark
, item
, NULL
);
3079 if (name
&& name
[0] != '\0')
3080 app_name
= g_strdup (name
);
3082 app_name
= g_strdup (g_get_application_name ());
3084 if (exec
&& exec
[0] != '\0')
3085 app_exec
= g_strdup (exec
);
3087 app_exec
= g_strjoin (" ", g_get_prgname(), "%u", NULL
);
3089 g_bookmark_file_set_app_info (bookmark
, uri
,
3101 * g_bookmark_file_remove_application:
3102 * @bookmark: a #GBookmarkFile
3104 * @name: the name of the application
3105 * @error: return location for a #GError or %NULL
3107 * Removes application registered with @name from the list of applications
3108 * that have registered a bookmark for @uri inside @bookmark.
3110 * In the event the URI cannot be found, %FALSE is returned and
3111 * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
3112 * In the event that no application with name @app_name has registered
3113 * a bookmark for @uri, %FALSE is returned and error is set to
3114 * #G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED.
3116 * Return value: %TRUE if the application was successfully removed.
3121 g_bookmark_file_remove_application (GBookmarkFile
*bookmark
,
3129 g_return_val_if_fail (bookmark
!= NULL
, FALSE
);
3130 g_return_val_if_fail (uri
!= NULL
, FALSE
);
3131 g_return_val_if_fail (name
!= NULL
, FALSE
);
3134 retval
= g_bookmark_file_set_app_info (bookmark
, uri
,
3142 g_propagate_error (error
, set_error
);
3151 * g_bookmark_file_has_application:
3152 * @bookmark: a #GBookmarkFile
3154 * @name: the name of the application
3155 * @error: return location for a #GError or %NULL
3157 * Checks whether the bookmark for @uri inside @bookmark has been
3158 * registered by application @name.
3160 * In the event the URI cannot be found, %FALSE is returned and
3161 * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
3163 * Return value: %TRUE if the application @name was found
3168 g_bookmark_file_has_application (GBookmarkFile
*bookmark
,
3175 g_return_val_if_fail (bookmark
!= NULL
, FALSE
);
3176 g_return_val_if_fail (uri
!= NULL
, FALSE
);
3177 g_return_val_if_fail (name
!= NULL
, FALSE
);
3179 item
= g_bookmark_file_lookup_item (bookmark
, uri
);
3182 g_set_error (error
, G_BOOKMARK_FILE_ERROR
,
3183 G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND
,
3184 _("No bookmark found for URI '%s'"),
3189 return (NULL
!= bookmark_item_lookup_app_info (item
, name
));
3193 * g_bookmark_file_set_app_info:
3194 * @bookmark: a #GBookmarkFile
3196 * @name: an application's name
3197 * @exec: an application's command line
3198 * @count: the number of registrations done for this application
3199 * @stamp: the time of the last registration for this application
3200 * @error: return location for a #GError or %NULL
3202 * Sets the meta-data of application @name inside the list of
3203 * applications that have registered a bookmark for @uri inside
3206 * You should rarely use this function; use g_bookmark_file_add_application()
3207 * and g_bookmark_file_remove_application() instead.
3209 * @name can be any UTF-8 encoded string used to identify an
3211 * @exec can have one of these two modifiers: "%f", which will
3212 * be expanded as the local file name retrieved from the bookmark's
3213 * URI; "%u", which will be expanded as the bookmark's URI.
3214 * The expansion is done automatically when retrieving the stored
3215 * command line using the g_bookmark_file_get_app_info() function.
3216 * @count is the number of times the application has registered the
3217 * bookmark; if is < 0, the current registration count will be increased
3218 * by one, if is 0, the application with @name will be removed from
3219 * the list of registered applications.
3220 * @stamp is the Unix time of the last registration; if it is -1, the
3221 * current time will be used.
3223 * If you try to remove an application by setting its registration count to
3224 * zero, and no bookmark for @uri is found, %FALSE is returned and
3225 * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND; similarly,
3226 * in the event that no application @name has registered a bookmark
3227 * for @uri, %FALSE is returned and error is set to
3228 * #G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED. Otherwise, if no bookmark
3229 * for @uri is found, one is created.
3231 * Return value: %TRUE if the application's meta-data was successfully
3237 g_bookmark_file_set_app_info (GBookmarkFile
*bookmark
,
3246 BookmarkAppInfo
*ai
;
3248 g_return_val_if_fail (bookmark
!= NULL
, FALSE
);
3249 g_return_val_if_fail (uri
!= NULL
, FALSE
);
3250 g_return_val_if_fail (name
!= NULL
, FALSE
);
3251 g_return_val_if_fail (exec
!= NULL
, FALSE
);
3253 item
= g_bookmark_file_lookup_item (bookmark
, uri
);
3258 g_set_error (error
, G_BOOKMARK_FILE_ERROR
,
3259 G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND
,
3260 _("No bookmark found for URI '%s'"),
3266 item
= bookmark_item_new (uri
);
3267 g_bookmark_file_add_item (bookmark
, item
, NULL
);
3271 ai
= bookmark_item_lookup_app_info (item
, name
);
3276 g_set_error (error
, G_BOOKMARK_FILE_ERROR
,
3277 G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED
,
3278 _("No application with name '%s' registered a bookmark for '%s'"),
3285 ai
= bookmark_app_info_new (name
);
3287 item
->metadata
->applications
= g_list_prepend (item
->metadata
->applications
, ai
);
3288 g_hash_table_replace (item
->metadata
->apps_by_name
, ai
->name
, ai
);
3294 item
->metadata
->applications
= g_list_remove (item
->metadata
->applications
, ai
);
3295 g_hash_table_remove (item
->metadata
->apps_by_name
, ai
->name
);
3296 bookmark_app_info_free (ai
);
3298 item
->modified
= time (NULL
);
3307 if (stamp
!= (time_t) -1)
3310 ai
->stamp
= time (NULL
);
3312 if (exec
&& exec
[0] != '\0')
3315 ai
->exec
= g_shell_quote (exec
);
3318 item
->modified
= time (NULL
);
3323 /* expands the application's command line */
3325 expand_exec_line (const gchar
*exec_fmt
,
3331 exec
= g_string_sized_new (512);
3332 while ((ch
= *exec_fmt
++) != '\0')
3336 exec
= g_string_append_c (exec
, ch
);
3347 g_string_append (exec
, uri
);
3352 gchar
*file
= g_filename_from_uri (uri
, NULL
, NULL
);
3355 g_string_append (exec
, file
);
3360 g_string_free (exec
, TRUE
);
3367 exec
= g_string_append_c (exec
, ch
);
3373 return g_string_free (exec
, FALSE
);
3377 * g_bookmark_file_get_app_info:
3378 * @bookmark: a #GBookmarkFile
3380 * @name: an application's name
3381 * @exec: location for the command line of the application, or %NULL
3382 * @count: return location for the registration count, or %NULL
3383 * @stamp: return location for the last registration time, or %NULL
3384 * @error: return location for a #GError, or %NULL
3386 * Gets the registration informations of @app_name for the bookmark for
3387 * @uri. See g_bookmark_file_set_app_info() for more informations about
3388 * the returned data.
3390 * The string returned in @app_exec must be freed.
3392 * In the event the URI cannot be found, %FALSE is returned and
3393 * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. In the
3394 * event that no application with name @app_name has registered a bookmark
3395 * for @uri, %FALSE is returned and error is set to
3396 * #G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED. In the event that unquoting
3397 * the command line fails, an error of the #G_SHELL_ERROR domain is
3398 * set and %FALSE is returned.
3400 * Return value: %TRUE on success.
3405 g_bookmark_file_get_app_info (GBookmarkFile
*bookmark
,
3414 BookmarkAppInfo
*ai
;
3416 g_return_val_if_fail (bookmark
!= NULL
, FALSE
);
3417 g_return_val_if_fail (uri
!= NULL
, FALSE
);
3418 g_return_val_if_fail (name
!= NULL
, FALSE
);
3420 item
= g_bookmark_file_lookup_item (bookmark
, uri
);
3423 g_set_error (error
, G_BOOKMARK_FILE_ERROR
,
3424 G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND
,
3425 _("No bookmark found for URI '%s'"),
3430 ai
= bookmark_item_lookup_app_info (item
, name
);
3433 g_set_error (error
, G_BOOKMARK_FILE_ERROR
,
3434 G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED
,
3435 _("No application with name '%s' registered a bookmark for '%s'"),
3443 GError
*unquote_error
= NULL
;
3444 gchar
*command_line
;
3446 command_line
= g_shell_unquote (ai
->exec
, &unquote_error
);
3449 g_propagate_error (error
, unquote_error
);
3453 *exec
= expand_exec_line (command_line
, uri
);
3456 g_set_error (error
, G_BOOKMARK_FILE_ERROR
,
3457 G_BOOKMARK_FILE_ERROR_INVALID_URI
,
3458 _("Failed to expand exec line '%s' with URI '%s'"),
3460 g_free (command_line
);
3465 g_free (command_line
);
3478 * g_bookmark_file_get_applications:
3479 * @bookmark: a #GBookmarkFile
3481 * @length: return location of the length of the returned list, or %NULL
3482 * @error: return location for a #GError, or %NULL
3484 * Retrieves the names of the applications that have registered the
3485 * bookmark for @uri.
3487 * In the event the URI cannot be found, %NULL is returned and
3488 * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
3490 * Return value: a newly allocated %NULL-terminated array of strings.
3491 * Use g_strfreev() to free it.
3496 g_bookmark_file_get_applications (GBookmarkFile
*bookmark
,
3506 g_return_val_if_fail (bookmark
!= NULL
, NULL
);
3507 g_return_val_if_fail (uri
!= NULL
, NULL
);
3509 item
= g_bookmark_file_lookup_item (bookmark
, uri
);
3512 g_set_error (error
, G_BOOKMARK_FILE_ERROR
,
3513 G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND
,
3514 _("No bookmark found for URI '%s'"),
3519 if (!item
->metadata
)
3527 n_apps
= g_list_length (item
->metadata
->applications
);
3528 apps
= g_new0 (gchar
*, n_apps
+ 1);
3530 for (l
= g_list_last (item
->metadata
->applications
), i
= 0;
3534 BookmarkAppInfo
*ai
;
3536 ai
= (BookmarkAppInfo
*) l
->data
;
3538 g_warn_if_fail (ai
!= NULL
);
3539 g_warn_if_fail (ai
->name
!= NULL
);
3541 apps
[i
++] = g_strdup (ai
->name
);
3552 * g_bookmark_file_get_size:
3553 * @bookmark: a #GBookmarkFile
3555 * Gets the number of bookmarks inside @bookmark.
3557 * Return value: the number of bookmarks
3562 g_bookmark_file_get_size (GBookmarkFile
*bookmark
)
3564 g_return_val_if_fail (bookmark
!= NULL
, 0);
3566 return g_list_length (bookmark
->items
);
3570 * g_bookmark_file_move_item:
3571 * @bookmark: a #GBookmarkFile
3572 * @old_uri: a valid URI
3573 * @new_uri: a valid URI, or %NULL
3574 * @error: return location for a #GError or %NULL
3576 * Changes the URI of a bookmark item from @old_uri to @new_uri. Any
3577 * existing bookmark for @new_uri will be overwritten. If @new_uri is
3578 * %NULL, then the bookmark is removed.
3580 * In the event the URI cannot be found, %FALSE is returned and
3581 * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
3583 * Return value: %TRUE if the URI was successfully changed
3588 g_bookmark_file_move_item (GBookmarkFile
*bookmark
,
3589 const gchar
*old_uri
,
3590 const gchar
*new_uri
,
3594 GError
*remove_error
;
3596 g_return_val_if_fail (bookmark
!= NULL
, FALSE
);
3597 g_return_val_if_fail (old_uri
!= NULL
, FALSE
);
3599 item
= g_bookmark_file_lookup_item (bookmark
, old_uri
);
3602 g_set_error (error
, G_BOOKMARK_FILE_ERROR
,
3603 G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND
,
3604 _("No bookmark found for URI '%s'"),
3609 if (new_uri
&& new_uri
[0] != '\0')
3611 if (g_bookmark_file_has_item (bookmark
, new_uri
))
3613 remove_error
= NULL
;
3614 g_bookmark_file_remove_item (bookmark
, new_uri
, &remove_error
);
3617 g_propagate_error (error
, remove_error
);
3623 g_hash_table_steal (bookmark
->items_by_uri
, item
->uri
);
3626 item
->uri
= g_strdup (new_uri
);
3627 item
->modified
= time (NULL
);
3629 g_hash_table_replace (bookmark
->items_by_uri
, item
->uri
, item
);
3635 remove_error
= NULL
;
3636 g_bookmark_file_remove_item (bookmark
, old_uri
, &remove_error
);
3639 g_propagate_error (error
, remove_error
);
3649 * g_bookmark_file_set_icon:
3650 * @bookmark: a #GBookmarkFile
3652 * @href: the URI of the icon for the bookmark, or %NULL
3653 * @mime_type: the MIME type of the icon for the bookmark
3655 * Sets the icon for the bookmark for @uri. If @href is %NULL, unsets
3656 * the currently set icon. @href can either be a full URL for the icon
3657 * file or the icon name following the Icon Naming specification.
3659 * If no bookmark for @uri is found one is created.
3664 g_bookmark_file_set_icon (GBookmarkFile
*bookmark
,
3667 const gchar
*mime_type
)
3671 g_return_if_fail (bookmark
!= NULL
);
3672 g_return_if_fail (uri
!= NULL
);
3674 item
= g_bookmark_file_lookup_item (bookmark
, uri
);
3677 item
= bookmark_item_new (uri
);
3678 g_bookmark_file_add_item (bookmark
, item
, NULL
);
3681 if (!item
->metadata
)
3682 item
->metadata
= bookmark_metadata_new ();
3684 g_free (item
->metadata
->icon_href
);
3685 g_free (item
->metadata
->icon_mime
);
3687 item
->metadata
->icon_href
= g_strdup (href
);
3689 if (mime_type
&& mime_type
[0] != '\0')
3690 item
->metadata
->icon_mime
= g_strdup (mime_type
);
3692 item
->metadata
->icon_mime
= g_strdup ("application/octet-stream");
3694 item
->modified
= time (NULL
);
3698 * g_bookmark_file_get_icon:
3699 * @bookmark: a #GBookmarkFile
3701 * @href: return location for the icon's location or %NULL
3702 * @mime_type: return location for the icon's MIME type or %NULL
3703 * @error: return location for a #GError or %NULL
3705 * Gets the icon of the bookmark for @uri.
3707 * In the event the URI cannot be found, %FALSE is returned and
3708 * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
3710 * Return value: %TRUE if the icon for the bookmark for the URI was found.
3711 * You should free the returned strings.
3716 g_bookmark_file_get_icon (GBookmarkFile
*bookmark
,
3724 g_return_val_if_fail (bookmark
!= NULL
, FALSE
);
3725 g_return_val_if_fail (uri
!= NULL
, FALSE
);
3727 item
= g_bookmark_file_lookup_item (bookmark
, uri
);
3730 g_set_error (error
, G_BOOKMARK_FILE_ERROR
,
3731 G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND
,
3732 _("No bookmark found for URI '%s'"),
3737 if ((!item
->metadata
) || (!item
->metadata
->icon_href
))
3741 *href
= g_strdup (item
->metadata
->icon_href
);
3744 *mime_type
= g_strdup (item
->metadata
->icon_mime
);