Next: , Previous: Top, Up: Top

1 Bookmark file parser

parses files containing bookmarks

1.1 Overview

<g-bookmark-file> 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 %u" timestamp="1115726763"/>
               <bookmark:application name="GViM" count="7" exec="gvim %f" 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 <g-bookmark-file> parser was added in GLib 2.12.

1.2 Usage

— Class: <g-bookmark-file>

Opaque pointer.

This class defines no direct slots.

— Function: g-bookmark-file-new ⇒  (ret <g-bookmark-file>)

Creates a new empty <g-bookmark-file> 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.

ret
an empty <g-bookmark-file>

Since 2.12

— Function: g-bookmark-file-load-from-file (bookmark <g-bookmark-file>) (filename mchars) ⇒  (ret bool)

Loads a desktop bookmark file into an empty <g-bookmark-file> structure. If the file could not be loaded then error is set to either a <g-file-error> or <g-bookmark-file-error>.

bookmark
an empty <g-bookmark-file> struct
filename
the path of a filename to load, in the GLib file name encoding
error
return location for a <g-error>, or ‘#f’
ret
‘#t’ if a desktop bookmark file could be loaded

Since 2.12

— Function: g-bookmark-file-load-from-data (bookmark <g-bookmark-file>) (data mchars) ⇒  (ret bool)

Loads a bookmark file from memory into an empty <g-bookmark-file> structure. If the object cannot be created then error is set to a <g-bookmark-file-error>.

bookmark
an empty <g-bookmark-file> struct
data
desktop bookmarks loaded in memory
length
the length of data in bytes
error
return location for a <g-error>, or ‘#f’
ret
‘#t’ if a desktop bookmark could be loaded.

Since 2.12

— Function: g-bookmark-file-load-from-data-dirs (bookmark <g-bookmark-file>) (file mchars) ⇒  (ret bool) (full_path mchars)

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 <g-file-error> or <g-bookmark-file-error>.

bookmark
a <g-bookmark-file>
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 ‘#f’
error
return location for a <g-error>, or ‘#f’
ret
‘#t’ if a key file could be loaded, ‘#f’ othewise

Since 2.12

— Function: g-bookmark-file-to-data (bookmark <g-bookmark-file>) ⇒  (ret mchars)

This function outputs bookmark as a string.

bookmark
a <g-bookmark-file>
length
return location for the length of the returned string, or ‘#f’
error
return location for a <g-error>, or ‘#f’
ret
a newly allocated string holding the contents of the <g-bookmark-file>

Since 2.12

— Function: g-bookmark-file-to-file (bookmark <g-bookmark-file>) (filename mchars) ⇒  (ret bool)

This function outputs bookmark into a file. The write process is guaranteed to be atomic by using g-file-set-contents internally.

bookmark
a <g-bookmark-file>
filename
path of the output file
error
return location for a <g-error>, or ‘#f’
ret
‘#t’ if the file was successfully written.

Since 2.12

— Function: g-bookmark-file-has-item (bookmark <g-bookmark-file>) (uri mchars) ⇒  (ret bool)

Looks whether the desktop bookmark has an item with its URI set to uri.

bookmark
a <g-bookmark-file>
uri
a valid URI
ret
‘#t’ if uri is inside bookmark, ‘#f’ otherwise

Since 2.12

— Function: g-bookmark-file-has-group (bookmark <g-bookmark-file>) (uri mchars) (group mchars) ⇒  (ret bool)

Checks whether group appears in the list of groups to which the bookmark for uri belongs to.

In the event the URI cannot be found, ‘#f’ is returned and error is set to <g-bookmark-file-error-uri-not-found>.

bookmark
a <g-bookmark-file>
uri
a valid URI
group
the group name to be searched
error
return location for a <g-error>, or ‘#f’
ret
‘#t’ if group was found.

Since 2.12

— Function: g-bookmark-file-has-application (bookmark <g-bookmark-file>) (uri mchars) (name mchars) ⇒  (ret bool)

Checks whether the bookmark for uri inside bookmark has been registered by application name.

