Bookmark file parser: GLib Reference Manual

Bookmark file parser

Bookmark file parser — parses files containing bookmarks

Functions

GBookmarkFile *	g_bookmark_file_new ()
void	g_bookmark_file_free ()
gboolean	g_bookmark_file_load_from_file ()
gboolean	g_bookmark_file_load_from_data ()
gboolean	g_bookmark_file_load_from_data_dirs ()
gchar *	g_bookmark_file_to_data ()
gboolean	g_bookmark_file_to_file ()
gboolean	g_bookmark_file_has_item ()
gboolean	g_bookmark_file_has_group ()
gboolean	g_bookmark_file_has_application ()
gint	g_bookmark_file_get_size ()
gchar **	g_bookmark_file_get_uris ()
gchar *	g_bookmark_file_get_title ()
gchar *	g_bookmark_file_get_description ()
gchar *	g_bookmark_file_get_mime_type ()
gboolean	g_bookmark_file_get_is_private ()
gboolean	g_bookmark_file_get_icon ()
time_t	g_bookmark_file_get_added ()
GDateTime *	g_bookmark_file_get_added_date_time ()
time_t	g_bookmark_file_get_modified ()
GDateTime *	g_bookmark_file_get_modified_date_time ()
time_t	g_bookmark_file_get_visited ()
GDateTime *	g_bookmark_file_get_visited_date_time ()
gchar **	g_bookmark_file_get_groups ()
gchar **	g_bookmark_file_get_applications ()
gboolean	g_bookmark_file_get_app_info ()
gboolean	g_bookmark_file_get_application_info ()
void	g_bookmark_file_set_title ()
void	g_bookmark_file_set_description ()
void	g_bookmark_file_set_mime_type ()
void	g_bookmark_file_set_is_private ()
void	g_bookmark_file_set_icon ()
void	g_bookmark_file_set_added ()
void	g_bookmark_file_set_added_date_time ()
void	g_bookmark_file_set_groups ()
void	g_bookmark_file_set_modified ()
void	g_bookmark_file_set_modified_date_time ()
void	g_bookmark_file_set_visited ()
void	g_bookmark_file_set_visited_date_time ()
gboolean	g_bookmark_file_set_app_info ()
gboolean	g_bookmark_file_set_application_info ()
void	g_bookmark_file_add_group ()
void	g_bookmark_file_add_application ()
gboolean	g_bookmark_file_remove_group ()
gboolean	g_bookmark_file_remove_application ()
gboolean	g_bookmark_file_remove_item ()
gboolean	g_bookmark_file_move_item ()

Types and Values

	GBookmarkFile
#define	G_BOOKMARK_FILE_ERROR
enum	GBookmarkFileError

Includes

#include <glib.h>
#include <glib/gprintf.h>

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.

Here is an example of a bookmark file: bookmarks.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_application_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.

Functions

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.

[constructor]

Returns

an empty GBookmarkFile

Since: 2.12

g_bookmark_file_free ()

void
g_bookmark_file_free (GBookmarkFile *bookmark);

Frees a GBookmarkFile.

Parameters

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.

Parameters

bookmark	an empty GBookmarkFile struct
filename	the path of a filename to load, in the GLib file name encoding.	[type filename]
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.

Parameters

bookmark	an empty GBookmarkFile struct
data	desktop bookmarks loaded in memory.	[array length=length][element-type guint8]
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 error is set to either a GFileError or GBookmarkFileError.

Parameters

bookmark	a GBookmarkFile
file	a relative path to a filename to open and parse.	[type filename]
full_path	return location for a string containing the full path of the file, or `NULL`.	[out][optional][type filename]
error	return location for a GError, or `NULL`

Returns

TRUE if a key file could be loaded, FALSE otherwise

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.

Parameters

bookmark	a GBookmarkFile
length	return location for the length of the returned string, or `NULL`.	[out][optional]
error	return location for a GError, or `NULL`

Returns

a newly allocated string holding the contents of the GBookmarkFile.

[transfer full][array length=length][element-type guint8]

Since: 2.12

g_bookmark_file_to_file ()

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

This function outputs bookmark into a file. The write process is guaranteed to be atomic by using g_file_set_contents() internally.

