Bookmark file parser

Bookmark file parser — parses files containing bookmarks

Synopsis


#include <glib.h>


            GBookmarkFile;
#define     G_BOOKMARK_FILE_ERROR
enum        GBookmarkFileError;
GBookmarkFile* g_bookmark_file_new          (void);
void        g_bookmark_file_free            (GBookmarkFile *bookmark);
gboolean    g_bookmark_file_load_from_file  (GBookmarkFile *bookmark,
                                             const gchar *filename,
                                             GError **error);
gboolean    g_bookmark_file_load_from_data  (GBookmarkFile *bookmark,
                                             const gchar *data,
                                             gsize length,
                                             GError **error);
gboolean    g_bookmark_file_load_from_data_dirs
                                            (GBookmarkFile *bookmark,
                                             const gchar *file,
                                             gchar **full_path,
                                             GError **error);
gchar*      g_bookmark_file_to_data         (GBookmarkFile *bookmark,
                                             gsize *length,
                                             GError **error);
gboolean    g_bookmark_file_to_file         (GBookmarkFile *bookmark,
                                             const gchar *filename,
                                             GError **error);
gboolean    g_bookmark_file_has_item        (GBookmarkFile *bookmark,
                                             const gchar *uri);
gboolean    g_bookmark_file_has_group       (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             const gchar *group,
                                             GError **error);
gboolean    g_bookmark_file_has_application (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             const gchar *name,
                                             GError **error);
gint        g_bookmark_file_get_size        (GBookmarkFile *bookmark);
gchar**     g_bookmark_file_get_uris        (GBookmarkFile *bookmark,
                                             gsize *length);

gchar*      g_bookmark_file_get_title       (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             GError **error);
gchar*      g_bookmark_file_get_description (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             GError **error);
gchar*      g_bookmark_file_get_mime_type   (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             GError **error);
gboolean    g_bookmark_file_get_is_private  (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             GError **error);
gboolean    g_bookmark_file_get_icon        (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             gchar **href,
                                             gchar **mime_type,
                                             GError **error);
time_t      g_bookmark_file_get_added       (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             GError **error);
time_t      g_bookmark_file_get_modified    (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             GError **error);
time_t      g_bookmark_file_get_visited     (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             GError **error);
gchar**     g_bookmark_file_get_groups      (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             gsize *length,
                                             GError **error);
gchar**     g_bookmark_file_get_applications
                                            (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             gsize *length,
                                             GError **error);
gboolean    g_bookmark_file_get_app_info    (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             const gchar *name,
                                             gchar **exec,
                                             guint *count,
                                             time_t *stamp,
                                             GError **error);

void        g_bookmark_file_set_title       (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             const gchar *title);
void        g_bookmark_file_set_description (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             const gchar *description);
void        g_bookmark_file_set_mime_type   (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             const gchar *mime_type);
void        g_bookmark_file_set_is_private  (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             gboolean is_private);
void        g_bookmark_file_set_icon        (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             const gchar *href,
                                             const gchar *mime_type);
void        g_bookmark_file_set_added       (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             time_t added);
void        g_bookmark_file_set_groups      (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             const gchar **groups,
                                             gsize length);
void        g_bookmark_file_set_modified    (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             time_t modified);
void        g_bookmark_file_set_visited     (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             time_t visited);
gboolean    g_bookmark_file_set_app_info    (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             const gchar *name,
                                             const gchar *exec,
                                             gint count,
                                             time_t stamp,
                                             GError **error);
void        g_bookmark_file_add_group       (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             const gchar *group);
void        g_bookmark_file_add_application (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             const gchar *name,
                                             const gchar *exec);
gboolean    g_bookmark_file_remove_group    (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             const gchar *group,
                                             GError **error);
gboolean    g_bookmark_file_remove_application
                                            (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             const gchar *name,
                                             GError **error);
gboolean    g_bookmark_file_remove_item     (GBookmarkFile *bookmark,
                                             const gchar *uri,
                                             GError **error);
gboolean    g_bookmark_file_move_item       (GBookmarkFile *bookmark,
                                             const gchar *old_uri,
                                             const gchar *new_uri,
                                             GError **error);

Description

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 Desktop Bookmark Specification.

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 XML Bookmark Exchange Language specification, consisting of valid UTF-8 encoded XML, under the xbel root element; each bookmark is stored inside a bookmark 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 metadata element, with its owner attribute set to http://freedesktop.org, 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.


<?xml version="1.0"?>
<!DOCTYPE xbel PUBLIC 
  "+//IDN python.org//DTD XML Bookmark Exchange Language 1.0//EN//XML"
  "http://www.python.org/topics/xml/dtds/xbel-1.0.dtd">