In the event the URI cannot be found, ‘#f’ is returned and error is set to <g-bookmark-file-error-uri-not-found>.

bookmark
a <g-bookmark-file>
uri
a valid URI
name
the name of the application
error
return location for a <g-error> or ‘#f’
ret
‘#t’ if the application name was found

Since 2.12

— Function: g-bookmark-file-get-size (bookmark <g-bookmark-file>) ⇒  (ret int)

Gets the number of bookmarks inside bookmark.

bookmark
a <g-bookmark-file>
ret
the number of bookmarks

Since 2.12

— Function: g-bookmark-file-get-uris (bookmark <g-bookmark-file>) ⇒  (ret scm)

Returns all URIs of the bookmarks in the bookmark file bookmark. The array of returned URIs will be ‘#f’-terminated, so length may optionally be ‘#f’.

bookmark
a <g-bookmark-file>
length
return location for the number of returned URIs, or ‘#f’
ret
a newly allocated ‘#f’-terminated array of strings. Use g-strfreev to free it.

Since 2.12

— Function: g-bookmark-file-get-title (bookmark <g-bookmark-file>) (uri mchars) ⇒  (ret mchars)

Returns the title of the bookmark for uri.

If uri is ‘#f’, the title of bookmark is returned.

In the event the URI cannot be found, ‘#f’ is returned and error is set to <g-bookmark-file-error-uri-not-found>.

bookmark
a <g-bookmark-file>
uri
a valid URI or ‘#f’
error
return location for a <g-error>, or ‘#f’
ret
a newly allocated string or ‘#f’ if the specified URI cannot be found.

Since 2.12

— Function: g-bookmark-file-get-description (bookmark <g-bookmark-file>) (uri mchars) ⇒  (ret mchars)

Retrieves the description of the bookmark for uri.

In the event the URI cannot be found, ‘#f’ is returned and error is set to <g-bookmark-file-error-uri-not-found>.

bookmark
a <g-bookmark-file>
uri
a valid URI
error
return location for a <g-error>, or ‘#f’
ret
a newly allocated string or ‘#f’ if the specified URI cannot be found.

Since 2.12

— Function: g-bookmark-file-get-mime-type (bookmark <g-bookmark-file>) (uri mchars) ⇒  (ret mchars)

Retrieves the MIME type of the resource pointed by uri.

In the event the URI cannot be found, ‘#f’ is returned and error is set to <g-bookmark-file-error-uri-not-found>. In the event that the MIME type cannot be found, ‘#f’ is returned and error is set to <g-bookmark-file-error-invalid-value>.

bookmark
a <g-bookmark-file>
uri
a valid URI
error
return location for a <g-error>, or ‘#f’
ret
a newly allocated string or ‘#f’ if the specified URI cannot be found.

Since 2.12

— Function: g-bookmark-file-get-is-private (bookmark <g-bookmark-file>) (uri mchars) ⇒  (ret bool)

Gets whether the private flag of the bookmark for uri is set.

In the event the URI cannot be found, ‘#f’ is returned and error is set to <g-bookmark-file-error-uri-not-found>. In the event that the private flag cannot be found, ‘#f’ is returned and error is set to <g-bookmark-file-error-invalid-value>.

bookmark
a <g-bookmark-file>
uri
a valid URI
error
return location for a <g-error>, or ‘#f’
ret
‘#t’ if the private flag is set, ‘#f’ otherwise.

Since 2.12

— Function: g-bookmark-file-get-icon (bookmark <g-bookmark-file>) (uri mchars) ⇒  (ret bool) (href mchars) (mime_type mchars)

Gets the icon of the bookmark for uri.

In the event the URI cannot be found, ‘#f’ is returned and error is set to <g-bookmark-file-error-uri-not-found>.

bookmark
a <g-bookmark-file>
uri
a valid URI
href
return location for the icon's location or ‘#f’
mime-type
return location for the icon's MIME type or ‘#f’
error
return location for a <g-error> or ‘#f’
ret
‘#t’ if the icon for the bookmark for the URI was found. You should free the returned strings.