Parameters

bookmark	a GBookmarkFile
filename	path of the output file.	[type filename]
error	return location for a GError, or `NULL`

Returns

TRUE if the file was successfully written.

Since: 2.12

g_bookmark_file_has_item ()

gboolean
g_bookmark_file_has_item (GBookmarkFile *bookmark,
                          const gchar *uri);

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

Parameters

bookmark	a GBookmarkFile
uri	a valid URI

Returns

TRUE if uri is inside bookmark , FALSE otherwise

Since: 2.12

g_bookmark_file_has_group ()

gboolean
g_bookmark_file_has_group (GBookmarkFile *bookmark,
                           const gchar *uri,
                           const gchar *group,
                           GError **error);

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, FALSE is returned and error is set to G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.

Parameters

bookmark	a GBookmarkFile
uri	a valid URI
group	the group name to be searched
error	return location for a GError, or `NULL`

Returns

TRUE if group was found.

Since: 2.12

g_bookmark_file_has_application ()

gboolean
g_bookmark_file_has_application (GBookmarkFile *bookmark,
                                 const gchar *uri,
                                 const gchar *name,
                                 GError **error);

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

In the event the URI cannot be found, FALSE is returned and error is set to G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.

Parameters

bookmark	a GBookmarkFile
uri	a valid URI
name	the name of the application
error	return location for a GError or `NULL`

Returns

TRUE if the application name was found

Since: 2.12

g_bookmark_file_get_size ()

gint
g_bookmark_file_get_size (GBookmarkFile *bookmark);

Gets the number of bookmarks inside bookmark .

Parameters

bookmark

a GBookmarkFile

Returns

the number of bookmarks

Since: 2.12

g_bookmark_file_get_uris ()

gchar **
g_bookmark_file_get_uris (GBookmarkFile *bookmark,
                          gsize *length);

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

Parameters

bookmark	a GBookmarkFile
length	return location for the number of returned URIs, or `NULL`.	[out][optional]

Returns

a newly allocated NULL-terminated array of strings. Use g_strfreev() to free it.

[array length=length][transfer full]

Since: 2.12

g_bookmark_file_get_title ()

gchar *
g_bookmark_file_get_title (GBookmarkFile *bookmark,
                           const gchar *uri,
                           GError **error);

Returns the title of the bookmark for uri .

If uri is NULL, the title of bookmark is returned.

In the event the URI cannot be found, NULL is returned and error is set to G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.

Parameters

bookmark	a GBookmarkFile
uri	a valid URI or `NULL`.	[nullable]
error	return location for a GError, or `NULL`

Returns

a newly allocated string or NULL if the specified URI cannot be found.

[transfer full]

Since: 2.12

g_bookmark_file_get_description ()

gchar *
g_bookmark_file_get_description (GBookmarkFile *bookmark,
                                 const gchar *uri,
                                 GError **error);

Retrieves the description of the bookmark for uri .

In the event the URI cannot be found, NULL is returned and error is set to G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.

Parameters

bookmark	a GBookmarkFile
uri	a valid URI
error	return location for a GError, or `NULL`

Returns

a newly allocated string or NULL if the specified URI cannot be found.

[transfer full]

Since: 2.12

g_bookmark_file_get_mime_type ()

gchar *
g_bookmark_file_get_mime_type (GBookmarkFile *bookmark,
                               const gchar *uri,
                               GError **error);

Retrieves the MIME type of the resource pointed by uri .

In the event the URI cannot be found, NULL is returned and error is set to G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. In the event that the MIME type cannot be found, NULL is returned and error is set to G_BOOKMARK_FILE_ERROR_INVALID_VALUE.

Parameters

bookmark	a GBookmarkFile
uri	a valid URI
error	return location for a GError, or `NULL`

Returns

a newly allocated string or NULL if the specified URI cannot be found.

[transfer full]

Since: 2.12

g_bookmark_file_get_is_private ()

gboolean
g_bookmark_file_get_is_private (GBookmarkFile *bookmark,
                                const gchar *uri,
                                GError **error);

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

In the event the URI cannot be found, FALSE is returned and error is set to G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. In the event that the private flag cannot be found, FALSE is returned and error is set to G_BOOKMARK_FILE_ERROR_INVALID_VALUE.

