#include "gtimer.h"
#include "gutils.h"
-#include "galias.h"
+
+/**
+ * SECTION:bookmarkfile
+ * @title: Bookmark file parser
+ * @short_description: parses files containing bookmarks
+ *
+ * GBookmarkFile lets you parse, edit or create files containing bookmarks
+ * to URI, along with some meta-data about the resource pointed by the URI
+ * like its MIME type, the application that is registering the bookmark and
+ * the icon that should be used to represent the bookmark. The data is stored
+ * using the
+ * <ulink url="http://www.gnome.org/~ebassi/bookmark-spec">Desktop Bookmark
+ * Specification</ulink>.
+ *
+ * The syntax of the bookmark files is described in detail inside the Desktop
+ * Bookmark Specification, here is a quick summary: bookmark files use a
+ * sub-class of the <ulink url="">XML Bookmark Exchange Language</ulink>
+ * specification, consisting of valid UTF-8 encoded XML, under the
+ * <literal>xbel</literal> root element; each bookmark is stored inside a
+ * <literal>bookmark</literal> element, using its URI: no relative paths can
+ * be used inside a bookmark file. The bookmark may have a user defined title
+ * and description, to be used instead of the URI. Under the
+ * <literal>metadata</literal> element, with its <literal>owner</literal>
+ * attribute set to <literal>http://freedesktop.org</literal>, is stored the
+ * meta-data about a resource pointed by its URI. The meta-data consists of
+ * the resource's MIME type; the applications that have registered a bookmark;
+ * the groups to which a bookmark belongs to; a visibility flag, used to set
+ * the bookmark as "private" to the applications and groups that has it
+ * registered; the URI and MIME type of an icon, to be used when displaying
+ * the bookmark inside a GUI.
+ * |[<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>]|
+ *
+ * A bookmark file might contain more than one bookmark; each bookmark
+ * is accessed through its URI.
+ *
+ * The important caveat of bookmark files is that when you add a new
+ * bookmark you must also add the application that is registering it, using
+ * g_bookmark_file_add_application() or g_bookmark_file_set_app_info().
+ * If a bookmark has no applications then it won't be dumped when creating
+ * the on disk representation, using g_bookmark_file_to_data() or
+ * g_bookmark_file_to_file().
+ *
+ * The #GBookmarkFile parser was added in GLib 2.12.
+ */
/* XBEL 1.0 standard entities */
#define XBEL_VERSION "1.0"
g_free (metadata->mime_type);
- if (metadata->groups)
- {
- g_list_foreach (metadata->groups,
- (GFunc) g_free,
- NULL);
- g_list_free (metadata->groups);
- }
-
- if (metadata->applications)
- {
- g_list_foreach (metadata->applications,
- (GFunc) bookmark_app_info_free,
- NULL);
- g_list_free (metadata->applications);
- }
+ g_list_free_full (metadata->groups, g_free);
+ g_list_free_full (metadata->applications, (GDestroyNotify) bookmark_app_info_free);
g_hash_table_destroy (metadata->apps_by_name);
g_free (bookmark->title);
g_free (bookmark->description);
- if (bookmark->items)
- {
- g_list_foreach (bookmark->items,
- (GFunc) bookmark_item_free,
- NULL);
- g_list_free (bookmark->items);
-
- bookmark->items = NULL;
- }
+ g_list_free_full (bookmark->items, (GDestroyNotify) bookmark_item_free);
+ bookmark->items = NULL;
if (bookmark->items_by_uri)
{
static gboolean
g_bookmark_file_parse (GBookmarkFile *bookmark,
- const gchar *buffer,
- gsize length,
- GError **error)
+ const gchar *buffer,
+ gsize length,
+ GError **error)
{
GMarkupParseContext *context;
ParseData *parse_data;
if (!buffer)
return FALSE;
+
+ parse_error = NULL;
+ end_error = NULL;
if (length == (gsize) -1)
length = strlen (buffer);
parse_data,
(GDestroyNotify) parse_data_free);
- parse_error = NULL;
retval = g_markup_parse_context_parse (context,
buffer,
length,
&parse_error);
if (!retval)
- {
- g_propagate_error (error, parse_error);
-
- return FALSE;
- }
-
- end_error = NULL;
- retval = g_markup_parse_context_end_parse (context, &end_error);
- if (!retval)
- {
- g_propagate_error (error, end_error);
-
- return FALSE;
- }
-
+ g_propagate_error (error, parse_error);
+ else
+ {
+ retval = g_markup_parse_context_end_parse (context, &end_error);
+ if (!retval)
+ g_propagate_error (error, end_error);
+ }
+
g_markup_parse_context_free (context);
-
- return TRUE;
+
+ return retval;
}
static gchar *
gboolean retval;
g_return_val_if_fail (bookmark != NULL, FALSE);
- g_return_val_if_fail (data != NULL, FALSE);
- g_return_val_if_fail (length != 0, FALSE);
-
+
if (length == (gsize) -1)
length = strlen (data);
g_bookmark_file_clear (bookmark);
g_bookmark_file_init (bookmark);
}
-
+
parse_error = NULL;
retval = g_bookmark_file_parse (bookmark, data, length, &parse_error);
+
if (!retval)
- {
- g_propagate_error (error, parse_error);
-
- return FALSE;
- }
-
- return TRUE;
+ g_propagate_error (error, parse_error);
+
+ return retval;
}
/**
* g_bookmark_file_load_from_data_dirs:
* @bookmark: a #GBookmarkFile
* @file: a relative path to a filename to open and parse
- * @full_path: return location for a string containing the full path
+ * @full_path: (allow-none): return location for a string containing the full path
* of the file, or %NULL
* @error: return location for a #GError, or %NULL
*
* @full_path. If the file could not be loaded then an %error is
* set to either a #GFileError or #GBookmarkFileError.
*
- * Return value: %TRUE if a key file could be loaded, %FALSE othewise
+ * Return value: %TRUE if a key file could be loaded, %FALSE otherwise
*
* Since: 2.12
*/
/**
* g_bookmark_file_to_data:
* @bookmark: a #GBookmarkFile
- * @length: return location for the length of the returned string, or %NULL
+ * @length: (allow-none): return location for the length of the returned string, or %NULL
* @error: return location for a #GError, or %NULL
*
* This function outputs @bookmark as a string.
/**
* g_bookmark_file_get_uris:
* @bookmark: a #GBookmarkFile
- * @length: return location for the number of returned URIs, or %NULL
+ * @length: (allow-none): return location for the number of returned URIs, or %NULL
*
* Returns all URIs of the bookmarks in the bookmark file @bookmark.
* The array of returned URIs will be %NULL-terminated, so @length may
/**
* g_bookmark_file_set_title:
* @bookmark: a #GBookmarkFile
- * @uri: a valid URI or %NULL
+ * @uri: (allow-none): a valid URI or %NULL
* @title: a UTF-8 encoded string
*
* Sets @title as the title of the bookmark for @uri inside the
/**
* g_bookmark_file_get_title:
* @bookmark: a #GBookmarkFile
- * @uri: a valid URI or %NULL
+ * @uri: (allow-none): a valid URI or %NULL
* @error: return location for a #GError, or %NULL
*
* Returns the title of the bookmark for @uri.
/**
* g_bookmark_file_set_description:
* @bookmark: a #GBookmarkFile
- * @uri: a valid URI or %NULL
+ * @uri: (allow-none): a valid URI or %NULL
* @description: a string
*
* Sets @description as the description of the bookmark for @uri.
* g_bookmark_file_set_groups:
* @bookmark: a #GBookmarkFile
* @uri: an item's URI
- * @groups: an array of group names, or %NULL to remove all groups
+ * @groups: (allow-none): an array of group names, or %NULL to remove all groups
* @length: number of group name values in @groups
*
* Sets a list of group names for the item with URI @uri. Each previously
if (!item->metadata)
item->metadata = bookmark_metadata_new ();
- if (item->metadata->groups != NULL)
- {
- g_list_foreach (item->metadata->groups,
- (GFunc) g_free,
- NULL);
- g_list_free (item->metadata->groups);
- item->metadata->groups = NULL;
- }
+ g_list_free_full (item->metadata->groups, g_free);
+ item->metadata->groups = NULL;
if (groups)
{
* g_bookmark_file_get_groups:
* @bookmark: a #GBookmarkFile
* @uri: a valid URI
- * @length: return location for the length of the returned string, or %NULL
+ * @length: (allow-none): return location for the length of the returned string, or %NULL
* @error: return location for a #GError, or %NULL
*
* Retrieves the list of group names of the bookmark for @uri.
* g_bookmark_file_add_application:
* @bookmark: a #GBookmarkFile
* @uri: a valid URI
- * @name: the name of the application registering the bookmark
+ * @name: (allow-none): the name of the application registering the bookmark
* or %NULL
- * @exec: command line to be used to launch the bookmark or %NULL
+ * @exec: (allow-none): command line to be used to launch the bookmark or %NULL
*
* Adds the application with @name and @exec to the list of
* applications that have registered a bookmark for @uri into
* If @name is %NULL, the name of the application will be the
* same returned by g_get_application_name(); if @exec is %NULL, the
* command line will be a composition of the program name as
- * returned by g_get_prgname() and the "%u" modifier, which will be
+ * returned by g_get_prgname() and the "\%u" modifier, which will be
* expanded to the bookmark's URI.
*
* This function will automatically take care of updating the
*
* @name can be any UTF-8 encoded string used to identify an
* application.
- * @exec can have one of these two modifiers: "%f", which will
+ * @exec can have one of these two modifiers: "\%f", which will
* be expanded as the local file name retrieved from the bookmark's
- * URI; "%u", which will be expanded as the bookmark's URI.
+ * URI; "\%u", which will be expanded as the bookmark's URI.
* The expansion is done automatically when retrieving the stored
* command line using the g_bookmark_file_get_app_info() function.
* @count is the number of times the application has registered the
* @bookmark: a #GBookmarkFile
* @uri: a valid URI
* @name: an application's name
- * @exec: location for the command line of the application, or %NULL
- * @count: return location for the registration count, or %NULL
- * @stamp: return location for the last registration time, or %NULL
+ * @exec: (allow-none): location for the command line of the application, or %NULL
+ * @count: (allow-none): return location for the registration count, or %NULL
+ * @stamp: (allow-none): return location for the last registration time, or %NULL
* @error: return location for a #GError, or %NULL
*
* Gets the registration informations of @app_name for the bookmark for
* g_bookmark_file_get_applications:
* @bookmark: a #GBookmarkFile
* @uri: a valid URI
- * @length: return location of the length of the returned list, or %NULL
+ * @length: (allow-none): return location of the length of the returned list, or %NULL
* @error: return location for a #GError, or %NULL
*
* Retrieves the names of the applications that have registered the
* g_bookmark_file_move_item:
* @bookmark: a #GBookmarkFile
* @old_uri: a valid URI
- * @new_uri: a valid URI, or %NULL
+ * @new_uri: (allow-none): a valid URI, or %NULL
* @error: return location for a #GError or %NULL
*
* Changes the URI of a bookmark item from @old_uri to @new_uri. Any
* g_bookmark_file_set_icon:
* @bookmark: a #GBookmarkFile
* @uri: a valid URI
- * @href: the URI of the icon for the bookmark, or %NULL
+ * @href: (allow-none): the URI of the icon for the bookmark, or %NULL
* @mime_type: the MIME type of the icon for the bookmark
*
* Sets the icon for the bookmark for @uri. If @href is %NULL, unsets
* g_bookmark_file_get_icon:
* @bookmark: a #GBookmarkFile
* @uri: a valid URI
- * @href: return location for the icon's location or %NULL
- * @mime_type: return location for the icon's MIME type or %NULL
+ * @href: (allow-none): return location for the icon's location or %NULL
+ * @mime_type: (allow-none): return location for the icon's MIME type or %NULL
* @error: return location for a #GError or %NULL
*
* Gets the icon of the bookmark for @uri.
return TRUE;
}
-
-#define __G_BOOKMARK_FILE_C__
-#include "galiasdef.c"
projects / platform / upstream / glib2.0.git / blobdiff