GLib.BookmarkFile

Fields

None

Methods

class error_quark ()
  add_application (uri, name, exec_)
  add_group (uri, group)
  free ()
  get_added (uri)
  get_added_date_time (uri)
  get_app_info (uri, name)
  get_application_info (uri, name)
  get_applications (uri)
  get_description (uri)
  get_groups (uri)
  get_icon (uri)
  get_is_private (uri)
  get_mime_type (uri)
  get_modified (uri)
  get_modified_date_time (uri)
  get_size ()
  get_title (uri)
  get_uris ()
  get_visited (uri)
  get_visited_date_time (uri)
  has_application (uri, name)
  has_group (uri, group)
  has_item (uri)
  load_from_data (data)
  load_from_data_dirs (file)
  load_from_file (filename)
  move_item (old_uri, new_uri)
  remove_application (uri, name)
  remove_group (uri, group)
  remove_item (uri)
  set_added (uri, added)
  set_added_date_time (uri, added)
  set_app_info (uri, name, exec_, count, stamp)
  set_application_info (uri, name, exec_, count, stamp)
  set_description (uri, description)
  set_groups (uri, groups)
  set_icon (uri, href, mime_type)
  set_is_private (uri, is_private)
  set_mime_type (uri, mime_type)
  set_modified (uri, modified)
  set_modified_date_time (uri, modified)
  set_title (uri, title)
  set_visited (uri, visited)
  set_visited_date_time (uri, visited)
  to_data ()
  to_file (filename)

Details

class GLib.BookmarkFile

The GBookmarkFile structure contains only private data and should not be directly accessed.

classmethod error_quark()[source]
Return type:int
add_application(uri, name, exec_)[source]
Parameters:
  • uri (str) – a valid URI
  • name (str or None) – the name of the application registering the bookmark or None
  • exec (str or None) – command line to be used to launch the bookmark or None

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

Every bookmark inside a GLib.BookmarkFile 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 None, the name of the application will be the same returned by GLib.get_application_name(); if exec is None, the command line will be a composition of the program name as returned by GLib.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 self.

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

New in version 2.12.

add_group(uri, group)[source]
Parameters:
  • uri (str) – a valid URI
  • group (str) – the group name to be added

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.

New in version 2.12.

free()[source]

Frees a GLib.BookmarkFile.

New in version 2.12.

get_added(uri)[source]
Parameters:uri (str) – a valid URI
Raises:GLib.Error
Returns:a timestamp
Return type:int

Gets the time the bookmark for uri was added to self

In the event the URI cannot be found, -1 is returned and error is set to GLib.BookmarkFileError.URI_NOT_FOUND.

New in version 2.12.

Deprecated since version 2.66: Use GLib.BookmarkFile.get_added_date_time() instead, as time_t is deprecated due to the year 2038 problem.

get_added_date_time(uri)[source]
Parameters:uri (str) – a valid URI
Raises:GLib.Error
Returns:a GLib.DateTime
Return type:GLib.DateTime

Gets the time the bookmark for uri was added to self

In the event the URI cannot be found, None is returned and error is set to GLib.BookmarkFileError.URI_NOT_FOUND.

New in version 2.66.

get_app_info(uri, name)[source]
Parameters:
  • uri (str) – a valid URI
  • name (str) – an application’s name
Raises:

GLib.Error
Returns:

True on success.

exec_:return location for the command line of the application, or None
count:return location for the registration count, or None
stamp:return location for the last registration time, or None

Return type:

(bool, exec_: str, count: int, stamp: int)

Gets the registration information of app_name for the bookmark for uri. See GLib.BookmarkFile.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 GLib.BookmarkFileError.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 GLib.BookmarkFileError.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.

New in version 2.12.

Deprecated since version 2.66: Use GLib.BookmarkFile.get_application_info() instead, as time_t is deprecated due to the year 2038 problem.

get_application_info(uri, name)[source]
Parameters:
  • uri (str) – a valid URI
  • name (str) – an application’s name
Raises:

GLib.Error
Returns:

True on success.

exec_:return location for the command line of the application, or None
count:return location for the registration count, or None
stamp:return location for the last registration time, or None

Return type:

(bool, exec_: str, count: int, stamp: GLib.DateTime)

Gets the registration information of app_name for the bookmark for uri. See GLib.BookmarkFile.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 GLib.BookmarkFileError.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 GLib.BookmarkFileError.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.