Since 2.12

— Function: g-bookmark-file-get-added (bookmark <g-bookmark-file>) (uri mchars) ⇒  (ret long)

Gets the time the bookmark for uri was added to bookmark

In the event the URI cannot be found, -1 is returned and error is set to <g-bookmark-file-error-uri-not-found>.

bookmark
a <g-bookmark-file>
uri
a valid URI
error
return location for a <g-error>, or ‘#f’
ret
a timestamp

Since 2.12

— Function: g-bookmark-file-get-modified (bookmark <g-bookmark-file>) (uri mchars) ⇒  (ret long)

Gets the time when the bookmark for uri was last modified.

In the event the URI cannot be found, -1 is returned and error is set to <g-bookmark-file-error-uri-not-found>.

bookmark
a <g-bookmark-file>
uri
a valid URI
error
return location for a <g-error>, or ‘#f’
ret
a timestamp

Since 2.12

— Function: g-bookmark-file-get-visited (bookmark <g-bookmark-file>) (uri mchars) ⇒  (ret long)

Gets the time the bookmark for uri was last visited.

In the event the URI cannot be found, -1 is returned and error is set to <g-bookmark-file-error-uri-not-found>.

bookmark
a <g-bookmark-file>
uri
a valid URI
error
return location for a <g-error>, or ‘#f’
ret
a timestamp.

Since 2.12

— Function: g-bookmark-file-get-groups (bookmark <g-bookmark-file>) (uri mchars) ⇒  (ret scm)

Retrieves the list of group names of the bookmark for uri.

In the event the URI cannot be found, ‘#f’ is returned and error is set to <g-bookmark-file-error-uri-not-found>.

The returned array is ‘#f’ terminated, so length may optionally be ‘#f’.

bookmark
a <g-bookmark-file>
uri
a valid URI
length
return location for the length of the returned string, or ‘#f’
error
return location for a <g-error>, or ‘#f’
ret
a newly allocated ‘#f’-terminated array of group names. Use g-strfreev to free it.

Since 2.12

— Function: g-bookmark-file-get-applications (bookmark <g-bookmark-file>) (uri mchars) ⇒  (ret scm)

Retrieves the names of the applications that have registered the bookmark for uri.

In the event the URI cannot be found, ‘#f’ is returned and error is set to <g-bookmark-file-error-uri-not-found>.

bookmark
a <g-bookmark-file>
uri
a valid URI
length
return location of the length of the returned list, or ‘#f’
error
return location for a <g-error>, or ‘#f’
ret
a newly allocated ‘#f’-terminated array of strings. Use g-strfreev to free it.

Since 2.12

— Function: g-bookmark-file-get-app-info (bookmark <g-bookmark-file>) (uri mchars) (name mchars) ⇒  (ret bool) (exec mchars) (count unsigned-int) (stamp long)

Gets the registration informations of app-name for the bookmark for uri. See g-bookmark-file-set-app-info for more informations about the returned data.

The string returned in app-exec must be freed.

In the event the URI cannot be found, ‘#f’ is returned and error is set to <g-bookmark-file-error-uri-not-found>. In the event that no application with name app-name has registered a bookmark for uri, ‘#f’ is returned and error is set to <g-bookmark-file-error-app-not-registered>.

bookmark
a <g-bookmark-file>
uri
a valid URI
name
an application's name
exec
location for the command line of the application, or ‘#f’
count
return location for the registration count, or ‘#f’
stamp
return location for the last registration time, or ‘#f’
error
return location for a <g-error>, or ‘#f’
ret
‘#t’ on success.

Since 2.12

— Function: g-bookmark-file-set-title (bookmark <g-bookmark-file>) (uri mchars) (title mchars)

Sets title as the title of the bookmark for uri inside the bookmark file bookmark.

If uri is ‘#f’, the title of bookmark is set.

If a bookmark for uri cannot be found then it is created.

bookmark
a <g-bookmark-file>
uri
a valid URI or ‘#f’
title
a UTF-8 encoded string