<xbel version="1.0"
      xmlns:mime="http://www.freedesktop.org/standards/shared-mime-info"
      xmlns:bookmark="http://www.freedesktop.org/standards/desktop-bookmarks">
  <bookmark href="file:///home/ebassi/bookmark-spec/bookmark-spec.xml">
    <title>Desktop Bookmarks Spec</title>
    <info>
      <metadata owner="http://freedesktop.org">
        <mime:mime-type>text/xml</mime:mime-type>
	<bookmark:applications>
          <bookmark:application name="GEdit" count="2" exec="gedit <link linkend="u"><literal>u</literal></link>" timestamp="1115726763"/>
          <bookmark:application name="GViM" count="7" exec="gvim <link linkend="f"><literal>f</literal></link>" timestamp="1115726812"/>
	</bookmark:applications>
	<bookmark:groups>
	  <bookmark:group>Editors</bookmark:group>
	</bookmark:groups>
      </metadata>
    </info>
  </bookmark>
</xbel>

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.

Details

GBookmarkFile

typedef struct _GBookmarkFile GBookmarkFile;

The GBookmarkFile struct contains only private data and should not be used directly.


G_BOOKMARK_FILE_ERROR

#define G_BOOKMARK_FILE_ERROR	(g_bookmark_file_error_quark ())

Error domain for bookmark file parsing. Errors in this domain will be from the GBookmarkFileError enumeration. See GError for informations on error domains.


enum GBookmarkFileError

typedef enum
{
  G_BOOKMARK_FILE_ERROR_INVALID_URI,
  G_BOOKMARK_FILE_ERROR_INVALID_VALUE,
  G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED,
  G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND,
  G_BOOKMARK_FILE_ERROR_READ,
  G_BOOKMARK_FILE_ERROR_UNKNOWN_ENCODING,
  G_BOOKMARK_FILE_ERROR_WRITE,
  G_BOOKMARK_FILE_ERROR_FILE_NOT_FOUND
} GBookmarkFileError;

Error codes returned by bookmark file parsing.

G_BOOKMARK_FILE_ERROR_INVALID_URI URI was ill-formed
G_BOOKMARK_FILE_ERROR_INVALID_VALUE a requested field was not found
G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED a requested application did not register a bookmark
G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND a requested URI was not found
G_BOOKMARK_FILE_ERROR_READ document was ill formed
G_BOOKMARK_FILE_ERROR_UNKNOWN_ENCODING the text being parsed was in an unknown encoding
G_BOOKMARK_FILE_ERROR_WRITE an error occurred while writing
G_BOOKMARK_FILE_ERROR_FILE_NOT_FOUND requested file was not found

g_bookmark_file_new ()

GBookmarkFile* g_bookmark_file_new          (void);

Creates a new empty GBookmarkFile object.

Use g_bookmark_file_load_from_file(), g_bookmark_file_load_from_data() or g_bookmark_file_load_from_data_dirs() to read an existing bookmark file.

Returns : an empty GBookmarkFile

Since 2.12


g_bookmark_file_free ()

void        g_bookmark_file_free            (GBookmarkFile *bookmark);

Frees a GBookmarkFile.

bookmark : a GBookmarkFile

Since 2.12


g_bookmark_file_load_from_file ()

gboolean    g_bookmark_file_load_from_file  (GBookmarkFile *bookmark,
                                             const gchar *filename,
                                             GError **error);

Loads a desktop bookmark file into an empty GBookmarkFile structure. If the file could not be loaded then error is set to either a GFileError or GBookmarkFileError.

bookmark : an empty GBookmarkFile struct
filename : the path of a filename to load, in the GLib file name encoding
error : return location for a GError, or NULL
Returns : TRUE if a desktop bookmark file could be loaded

Since 2.12


g_bookmark_file_load_from_data ()

gboolean    g_bookmark_file_load_from_data  (GBookmarkFile *bookmark,
                                             const gchar *data,
                                             gsize length,
                                             GError **error);

Loads a bookmark file from memory into an empty GBookmarkFile structure. If the object cannot be created then error is set to a GBookmarkFileError.

bookmark : an empty GBookmarkFile struct
data : desktop bookmarks loaded in memory
length : the length of data in bytes
error : return location for a GError, or NULL
Returns : TRUE if a desktop bookmark could be loaded.

Since 2.12


g_bookmark_file_load_from_data_dirs ()

gboolean    g_bookmark_file_load_from_data_dirs
                                            (GBookmarkFile *bookmark,
                                             const gchar *file,
                                             gchar **full_path,
                                             GError **error);

This function looks for a desktop bookmark file named file in the paths returned from g_get_user_data_dir() and g_get_system_data_dirs(), loads the file into bookmark and returns the file's full path in full_path. If the file could not be loaded then an error is set to either a GFileError or GBookmarkFileError.

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 of the file, or NULL
error : return location for a GError, or NULL
Returns : TRUE if a key file could be loaded, FALSE othewise

Since 2.12


g_bookmark_file_to_data ()

gchar*      g_bookmark_file_to_data         (GBookmarkFile *bookmark,
                                             gsize *length,
                                             GError **error);

This function outputs bookmark as a string.

bookmark : a GBookmarkFile
length : return location for the length of the returned string, or NULL
error : return location for a GError, or NULL
Returns : a newly allocated string holding the contents of the GBookmarkFile

Since 2.12


g_bookmark_file_to_file ()

gboolean    g_bookmark_file_to_file         (GBookmarkFile *bookmark,
                                             const gchar *filename,