New in version 2.66.

get_applications(uri)[source]
Parameters:uri (str) – a valid URI
Raises:GLib.Error
Returns:a newly allocated None-terminated array of strings. Use GLib.strfreev() to free it.
Return type:[str]

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

In the event the URI cannot be found, None is returned and error is set to GLib.BookmarkFileError.URI_NOT_FOUND.

New in version 2.12.

get_description(uri)[source]
Parameters:uri (str) – a valid URI
Raises:GLib.Error
Returns:a newly allocated string or None if the specified URI cannot be found.
Return type:str

Retrieves the description of the bookmark for uri.

In the event the URI cannot be found, None is returned and error is set to GLib.BookmarkFileError.URI_NOT_FOUND.

New in version 2.12.

get_groups(uri)[source]
Parameters:uri (str) – a valid URI
Raises:GLib.Error
Returns:a newly allocated None-terminated array of group names. Use GLib.strfreev() to free it.
Return type:[str]

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

In the event the URI cannot be found, None is returned and error is set to GLib.BookmarkFileError.URI_NOT_FOUND.

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

New in version 2.12.

get_icon(uri)[source]
Parameters:uri (str) – a valid URI
Raises:GLib.Error
Returns:True if the icon for the bookmark for the URI was found. You should free the returned strings.
href:return location for the icon’s location or None
mime_type:return location for the icon’s MIME type or None
Return type:(bool, href: str, mime_type: str)

Gets the icon of the bookmark for uri.

In the event the URI cannot be found, False is returned and error is set to GLib.BookmarkFileError.URI_NOT_FOUND.

New in version 2.12.

get_is_private(uri)[source]
Parameters:uri (str) – a valid URI
Raises:GLib.Error
Returns:True if the private flag is set, False otherwise.
Return type:bool

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 GLib.BookmarkFileError.URI_NOT_FOUND. In the event that the private flag cannot be found, False is returned and error is set to GLib.BookmarkFileError.INVALID_VALUE.

New in version 2.12.

get_mime_type(uri)[source]
Parameters:uri (str) – a valid URI
Raises:GLib.Error
Returns:a newly allocated string or None if the specified URI cannot be found.
Return type:str

Retrieves the MIME type of the resource pointed by uri.

In the event the URI cannot be found, None is returned and error is set to GLib.BookmarkFileError.URI_NOT_FOUND. In the event that the MIME type cannot be found, None is returned and error is set to GLib.BookmarkFileError.INVALID_VALUE.

New in version 2.12.

get_modified(uri)[source]
Parameters:uri (str) – a valid URI
Raises:GLib.Error
Returns:a timestamp
Return type:int

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 GLib.BookmarkFileError.URI_NOT_FOUND.

New in version 2.12.

Deprecated since version 2.66: Use GLib.BookmarkFile.get_modified_date_time() instead, as time_t is deprecated due to the year 2038 problem.

get_modified_date_time(uri)[source]
Parameters:uri (str) – a valid URI
Raises:GLib.Error
Returns:a GLib.DateTime
Return type:GLib.DateTime

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

In the event the URI cannot be found, None is returned and error is set to GLib.BookmarkFileError.URI_NOT_FOUND.

New in version 2.66.

get_size()[source]
Returns:the number of bookmarks
Return type:int

Gets the number of bookmarks inside self.

New in version 2.12.

get_title(uri)[source]
Parameters:uri (str or None) – a valid URI or None
Raises:GLib.Error
Returns:a newly allocated string or None if the specified URI cannot be found.
Return type:str

Returns the title of the bookmark for uri.

If uri is None, the title of self is returned.

In the event the URI cannot be found, None is returned and error is set to GLib.BookmarkFileError.URI_NOT_FOUND.

New in version 2.12.

get_uris()[source]
Returns:a newly allocated None-terminated array of strings. Use GLib.strfreev() to free it.
Return type:[str]

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

New in version 2.12.

get_visited(uri)[source]
Parameters:uri (str) – a valid URI
Raises:GLib.Error
Returns:a timestamp.
Return type:int

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 GLib.BookmarkFileError.URI_NOT_FOUND.

New in version 2.12.

Deprecated since version 2.66: Use GLib.BookmarkFile.get_visited_date_time() instead, as time_t is deprecated due to the year 2038 problem.