Since 2.12

— Function: g-bookmark-file-set-description (bookmark <g-bookmark-file>) (uri mchars) (description mchars)

Sets description as the description of the bookmark for uri.

If uri is ‘#f’, the description of bookmark is set.

If a bookmark for uri cannot be found then it is created.

bookmark
a <g-bookmark-file>
uri
a valid URI or ‘#f’
description
a string

Since 2.12

— Function: g-bookmark-file-set-mime-type (bookmark <g-bookmark-file>) (uri mchars) (mime_type mchars)

Sets mime-type as the MIME type of the bookmark for uri.

If a bookmark for uri cannot be found then it is created.

bookmark
a <g-bookmark-file>
uri
a valid URI
mime-type
a MIME type

Since 2.12

— Function: g-bookmark-file-set-is-private (bookmark <g-bookmark-file>) (uri mchars) (is_private bool)

Sets the private flag of the bookmark for uri.

If a bookmark for uri cannot be found then it is created.

bookmark
a <g-bookmark-file>
uri
a valid URI
is-private
‘#t’ if the bookmark should be marked as private

Since 2.12

— Function: g-bookmark-file-set-icon (bookmark <g-bookmark-file>) (uri mchars) (href mchars) (mime_type mchars)

Sets the icon for the bookmark for uri. If href is ‘#f’, unsets the currently set icon.

If no bookmark for uri is found it is created.

bookmark
a <g-bookmark-file>
uri
a valid URI
href
the URI of the icon for the bookmark, or ‘#f’
mime-type
the MIME type of the icon for the bookmark

Since 2.12

— Function: g-bookmark-file-set-added (bookmark <g-bookmark-file>) (uri mchars) (added long)

Sets the time the bookmark for uri was added into bookmark.

If no bookmark for uri is found then it is created.

bookmark
a <g-bookmark-file>
uri
a valid URI
added
a timestamp or -1 to use the current time

Since 2.12

— Function: g-bookmark-file-set-modified (bookmark <g-bookmark-file>) (uri mchars) (modified long)

Sets the last time the bookmark for uri was last modified.

If no bookmark for uri is found then it is created.

The "modified" time should only be set when the bookmark's meta-data was actually changed. Every function of <g-bookmark-file> that modifies a bookmark also changes the modification time, except for g-bookmark-file-set-visited.

bookmark
a <g-bookmark-file>
uri
a valid URI
modified
a timestamp or -1 to use the current time

Since 2.12

— Function: g-bookmark-file-set-visited (bookmark <g-bookmark-file>) (uri mchars) (visited long)

Sets the time the bookmark for uri was last visited.

If no bookmark for uri is found then it is created.

The "visited" time should only be set if the bookmark was launched, either using the command line retrieved by g-bookmark-file-get-app-info or by the default application for the bookmark's MIME type, retrieved using g-bookmark-file-get-mime-type. Changing the "visited" time does not affect the "modified" time.

bookmark
a <g-bookmark-file>
uri
a valid URI
visited
a timestamp or -1 to use the current time

Since 2.12

— Function: g-bookmark-file-set-app-info (bookmark <g-bookmark-file>) (uri mchars) (name mchars) (exec mchars) (count int) (stamp long) ⇒  (ret bool)

Sets the meta-data of application name inside the list of applications that have registered a bookmark for uri inside bookmark.

You should rarely use this function; use g-bookmark-file-add-application and g-bookmark-file-remove-application instead.

name can be any UTF-8 encoded string used to identify an application. 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. 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; if is < 0, the current registration count will be increased by one, if is 0, the application with name will be removed from the list of registered applications. stamp is the Unix time of the last registration; if it is -1, the current time will be used.

If you try to remove an application by setting its registration count to zero, and no bookmark for uri is found, ‘#f’ is returned and error is set to <g-bookmark-file-error-uri-not-found>; similarly, in the event that no application name has registered a bookmark for uri, ‘#f’ is returned and error is set to <g-bookmark-file-error-app-not-registered>. Otherwise, if no bookmark for uri is found, one is created.