Parameters

bookmark	a GBookmarkFile
uri	a valid URI
error	return location for a GError, or `NULL`

Returns

TRUE if the private flag is set, FALSE otherwise.

Since: 2.12

g_bookmark_file_get_icon ()

gboolean
g_bookmark_file_get_icon (GBookmarkFile *bookmark,
                          const gchar *uri,
                          gchar **href,
                          gchar **mime_type,
                          GError **error);

Gets the icon of the bookmark for uri .

In the event the URI cannot be found, FALSE is returned and error is set to G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.

Parameters

bookmark	a GBookmarkFile
uri	a valid URI
href	return location for the icon's location or `NULL`.	[out][optional]
mime_type	return location for the icon's MIME type or `NULL`.	[out][optional]
error	return location for a GError or `NULL`

Returns

TRUE if the icon for the bookmark for the URI was found. You should free the returned strings.

Since: 2.12

g_bookmark_file_get_added ()

time_t
g_bookmark_file_get_added (GBookmarkFile *bookmark,
                           const gchar *uri,
                           GError **error);

g_bookmark_file_get_added has been deprecated since version 2.66 and should not be used in newly-written code.

Use g_bookmark_file_get_added_date_time() instead, as time_t is deprecated due to the year 2038 problem.

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.

Parameters

bookmark	a GBookmarkFile
uri	a valid URI
error	return location for a GError, or `NULL`

Returns

a timestamp

Since: 2.12

g_bookmark_file_get_added_date_time ()

GDateTime *
g_bookmark_file_get_added_date_time (GBookmarkFile *bookmark,
                                     const char *uri,
                                     GError **error);

Gets the time the bookmark for uri was added to bookmark

In the event the URI cannot be found, NULL is returned and error is set to G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.

Parameters

bookmark	a GBookmarkFile
uri	a valid URI
error	return location for a GError, or `NULL`

Returns

a GDateTime.

[transfer none]

Since: 2.66

g_bookmark_file_get_modified ()

time_t
g_bookmark_file_get_modified (GBookmarkFile *bookmark,
                              const gchar *uri,
                              GError **error);

g_bookmark_file_get_modified has been deprecated since version 2.66 and should not be used in newly-written code.

Use g_bookmark_file_get_modified_date_time() instead, as time_t is deprecated due to the year 2038 problem.

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.

Parameters

bookmark	a GBookmarkFile
uri	a valid URI
error	return location for a GError, or `NULL`

Returns

a timestamp

Since: 2.12

g_bookmark_file_get_modified_date_time ()

GDateTime *
g_bookmark_file_get_modified_date_time
                               (GBookmarkFile *bookmark,
                                const char *uri,
                                GError **error);

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

In the event the URI cannot be found, NULL is returned and error is set to G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.

Parameters

bookmark	a GBookmarkFile
uri	a valid URI
error	return location for a GError, or `NULL`

Returns

a GDateTime.

[transfer none]

Since: 2.66

g_bookmark_file_get_visited ()

time_t
g_bookmark_file_get_visited (GBookmarkFile *bookmark,
                             const gchar *uri,
                             GError **error);

g_bookmark_file_get_visited has been deprecated since version 2.66 and should not be used in newly-written code.

Use g_bookmark_file_get_visited_date_time() instead, as time_t is deprecated due to the year 2038 problem.

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.

Parameters

bookmark	a GBookmarkFile
uri	a valid URI
error	return location for a GError, or `NULL`

Returns

a timestamp.

Since: 2.12

g_bookmark_file_get_visited_date_time ()

GDateTime *
g_bookmark_file_get_visited_date_time (GBookmarkFile *bookmark,
                                       const char *uri,
                                       GError **error);

Gets the time the bookmark for uri was last visited.

In the event the URI cannot be found, NULL is returned and error is set to G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.

Parameters

bookmark	a GBookmarkFile
uri	a valid URI
error	return location for a GError, or `NULL`

Returns

a GDateTime.

[transfer none]

Since: 2.66

g_bookmark_file_get_groups ()

gchar **
g_bookmark_file_get_groups (GBookmarkFile *bookmark,
                            const gchar *uri,
                            gsize *length,
                            GError **error);

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