get_visited_date_time(uri)[source]
Parameters:uri (str) – a valid URI
Raises:GLib.Error
Returns:a GLib.DateTime
Return type:GLib.DateTime

Gets the time the bookmark for uri was last visited.

In the event the URI cannot be found, None is returned and error is set to GLib.BookmarkFileError.URI_NOT_FOUND.

New in version 2.66.

has_application(uri, name)[source]
Parameters:
  • uri (str) – a valid URI
  • name (str) – the name of the application
Raises:

GLib.Error
Returns:

True if the application name was found
Return type:

bool

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

In the event the URI cannot be found, False is returned and error is set to GLib.BookmarkFileError.URI_NOT_FOUND.

New in version 2.12.

has_group(uri, group)[source]
Parameters:
  • uri (str) – a valid URI
  • group (str) – the group name to be searched
Raises:

GLib.Error
Returns:

True if group was found.
Return type:

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, False is returned and error is set to GLib.BookmarkFileError.URI_NOT_FOUND.

New in version 2.12.

has_item(uri)[source]
Parameters:uri (str) – a valid URI
Returns:True if uri is inside self, False otherwise
Return type:bool

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

New in version 2.12.

load_from_data(data)[source]
Parameters:data (bytes) – desktop bookmarks loaded in memory
Raises:GLib.Error
Returns:True if a desktop bookmark could be loaded.
Return type:bool

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

New in version 2.12.

load_from_data_dirs(file)[source]
Parameters:file (str) – a relative path to a filename to open and parse
Raises:GLib.Error
Returns:True if a key file could be loaded, False otherwise
full_path:return location for a string containing the full path of the file, or None
Return type:(bool, full_path: str)

This function looks for a desktop bookmark file named file in the paths returned from GLib.get_user_data_dir() and GLib.get_system_data_dirs(), loads the file into self and returns the file’s full path in full_path. If the file could not be loaded then error is set to either a GLib.FileError or GLib.BookmarkFileError.

New in version 2.12.

load_from_file(filename)[source]
Parameters:filename (str) – the path of a filename to load, in the GLib file name encoding
Raises:GLib.Error
Returns:True if a desktop bookmark file could be loaded
Return type:bool

Loads a desktop bookmark file into an empty GLib.BookmarkFile structure. If the file could not be loaded then error is set to either a GLib.FileError or GLib.BookmarkFileError.

New in version 2.12.

move_item(old_uri, new_uri)[source]
Parameters:
  • old_uri (str) – a valid URI
  • new_uri (str or None) – a valid URI, or None
Raises:

GLib.Error
Returns:

True if the URI was successfully changed
Return type:

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

In the event the URI cannot be found, False is returned and error is set to GLib.BookmarkFileError.URI_NOT_FOUND.

New in version 2.12.

remove_application(uri, name)[source]
Parameters:
  • uri (str) – a valid URI
  • name (str) – the name of the application
Raises:

GLib.Error
Returns:

True if the application was successfully removed.
Return type:

bool

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

In the event the URI cannot be found, False is returned and error is set to GLib.BookmarkFileError.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 GLib.BookmarkFileError.APP_NOT_REGISTERED.

New in version 2.12.

remove_group(uri, group)[source]
Parameters:
  • uri (str) – a valid URI
  • group (str) – the group name to be removed
Raises:

GLib.Error
Returns:

True if group was successfully removed.
Return type:

bool

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 GLib.BookmarkFileError.URI_NOT_FOUND. In the event no group was defined, False is returned and error is set to GLib.BookmarkFileError.INVALID_VALUE.

New in version 2.12.

remove_item(uri)[source]
Parameters:uri (str) – a valid URI
Raises:GLib.Error
Returns:True if the bookmark was removed successfully.
Return type:bool

Removes the bookmark for uri from the bookmark file self.

New in version 2.12.

set_added(uri, added)[source]
Parameters:
  • uri (str) – a valid URI
  • added (int) – a timestamp or -1 to use the current time

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

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

New in version 2.12.

Deprecated since version 2.66: Use GLib.BookmarkFile.set_added_date_time() instead, as time_t is deprecated due to the year 2038 problem.

set_added_date_time(uri, added)[source]
Parameters:

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

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

New in version 2.66.

set_app_info(uri, name, exec_, count, stamp)[source]
Parameters:
  • uri (str) – a valid URI
  • name (str) – an application’s name
  • exec (str) – an application’s command line
  • count (int) – the number of registrations done for this application
  • stamp (int) – the time of the last registration for this application