bookmark
a <g-bookmark-file>
uri
a valid URI
name
an application's name
exec
an application's command line
count
the number of registrations done for this application
stamp
the time of the last registration for this application
error
return location for a <g-error> or ‘#f’
ret
‘#t’ if the application's meta-data was successfully changed.

Since 2.12

— Function: g-bookmark-file-add-group (bookmark <g-bookmark-file>) (uri mchars) (group mchars)

Adds group to the list of groups to which the bookmark for uri belongs to.

If no bookmark for uri is found then it is created.

bookmark
a <g-bookmark-file>
uri
a valid URI
group
the group name to be added

Since 2.12

— Function: g-bookmark-file-add-application (bookmark <g-bookmark-file>) (uri mchars) (name mchars) (exec mchars)

Adds the application with name and exec to the list of applications that have registered a bookmark for uri into bookmark.

Every bookmark inside a <g-bookmark-file> must have at least an application registered. Each application must provide a name, a command line useful for launching the bookmark, the number of times the bookmark has been registered by the application and the last time the application registered this bookmark.

If name is ‘#f’, the name of the application will be the same returned by g-get-application; if exec is ‘#f’, the command line will be a composition of the program name as 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 registrations count and timestamping in case an application with the same name had already registered a bookmark for uri inside bookmark.

If no bookmark for uri is found, one is created.

bookmark
a <g-bookmark-file>
uri
a valid URI
name
the name of the application registering the bookmark or ‘#f’
exec
command line to be used to launch the bookmark or ‘#f’

Since 2.12

— Function: g-bookmark-file-remove-group (bookmark <g-bookmark-file>) (uri mchars) (group mchars) ⇒  (ret bool)

Removes group from the list of groups to which the bookmark for uri belongs to.

In the event the URI cannot be found, ‘#f’ is returned and error is set to <g-bookmark-file-error-uri-not-found>. In the event no group was defined, ‘#f’ is returned and error is set to <g-bookmark-file-error-invalid-value>.

bookmark
a <g-bookmark-file>
uri
a valid URI
group
the group name to be removed
error
return location for a <g-error>, or ‘#f’
ret
‘#t’ if group was successfully removed.

Since 2.12

— Function: g-bookmark-file-remove-application (bookmark <g-bookmark-file>) (uri mchars) (name mchars) ⇒  (ret bool)

Removes application registered with name from the list of applications that have registered a bookmark for uri inside bookmark.

In the event the URI cannot be found, ‘#f’ is returned and error is set to <g-bookmark-file-error-uri-not-found>. In the event that no application with name app-name has registered a bookmark for uri, ‘#f’ is returned and error is set to <g-bookmark-file-error-app-not-registered>.

bookmark
a <g-bookmark-file>
uri
a valid URI
name
the name of the application
error
return location for a <g-error> or ‘#f’
ret
‘#t’ if the application was successfully removed.

Since 2.12

— Function: g-bookmark-file-remove-item (bookmark <g-bookmark-file>) (uri mchars) ⇒  (ret bool)

Removes the bookmark for uri from the bookmark file bookmark.

bookmark
a <g-bookmark-file>
uri
a valid URI
error
return location for a <g-error>, or ‘#f’
ret
‘#t’ if the bookmark was removed successfully.

Since 2.12

— Function: g-bookmark-file-move-item (bookmark <g-bookmark-file>) (old_uri mchars) (new_uri mchars) ⇒  (ret bool)

Changes the URI of a bookmark item from old-uri to new-uri. Any existing bookmark for new-uri will be overwritten. If new-uri is ‘#f’, then the bookmark is removed.

In the event the URI cannot be found, ‘#f’ is returned and error is set to <g-bookmark-file-error-uri-not-found>.

bookmark
a <g-bookmark-file>
old-uri
a valid URI
new-uri
a valid URI, or ‘#f’
error
return location for a <g-error> or ‘#f’
ret
‘#t’ if the URI was successfully changed

Since 2.12