In the event the URI cannot be found, NULL is returned and error is set to G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.

The returned array is NULL terminated, so length may optionally be NULL.

Parameters

bookmark	a GBookmarkFile
uri	a valid URI
length	return location for the length of the returned string, or `NULL`.	[out][optional]
error	return location for a GError, or `NULL`

Returns

a newly allocated NULL-terminated array of group names. Use g_strfreev() to free it.

[array length=length][transfer full]

Since: 2.12

g_bookmark_file_get_applications ()

gchar **
g_bookmark_file_get_applications (GBookmarkFile *bookmark,
                                  const gchar *uri,
                                  gsize *length,
                                  GError **error);

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

In the event the URI cannot be found, NULL is returned and error is set to G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.

Parameters

bookmark	a GBookmarkFile
uri	a valid URI
length	return location of the length of the returned list, or `NULL`.	[out][optional]
error	return location for a GError, or `NULL`

Returns

a newly allocated NULL-terminated array of strings. Use g_strfreev() to free it.

[array length=length][transfer full]

Since: 2.12

g_bookmark_file_get_app_info ()

gboolean
g_bookmark_file_get_app_info (GBookmarkFile *bookmark,
                              const gchar *uri,
                              const gchar *name,
                              gchar **exec,
                              guint *count,
                              time_t *stamp,
                              GError **error);

g_bookmark_file_get_app_info has been deprecated since version 2.66 and should not be used in newly-written code.

Use g_bookmark_file_get_application_info() instead, as time_t is deprecated due to the year 2038 problem.

Gets the registration information of app_name for the bookmark for uri . See g_bookmark_file_set_application_info() for more information about the returned data.

The string returned in app_exec must be freed.

In the event the URI cannot be found, FALSE 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 , FALSE is returned and error is set to G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED. In the event that unquoting the command line fails, an error of the G_SHELL_ERROR domain is set and FALSE is returned.

Parameters

bookmark	a GBookmarkFile
uri	a valid URI
name	an application's name
exec	return location for the command line of the application, or `NULL`.	[out][optional]
count	return location for the registration count, or `NULL`.	[out][optional]
stamp	return location for the last registration time, or `NULL`.	[out][optional]
error	return location for a GError, or `NULL`

Returns

TRUE on success.

Since: 2.12

g_bookmark_file_get_application_info ()

gboolean
g_bookmark_file_get_application_info (GBookmarkFile *bookmark,
                                      const char *uri,
                                      const char *name,
                                      char **exec,
                                      unsigned int *count,
                                      GDateTime **stamp,
                                      GError **error);

Gets the registration information of app_name for the bookmark for uri . See g_bookmark_file_set_application_info() for more information about the returned data.

The string returned in app_exec must be freed.

Parameters

bookmark	a GBookmarkFile
uri	a valid URI
name	an application's name
exec	return location for the command line of the application, or `NULL`.	[out][optional]
count	return location for the registration count, or `NULL`.	[out][optional]
stamp	return location for the last registration time, or `NULL`.	[out][optional][transfer none]
error	return location for a GError, or `NULL`

Returns

TRUE on success.

Since: 2.66

g_bookmark_file_set_title ()

void
g_bookmark_file_set_title (GBookmarkFile *bookmark,
                           const gchar *uri,
                           const gchar *title);

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

If uri is NULL, the title of bookmark is set.

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

Parameters

bookmark	a GBookmarkFile
uri	a valid URI or `NULL`.	[nullable]
title	a UTF-8 encoded string

Since: 2.12

g_bookmark_file_set_description ()

void
g_bookmark_file_set_description (GBookmarkFile *bookmark,
                                 const gchar *uri,
                                 const gchar *description);

Sets description as the description of the bookmark for uri .

If uri is NULL, the description of bookmark is set.

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

Parameters

bookmark	a GBookmarkFile
uri	a valid URI or `NULL`.	[nullable]
description	a string

Since: 2.12

g_bookmark_file_set_mime_type ()

void
g_bookmark_file_set_mime_type (GBookmarkFile *bookmark,
                               const gchar *uri,
                               const gchar *mime_type);

Sets mime_type as the MIME type of the bookmark for uri .

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