Raises:

GLib.Error
Returns:

True if the application’s meta-data was successfully changed.
Return type:

bool

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

You should rarely use this function; use GLib.BookmarkFile.add_application() and GLib.BookmarkFile.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 GLib.BookmarkFile.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 GLib.BookmarkFileError.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 GLib.BookmarkFileError.APP_NOT_REGISTERED. Otherwise, if no bookmark for uri is found, one is created.

New in version 2.12.

Deprecated since version 2.66: Use GLib.BookmarkFile.set_application_info() instead, as time_t is deprecated due to the year 2038 problem.

set_application_info(uri, name, exec_, count, stamp)[source]
Parameters:
  • uri (str) – a valid URI
  • name (str) – an application’s name
  • exec (str) – an application’s command line
  • count (int) – the number of registrations done for this application
  • stamp (GLib.DateTime or None) – the time of the last registration for this application, which may be None if count is 0
Raises:

GLib.Error
Returns:

True if the application’s meta-data was successfully changed.
Return type:

bool

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

You should rarely use this function; use GLib.BookmarkFile.add_application() and GLib.BookmarkFile.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 GLib.BookmarkFile.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 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 GLib.BookmarkFileError.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 GLib.BookmarkFileError.APP_NOT_REGISTERED. Otherwise, if no bookmark for uri is found, one is created.

New in version 2.66.

set_description(uri, description)[source]
Parameters:
  • uri (str or None) – a valid URI or None
  • description (str) – a string

Sets description as the description of the bookmark for uri.

If uri is None, the description of self is set.

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

New in version 2.12.

set_groups(uri, groups)[source]
Parameters:
  • uri (str) – an item’s URI
  • groups ([str] or None) – an array of group names, or None to remove all groups

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.

New in version 2.12.

set_icon(uri, href, mime_type)[source]
Parameters:
  • uri (str) – a valid URI
  • href (str or None) – the URI of the icon for the bookmark, or None
  • mime_type (str) – the MIME type of the icon for the bookmark

Sets the icon for the bookmark for uri. If href is None, 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.

New in version 2.12.

set_is_private(uri, is_private)[source]
Parameters:
  • uri (str) – a valid URI
  • is_private (bool) – True if the bookmark should be marked as private

Sets the private flag of the bookmark for uri.

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

New in version 2.12.

set_mime_type(uri, mime_type)[source]
Parameters:
  • uri (str) – a valid URI
  • mime_type (str) – a 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.

New in version 2.12.

set_modified(uri, modified)[source]
Parameters:
  • uri (str) – a valid URI
  • modified (int) – a timestamp or -1 to use the current time

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

New in version 2.12.

Deprecated since version 2.66: Use GLib.BookmarkFile.set_modified_date_time() instead, as time_t is deprecated due to the year 2038 problem.

set_modified_date_time(uri, modified)[source]
Parameters:

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

New in version 2.66.

set_title(uri, title)[source]
Parameters:
  • uri (str or None) – a valid URI or None
  • title (str) – a UTF-8 encoded string

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

If uri is None, the title of self is set.

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

New in version 2.12.

set_visited(uri, visited)[source]
Parameters:
  • uri (str) – a valid URI
  • visited (int) – a timestamp or -1 to use the current time

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 GLib.BookmarkFile.get_application_info() or by the default application for the bookmark’s MIME type, retrieved using GLib.BookmarkFile.get_mime_type(). Changing the “visited” time does not affect the “modified” time.

New in version 2.12.

Deprecated since version 2.66: Use GLib.BookmarkFile.set_visited_date_time() instead, as time_t is deprecated due to the year 2038 problem.

set_visited_date_time(uri, visited)[source]
Parameters:

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 GLib.BookmarkFile.get_application_info() or by the default application for the bookmark’s MIME type, retrieved using GLib.BookmarkFile.get_mime_type(). Changing the “visited” time does not affect the “modified” time.

New in version 2.66.

to_data()[source]
Raises:GLib.Error
Returns:a newly allocated string holding the contents of the GLib.BookmarkFile
Return type:bytes

This function outputs self as a string.

New in version 2.12.

to_file(filename)[source]
Parameters:filename (str) – path of the output file
Raises:GLib.Error
Returns:True if the file was successfully written.
Return type:bool

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

New in version 2.12.