Parameters

bookmark	a GBookmarkFile
uri	a valid URI
mime_type	a MIME type

Since: 2.12

g_bookmark_file_set_is_private ()

void
g_bookmark_file_set_is_private (GBookmarkFile *bookmark,
                                const gchar *uri,
                                gboolean is_private);

Sets the private flag of the bookmark for uri .

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

Parameters

bookmark	a GBookmarkFile
uri	a valid URI
is_private	`TRUE` if the bookmark should be marked as private

Since: 2.12

g_bookmark_file_set_icon ()

void
g_bookmark_file_set_icon (GBookmarkFile *bookmark,
                          const gchar *uri,
                          const gchar *href,
                          const gchar *mime_type);

Sets the icon for the bookmark for uri . If href is NULL, unsets the currently set icon. href can either be a full URL for the icon file or the icon name following the Icon Naming specification.

If no bookmark for uri is found one is created.

Parameters

bookmark	a GBookmarkFile
uri	a valid URI
href	the URI of the icon for the bookmark, or `NULL`.	[nullable]
mime_type	the MIME type of the icon for the bookmark

Since: 2.12

g_bookmark_file_set_added ()

void
g_bookmark_file_set_added (GBookmarkFile *bookmark,
                           const gchar *uri,
                           time_t added);

g_bookmark_file_set_added has been deprecated since version 2.66 and should not be used in newly-written code.

Use g_bookmark_file_set_added_date_time() instead, as time_t is deprecated due to the year 2038 problem.

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

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

Parameters

bookmark	a GBookmarkFile
uri	a valid URI
added	a timestamp or -1 to use the current time

Since: 2.12

g_bookmark_file_set_added_date_time ()

void
g_bookmark_file_set_added_date_time (GBookmarkFile *bookmark,
                                     const char *uri,
                                     GDateTime *added);

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

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

Parameters

bookmark	a GBookmarkFile
uri	a valid URI
added	a GDateTime

Since: 2.66

g_bookmark_file_set_groups ()

void
g_bookmark_file_set_groups (GBookmarkFile *bookmark,
                            const gchar *uri,
                            const gchar **groups,
                            gsize length);

Sets a list of group names for the item with URI uri . Each previously set group name list is removed.

If uri cannot be found then an item for it is created.

Parameters

bookmark	a GBookmarkFile
uri	an item's URI
groups	an array of group names, or `NULL` to remove all groups.	[nullable][array length=length][element-type utf8]
length	number of group name values in `groups`

Since: 2.12

g_bookmark_file_set_modified ()

void
g_bookmark_file_set_modified (GBookmarkFile *bookmark,
                              const gchar *uri,
                              time_t modified);

g_bookmark_file_set_modified has been deprecated since version 2.66 and should not be used in newly-written code.

Use g_bookmark_file_set_modified_date_time() instead, as time_t is deprecated due to the year 2038 problem.

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 GBookmarkFile that modifies a bookmark also changes the modification time, except for g_bookmark_file_set_visited_date_time().

Parameters

bookmark	a GBookmarkFile
uri	a valid URI
modified	a timestamp or -1 to use the current time

Since: 2.12

g_bookmark_file_set_modified_date_time ()

void
g_bookmark_file_set_modified_date_time
                               (GBookmarkFile *bookmark,
                                const char *uri,
                                GDateTime *modified);

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

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

Parameters

bookmark	a GBookmarkFile
uri	a valid URI
modified	a GDateTime

Since: 2.66

g_bookmark_file_set_visited ()

void
g_bookmark_file_set_visited (GBookmarkFile *bookmark,
                             const gchar *uri,
                             time_t visited);

g_bookmark_file_set_visited has been deprecated since version 2.66 and should not be used in newly-written code.

Use g_bookmark_file_set_visited_date_time() instead, as time_t is deprecated due to the year 2038 problem.

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_application_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.

Parameters

bookmark	a GBookmarkFile
uri	a valid URI
visited	a timestamp or -1 to use the current time

Since: 2.12

g_bookmark_file_set_visited_date_time ()

void
g_bookmark_file_set_visited_date_time (GBookmarkFile *bookmark,
                                       const char *uri,
                                       GDateTime *visited);

Sets the time the bookmark for uri was last visited.

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

Parameters

bookmark	a GBookmarkFile
uri	a valid URI
visited	a GDateTime

Since: 2.66

g_bookmark_file_set_app_info ()

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);

g_bookmark_file_set_app_info has been deprecated since version 2.66 and should not be used in newly-written code.

Use g_bookmark_file_set_application_info() instead, as time_t is deprecated due to the year 2038 problem.

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_application_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, FALSE 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 , FALSE 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.

Parameters

bookmark	a GBookmarkFile
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 GError or `NULL`

Returns

TRUE if the application's meta-data was successfully changed.

Since: 2.12

g_bookmark_file_set_application_info ()

gboolean
g_bookmark_file_set_application_info (GBookmarkFile *bookmark,
                                      const char *uri,
                                      const char *name,
                                      const char *exec,
                                      int count,
                                      GDateTime *stamp,
                                      GError **error);

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.

Parameters

bookmark	a GBookmarkFile
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, which may be `NULL` if `count` is 0.	[nullable]
error	return location for a GError or `NULL`

Returns

TRUE if the application's meta-data was successfully changed.

Since: 2.66

g_bookmark_file_add_group ()

void
g_bookmark_file_add_group (GBookmarkFile *bookmark,
                           const gchar *uri,
                           const gchar *group);

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.

Parameters

bookmark	a GBookmarkFile
uri	a valid URI
group	the group name to be added

Since: 2.12

g_bookmark_file_add_application ()

void
g_bookmark_file_add_application (GBookmarkFile *bookmark,
                                 const gchar *uri,
                                 const gchar *name,
                                 const gchar *exec);

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 GBookmarkFile 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 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 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.

Parameters

bookmark	a GBookmarkFile
uri	a valid URI
name	the name of the application registering the bookmark or `NULL`.	[nullable]
exec	command line to be used to launch the bookmark or `NULL`.	[nullable]

Since: 2.12

g_bookmark_file_remove_group ()

gboolean
g_bookmark_file_remove_group (GBookmarkFile *bookmark,
                              const gchar *uri,
                              const gchar *group,
                              GError **error);

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

In the event the URI cannot be found, FALSE is returned and error is set to G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. In the event no group was defined, FALSE is returned and error is set to G_BOOKMARK_FILE_ERROR_INVALID_VALUE.

Parameters

bookmark	a GBookmarkFile
uri	a valid URI
group	the group name to be removed
error	return location for a GError, or `NULL`

Returns

TRUE if group was successfully removed.

Since: 2.12

g_bookmark_file_remove_application ()

gboolean
g_bookmark_file_remove_application (GBookmarkFile *bookmark,
                                    const gchar *uri,
                                    const gchar *name,
                                    GError **error);

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

Parameters

bookmark	a GBookmarkFile
uri	a valid URI
name	the name of the application
error	return location for a GError or `NULL`

Returns

TRUE if the application was successfully removed.

Since: 2.12

g_bookmark_file_remove_item ()

gboolean
g_bookmark_file_remove_item (GBookmarkFile *bookmark,
                             const gchar *uri,
                             GError **error);

Removes the bookmark for uri from the bookmark file bookmark .

Parameters

bookmark	a GBookmarkFile
uri	a valid URI
error	return location for a GError, or `NULL`

Returns

TRUE if the bookmark was removed successfully.

Since: 2.12

g_bookmark_file_move_item ()

gboolean
g_bookmark_file_move_item (GBookmarkFile *bookmark,
                           const gchar *old_uri,
                           const gchar *new_uri,
                           GError **error);

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 NULL, then the bookmark is removed.

In the event the URI cannot be found, FALSE is returned and error is set to G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.

Parameters

bookmark	a GBookmarkFile
old_uri	a valid URI
new_uri	a valid URI, or `NULL`.	[nullable]
error	return location for a GError or `NULL`

Returns

TRUE if the URI was successfully changed

Since: 2.12

Types and Values

GBookmarkFile

typedef struct _GBookmarkFile GBookmarkFile;

An opaque data structure representing a set of bookmarks.

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 information on error domains.

enum GBookmarkFileError

Error codes returned by bookmark file parsing.

Members

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