
@c %start of fragment

@deftp Class <g-bookmark-file>
Opaque pointer.

@end deftp

@deffn Function g-bookmark-file-new  @result{}@tie{} (ret@tie{}@code{<g-bookmark-file>})
Creates a new empty @code{<g-bookmark-file>} object.

Use @code{g-bookmark-file-load-from-file}, @code{g-bookmark-file-load-from-data}
or @code{g-bookmark-file-load-from-data-dirs} to read an existing bookmark file.

@table @var
@item ret
an empty @code{<g-bookmark-file>}

@end table

Since 2.12

@end deffn

@deffn Function g-bookmark-file-load-from-file  (bookmark@tie{}@code{<g-bookmark-file>}) (filename@tie{}@code{mchars}) @result{}@tie{} (ret@tie{}@code{bool})
Loads a desktop bookmark file into an empty @code{<g-bookmark-file>} structure.
If the file could not be loaded then @var{error} is set to either a
@code{<g-file-error>} or @code{<g-bookmark-file-error>}.

@table @var
@item bookmark
an empty @code{<g-bookmark-file>} struct

@item filename
the path of a filename to load, in the GLib file name encoding

@item error
return location for a @code{<g-error>}, or @samp{@code{#f}}

@item ret
@samp{@code{#t}} if a desktop bookmark file could be loaded

@end table

Since 2.12

@end deffn

@deffn Function g-bookmark-file-load-from-data  (bookmark@tie{}@code{<g-bookmark-file>}) (data@tie{}@code{mchars}) @result{}@tie{} (ret@tie{}@code{bool})
Loads a bookmark file from memory into an empty @code{<g-bookmark-file>}
structure. If the object cannot be created then @var{error} is set to a
@code{<g-bookmark-file-error>}.

@table @var
@item bookmark
an empty @code{<g-bookmark-file>} struct

@item data
desktop bookmarks loaded in memory

@item length
the length of @var{data} in bytes

@item error
return location for a @code{<g-error>}, or @samp{@code{#f}}

@item ret
@samp{@code{#t}} if a desktop bookmark could be loaded.

@end table

Since 2.12

@end deffn

@deffn Function g-bookmark-file-load-from-data-dirs  (bookmark@tie{}@code{<g-bookmark-file>}) (file@tie{}@code{mchars}) @result{}@tie{} (ret@tie{}@code{bool}) (full_path@tie{}@code{mchars})
This function looks for a desktop bookmark file named @var{file} in the paths
returned from @code{g-get-user-data-dir} and @code{g-get-system-data-dirs},
loads the file into @var{bookmark} and returns the file's full path in
@var{full-path}. If the file could not be loaded then an @samp{error} is set to
either a @code{<g-file-error>} or @code{<g-bookmark-file-error>}.

@table @var
@item bookmark
a @code{<g-bookmark-file>}

@item file
a relative path to a filename to open and parse

@item full-path
return location for a string containing the full path of the file, or
@samp{@code{#f}}

@item error
return location for a @code{<g-error>}, or @samp{@code{#f}}

@item ret
@samp{@code{#t}} if a key file could be loaded, @samp{@code{#f}} othewise

@end table

Since 2.12

@end deffn

@deffn Function g-bookmark-file-to-data  (bookmark@tie{}@code{<g-bookmark-file>}) @result{}@tie{} (ret@tie{}@code{mchars})
This function outputs @var{bookmark} as a string.

@table @var
@item bookmark
a @code{<g-bookmark-file>}

@item length
return location for the length of the returned string, or @samp{@code{#f}}

@item error
return location for a @code{<g-error>}, or @samp{@code{#f}}

@item ret
a newly allocated string holding the contents of the @code{<g-bookmark-file>}

@end table

Since 2.12

@end deffn

@deffn Function g-bookmark-file-to-file  (bookmark@tie{}@code{<g-bookmark-file>}) (filename@tie{}@code{mchars}) @result{}@tie{} (ret@tie{}@code{bool})
This function outputs @var{bookmark} into a file. The write process is
guaranteed to be atomic by using @code{g-file-set-contents} internally.

@table @var
@item bookmark
a @code{<g-bookmark-file>}

@item filename
path of the output file

@item error
return location for a @code{<g-error>}, or @samp{@code{#f}}

@item ret
@samp{@code{#t}} if the file was successfully written.

@end table

Since 2.12

@end deffn

@deffn Function g-bookmark-file-has-item  (bookmark@tie{}@code{<g-bookmark-file>}) (uri@tie{}@code{mchars}) @result{}@tie{} (ret@tie{}@code{bool})
Looks whether the desktop bookmark has an item with its URI set to @var{uri}.

@table @var
@item bookmark
a @code{<g-bookmark-file>}

@item uri
a valid URI

@item ret
@samp{@code{#t}} if @var{uri} is inside @var{bookmark}, @samp{@code{#f}}
otherwise

@end table

Since 2.12

@end deffn

@deffn Function g-bookmark-file-has-group  (bookmark@tie{}@code{<g-bookmark-file>}) (uri@tie{}@code{mchars}) (group@tie{}@code{mchars}) @result{}@tie{} (ret@tie{}@code{bool})
Checks whether @var{group} appears in the list of groups to which the bookmark
for @var{uri} belongs to.

In the event the URI cannot be found, @samp{@code{#f}} is returned and
@var{error} is set to @code{<g-bookmark-file-error-uri-not-found>}.

@table @var
@item bookmark
a @code{<g-bookmark-file>}

@item uri
a valid URI

@item group
the group name to be searched

@item error
return location for a @code{<g-error>}, or @samp{@code{#f}}

@item ret
@samp{@code{#t}} if @var{group} was found.

@end table

Since 2.12

@end deffn

@deffn Function g-bookmark-file-has-application  (bookmark@tie{}@code{<g-bookmark-file>}) (uri@tie{}@code{mchars}) (name@tie{}@code{mchars}) @result{}@tie{} (ret@tie{}@code{bool})
Checks whether the bookmark for @var{uri} inside @var{bookmark} has been
registered by application @var{name}.

In the event the URI cannot be found, @samp{@code{#f}} is returned and
@var{error} is set to @code{<g-bookmark-file-error-uri-not-found>}.

@table @var
@item bookmark
a @code{<g-bookmark-file>}

@item uri
a valid URI

@item name
the name of the application

@item error
return location for a @code{<g-error>} or @samp{@code{#f}}

@item ret
@samp{@code{#t}} if the application @var{name} was found

@end table

Since 2.12

@end deffn

@deffn Function g-bookmark-file-get-size  (bookmark@tie{}@code{<g-bookmark-file>}) @result{}@tie{} (ret@tie{}@code{int})
Gets the number of bookmarks inside @var{bookmark}.

@table @var
@item bookmark
a @code{<g-bookmark-file>}

@item ret
the number of bookmarks

@end table

Since 2.12

@end deffn

@deffn Function g-bookmark-file-get-uris  (bookmark@tie{}@code{<g-bookmark-file>}) @result{}@tie{} (ret@tie{}@code{scm})
Returns all URIs of the bookmarks in the bookmark file @var{bookmark}. The array
of returned URIs will be @samp{@code{#f}}-terminated, so @var{length} may
optionally be @samp{@code{#f}}.

@table @var
@item bookmark
a @code{<g-bookmark-file>}

@item length
return location for the number of returned URIs, or @samp{@code{#f}}

@item ret
a newly allocated @samp{@code{#f}}-terminated array of strings. Use
@code{g-strfreev} to free it.

@end table

Since 2.12

@end deffn

@deffn Function g-bookmark-file-get-title  (bookmark@tie{}@code{<g-bookmark-file>}) (uri@tie{}@code{mchars}) @result{}@tie{} (ret@tie{}@code{mchars})
Returns the title of the bookmark for @var{uri}.

If @var{uri} is @samp{@code{#f}}, the title of @var{bookmark} is returned.

In the event the URI cannot be found, @samp{@code{#f}} is returned and
@var{error} is set to @code{<g-bookmark-file-error-uri-not-found>}.

@table @var
@item bookmark
a @code{<g-bookmark-file>}

@item uri
a valid URI or @samp{@code{#f}}

@item error
return location for a @code{<g-error>}, or @samp{@code{#f}}

@item ret
a newly allocated string or @samp{@code{#f}} if the specified URI cannot be
found.

@end table

Since 2.12

@end deffn

@deffn Function g-bookmark-file-get-description  (bookmark@tie{}@code{<g-bookmark-file>}) (uri@tie{}@code{mchars}) @result{}@tie{} (ret@tie{}@code{mchars})
Retrieves the description of the bookmark for @var{uri}.

In the event the URI cannot be found, @samp{@code{#f}} is returned and
@var{error} is set to @code{<g-bookmark-file-error-uri-not-found>}.

@table @var
@item bookmark
a @code{<g-bookmark-file>}

@item uri
a valid URI

@item error
return location for a @code{<g-error>}, or @samp{@code{#f}}

@item ret
a newly allocated string or @samp{@code{#f}} if the specified URI cannot be
found.

@end table

Since 2.12

@end deffn

@deffn Function g-bookmark-file-get-mime-type  (bookmark@tie{}@code{<g-bookmark-file>}) (uri@tie{}@code{mchars}) @result{}@tie{} (ret@tie{}@code{mchars})
Retrieves the MIME type of the resource pointed by @var{uri}.

In the event the URI cannot be found, @samp{@code{#f}} is returned and
@var{error} is set to @code{<g-bookmark-file-error-uri-not-found>}. In the event
that the MIME type cannot be found, @samp{@code{#f}} is returned and @var{error}
is set to @code{<g-bookmark-file-error-invalid-value>}.

@table @var
@item bookmark
a @code{<g-bookmark-file>}

@item uri
a valid URI

@item error
return location for a @code{<g-error>}, or @samp{@code{#f}}

@item ret
a newly allocated string or @samp{@code{#f}} if the specified URI cannot be
found.

@end table

Since 2.12

@end deffn

@deffn Function g-bookmark-file-get-is-private  (bookmark@tie{}@code{<g-bookmark-file>}) (uri@tie{}@code{mchars}) @result{}@tie{} (ret@tie{}@code{bool})
Gets whether the private flag of the bookmark for @var{uri} is set.

In the event the URI cannot be found, @samp{@code{#f}} is returned and
@var{error} is set to @code{<g-bookmark-file-error-uri-not-found>}. In the event
that the private flag cannot be found, @samp{@code{#f}} is returned and
@var{error} is set to @code{<g-bookmark-file-error-invalid-value>}.

@table @var
@item bookmark
a @code{<g-bookmark-file>}

@item uri
a valid URI

@item error
return location for a @code{<g-error>}, or @samp{@code{#f}}

@item ret
@samp{@code{#t}} if the private flag is set, @samp{@code{#f}} otherwise.

@end table

Since 2.12

@end deffn

@deffn Function g-bookmark-file-get-icon  (bookmark@tie{}@code{<g-bookmark-file>}) (uri@tie{}@code{mchars}) @result{}@tie{} (ret@tie{}@code{bool}) (href@tie{}@code{mchars}) (mime_type@tie{}@code{mchars})
Gets the icon of the bookmark for @var{uri}.

In the event the URI cannot be found, @samp{@code{#f}} is returned and
@var{error} is set to @code{<g-bookmark-file-error-uri-not-found>}.

@table @var
@item bookmark
a @code{<g-bookmark-file>}

@item uri
a valid URI

@item href
return location for the icon's location or @samp{@code{#f}}

@item mime-type
return location for the icon's MIME type or @samp{@code{#f}}

@item error
return location for a @code{<g-error>} or @samp{@code{#f}}

@item ret
@samp{@code{#t}} if the icon for the bookmark for the URI was found. You should
free the returned strings.

@end table

Since 2.12

@end deffn

@deffn Function g-bookmark-file-get-added  (bookmark@tie{}@code{<g-bookmark-file>}) (uri@tie{}@code{mchars}) @result{}@tie{} (ret@tie{}@code{long})
Gets the time the bookmark for @var{uri} was added to @var{bookmark}

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

@table @var
@item bookmark
a @code{<g-bookmark-file>}

@item uri
a valid URI

@item error
return location for a @code{<g-error>}, or @samp{@code{#f}}

@item ret
a timestamp

@end table

Since 2.12

@end deffn

@deffn Function g-bookmark-file-get-modified  (bookmark@tie{}@code{<g-bookmark-file>}) (uri@tie{}@code{mchars}) @result{}@tie{} (ret@tie{}@code{long})
Gets the time when the bookmark for @var{uri} was last modified.

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

@table @var
@item bookmark
a @code{<g-bookmark-file>}

@item uri
a valid URI

@item error
return location for a @code{<g-error>}, or @samp{@code{#f}}

@item ret
a timestamp

@end table

Since 2.12

@end deffn

@deffn Function g-bookmark-file-get-visited  (bookmark@tie{}@code{<g-bookmark-file>}) (uri@tie{}@code{mchars}) @result{}@tie{} (ret@tie{}@code{long})
Gets the time the bookmark for @var{uri} was last visited.

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

@table @var
@item bookmark
a @code{<g-bookmark-file>}

@item uri
a valid URI

@item error
return location for a @code{<g-error>}, or @samp{@code{#f}}

@item ret
a timestamp.

@end table

Since 2.12

@end deffn

@deffn Function g-bookmark-file-get-groups  (bookmark@tie{}@code{<g-bookmark-file>}) (uri@tie{}@code{mchars}) @result{}@tie{} (ret@tie{}@code{scm})
Retrieves the list of group names of the bookmark for @var{uri}.

In the event the URI cannot be found, @samp{@code{#f}} is returned and
@var{error} is set to @code{<g-bookmark-file-error-uri-not-found>}.

The returned array is @samp{@code{#f}} terminated, so @var{length} may
optionally be @samp{@code{#f}}.

@table @var
@item bookmark
a @code{<g-bookmark-file>}

@item uri
a valid URI

@item length
return location for the length of the returned string, or @samp{@code{#f}}

@item error
return location for a @code{<g-error>}, or @samp{@code{#f}}

@item ret
a newly allocated @samp{@code{#f}}-terminated array of group names. Use
@code{g-strfreev} to free it.

@end table

Since 2.12

@end deffn

@deffn Function g-bookmark-file-get-applications  (bookmark@tie{}@code{<g-bookmark-file>}) (uri@tie{}@code{mchars}) @result{}@tie{} (ret@tie{}@code{scm})
Retrieves the names of the applications that have registered the bookmark for
@var{uri}.

In the event the URI cannot be found, @samp{@code{#f}} is returned and
@var{error} is set to @code{<g-bookmark-file-error-uri-not-found>}.

@table @var
@item bookmark
a @code{<g-bookmark-file>}

@item uri
a valid URI

@item length
return location of the length of the returned list, or @samp{@code{#f}}

@item error
return location for a @code{<g-error>}, or @samp{@code{#f}}

@item ret
a newly allocated @samp{@code{#f}}-terminated array of strings. Use
@code{g-strfreev} to free it.

@end table

Since 2.12

@end deffn

@deffn Function g-bookmark-file-get-app-info  (bookmark@tie{}@code{<g-bookmark-file>}) (uri@tie{}@code{mchars}) (name@tie{}@code{mchars}) @result{}@tie{} (ret@tie{}@code{bool}) (exec@tie{}@code{mchars}) (count@tie{}@code{unsigned-int}) (stamp@tie{}@code{long})
Gets the registration informations of @var{app-name} for the bookmark for
@var{uri}. See @code{g-bookmark-file-set-app-info} for more informations about
the returned data.

The string returned in @var{app-exec} must be freed.

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

@table @var
@item bookmark
a @code{<g-bookmark-file>}

@item uri
a valid URI

@item name
an application's name

@item exec
location for the command line of the application, or @samp{@code{#f}}

@item count
return location for the registration count, or @samp{@code{#f}}

@item stamp
return location for the last registration time, or @samp{@code{#f}}

@item error
return location for a @code{<g-error>}, or @samp{@code{#f}}

@item ret
@samp{@code{#t}} on success.

@end table

Since 2.12

@end deffn

@deffn Function g-bookmark-file-set-title  (bookmark@tie{}@code{<g-bookmark-file>}) (uri@tie{}@code{mchars}) (title@tie{}@code{mchars})
Sets @var{title} as the title of the bookmark for @var{uri} inside the bookmark
file @var{bookmark}.

If @var{uri} is @samp{@code{#f}}, the title of @var{bookmark} is set.

If a bookmark for @var{uri} cannot be found then it is created.

@table @var
@item bookmark
a @code{<g-bookmark-file>}

@item uri
a valid URI or @samp{@code{#f}}

@item title
a UTF-8 encoded string

@end table

Since 2.12

@end deffn

@deffn Function g-bookmark-file-set-description  (bookmark@tie{}@code{<g-bookmark-file>}) (uri@tie{}@code{mchars}) (description@tie{}@code{mchars})
Sets @var{description} as the description of the bookmark for @var{uri}.

If @var{uri} is @samp{@code{#f}}, the description of @var{bookmark} is set.

If a bookmark for @var{uri} cannot be found then it is created.

@table @var
@item bookmark
a @code{<g-bookmark-file>}

@item uri
a valid URI or @samp{@code{#f}}

@item description
a string

@end table

Since 2.12

@end deffn

@deffn Function g-bookmark-file-set-mime-type  (bookmark@tie{}@code{<g-bookmark-file>}) (uri@tie{}@code{mchars}) (mime_type@tie{}@code{mchars})
Sets @var{mime-type} as the MIME type of the bookmark for @var{uri}.

If a bookmark for @var{uri} cannot be found then it is created.

@table @var
@item bookmark
a @code{<g-bookmark-file>}

@item uri
a valid URI

@item mime-type
a MIME type

@end table

Since 2.12

@end deffn

@deffn Function g-bookmark-file-set-is-private  (bookmark@tie{}@code{<g-bookmark-file>}) (uri@tie{}@code{mchars}) (is_private@tie{}@code{bool})
Sets the private flag of the bookmark for @var{uri}.

If a bookmark for @var{uri} cannot be found then it is created.

@table @var
@item bookmark
a @code{<g-bookmark-file>}

@item uri
a valid URI

@item is-private
@samp{@code{#t}} if the bookmark should be marked as private

@end table

Since 2.12

@end deffn

@deffn Function g-bookmark-file-set-icon  (bookmark@tie{}@code{<g-bookmark-file>}) (uri@tie{}@code{mchars}) (href@tie{}@code{mchars}) (mime_type@tie{}@code{mchars})
Sets the icon for the bookmark for @var{uri}. If @var{href} is @samp{@code{#f}},
unsets the currently set icon.

If no bookmark for @var{uri} is found it is created.

@table @var
@item bookmark
a @code{<g-bookmark-file>}

@item uri
a valid URI

@item href
the URI of the icon for the bookmark, or @samp{@code{#f}}

@item mime-type
the MIME type of the icon for the bookmark

@end table

Since 2.12

@end deffn

@deffn Function g-bookmark-file-set-added  (bookmark@tie{}@code{<g-bookmark-file>}) (uri@tie{}@code{mchars}) (added@tie{}@code{long})
Sets the time the bookmark for @var{uri} was added into @var{bookmark}.

If no bookmark for @var{uri} is found then it is created.

@table @var
@item bookmark
a @code{<g-bookmark-file>}

@item uri
a valid URI

@item added
a timestamp or -1 to use the current time

@end table

Since 2.12

@end deffn

@deffn Function g-bookmark-file-set-modified  (bookmark@tie{}@code{<g-bookmark-file>}) (uri@tie{}@code{mchars}) (modified@tie{}@code{long})
Sets the last time the bookmark for @var{uri} was last modified.

If no bookmark for @var{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 @code{<g-bookmark-file>} that modifies a
bookmark also changes the modification time, except for
@code{g-bookmark-file-set-visited}.

@table @var
@item bookmark
a @code{<g-bookmark-file>}

@item uri
a valid URI

@item modified
a timestamp or -1 to use the current time

@end table

Since 2.12

@end deffn

@deffn Function g-bookmark-file-set-visited  (bookmark@tie{}@code{<g-bookmark-file>}) (uri@tie{}@code{mchars}) (visited@tie{}@code{long})
Sets the time the bookmark for @var{uri} was last visited.

If no bookmark for @var{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 @code{g-bookmark-file-get-app-info} or by the
default application for the bookmark's MIME type, retrieved using
@code{g-bookmark-file-get-mime-type}. Changing the "visited" time does not
affect the "modified" time.

@table @var
@item bookmark
a @code{<g-bookmark-file>}

@item uri
a valid URI

@item visited
a timestamp or -1 to use the current time

@end table

Since 2.12

@end deffn

@deffn Function g-bookmark-file-set-app-info  (bookmark@tie{}@code{<g-bookmark-file>}) (uri@tie{}@code{mchars}) (name@tie{}@code{mchars}) (exec@tie{}@code{mchars}) (count@tie{}@code{int}) (stamp@tie{}@code{long}) @result{}@tie{} (ret@tie{}@code{bool})
Sets the meta-data of application @var{name} inside the list of applications
that have registered a bookmark for @var{uri} inside @var{bookmark}.

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

@var{name} can be any UTF-8 encoded string used to identify an application.
@var{exec} can have one of these two modifiers: "@samp{f}", which will be
expanded as the local file name retrieved from the bookmark's URI; "@samp{u}",
which will be expanded as the bookmark's URI. The expansion is done
automatically when retrieving the stored command line using the
@code{g-bookmark-file-get-app-info} function. @var{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 @var{name} will be
removed from the list of registered applications. @var{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 @var{uri} is found, @samp{@code{#f}} is returned and
@var{error} is set to @code{<g-bookmark-file-error-uri-not-found>}; similarly,
in the event that no application @var{name} has registered a bookmark for
@var{uri}, @samp{@code{#f}} is returned and error is set to
@code{<g-bookmark-file-error-app-not-registered>}. Otherwise, if no bookmark for
@var{uri} is found, one is created.

@table @var
@item bookmark
a @code{<g-bookmark-file>}

@item uri
a valid URI

@item name
an application's name

@item exec
an application's command line

@item count
the number of registrations done for this application

@item stamp
the time of the last registration for this application

@item error
return location for a @code{<g-error>} or @samp{@code{#f}}

@item ret
@samp{@code{#t}} if the application's meta-data was successfully changed.

@end table

Since 2.12

@end deffn

@deffn Function g-bookmark-file-add-group  (bookmark@tie{}@code{<g-bookmark-file>}) (uri@tie{}@code{mchars}) (group@tie{}@code{mchars})
Adds @var{group} to the list of groups to which the bookmark for @var{uri}
belongs to.

If no bookmark for @var{uri} is found then it is created.

@table @var
@item bookmark
a @code{<g-bookmark-file>}

@item uri
a valid URI

@item group
the group name to be added

@end table

Since 2.12

@end deffn

@deffn Function g-bookmark-file-add-application  (bookmark@tie{}@code{<g-bookmark-file>}) (uri@tie{}@code{mchars}) (name@tie{}@code{mchars}) (exec@tie{}@code{mchars})
Adds the application with @var{name} and @var{exec} to the list of applications
that have registered a bookmark for @var{uri} into @var{bookmark}.

Every bookmark inside a @code{<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 @var{name} is @samp{@code{#f}}, the name of the application will be the same
returned by @code{g-get-application}; if @var{exec} is @samp{@code{#f}}, the
command line will be a composition of the program name as returned by
@code{g-get-prgname} and the "@samp{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 @var{name} had already
registered a bookmark for @var{uri} inside @var{bookmark}.

If no bookmark for @var{uri} is found, one is created.

@table @var
@item bookmark
a @code{<g-bookmark-file>}

@item uri
a valid URI

@item name
the name of the application registering the bookmark or @samp{@code{#f}}

@item exec
command line to be used to launch the bookmark or @samp{@code{#f}}

@end table

Since 2.12

@end deffn

@deffn Function g-bookmark-file-remove-group  (bookmark@tie{}@code{<g-bookmark-file>}) (uri@tie{}@code{mchars}) (group@tie{}@code{mchars}) @result{}@tie{} (ret@tie{}@code{bool})
Removes @var{group} from the list of groups to which the bookmark for @var{uri}
belongs to.

In the event the URI cannot be found, @samp{@code{#f}} is returned and
@var{error} is set to @code{<g-bookmark-file-error-uri-not-found>}. In the event
no group was defined, @samp{@code{#f}} is returned and @var{error} is set to
@code{<g-bookmark-file-error-invalid-value>}.

@table @var
@item bookmark
a @code{<g-bookmark-file>}

@item uri
a valid URI

@item group
the group name to be removed

@item error
return location for a @code{<g-error>}, or @samp{@code{#f}}

@item ret
@samp{@code{#t}} if @var{group} was successfully removed.

@end table

Since 2.12

@end deffn

@deffn Function g-bookmark-file-remove-application  (bookmark@tie{}@code{<g-bookmark-file>}) (uri@tie{}@code{mchars}) (name@tie{}@code{mchars}) @result{}@tie{} (ret@tie{}@code{bool})
Removes application registered with @var{name} from the list of applications
that have registered a bookmark for @var{uri} inside @var{bookmark}.

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

@table @var
@item bookmark
a @code{<g-bookmark-file>}

@item uri
a valid URI

@item name
the name of the application

@item error
return location for a @code{<g-error>} or @samp{@code{#f}}

@item ret
@samp{@code{#t}} if the application was successfully removed.

@end table

Since 2.12

@end deffn

@deffn Function g-bookmark-file-remove-item  (bookmark@tie{}@code{<g-bookmark-file>}) (uri@tie{}@code{mchars}) @result{}@tie{} (ret@tie{}@code{bool})
Removes the bookmark for @var{uri} from the bookmark file @var{bookmark}.

@table @var
@item bookmark
a @code{<g-bookmark-file>}

@item uri
a valid URI

@item error
return location for a @code{<g-error>}, or @samp{@code{#f}}

@item ret
@samp{@code{#t}} if the bookmark was removed successfully.

@end table

Since 2.12

@end deffn

@deffn Function g-bookmark-file-move-item  (bookmark@tie{}@code{<g-bookmark-file>}) (old_uri@tie{}@code{mchars}) (new_uri@tie{}@code{mchars}) @result{}@tie{} (ret@tie{}@code{bool})
Changes the URI of a bookmark item from @var{old-uri} to @var{new-uri}. Any
existing bookmark for @var{new-uri} will be overwritten. If @var{new-uri} is
@samp{@code{#f}}, then the bookmark is removed.

In the event the URI cannot be found, @samp{@code{#f}} is returned and
@var{error} is set to @code{<g-bookmark-file-error-uri-not-found>}.

@table @var
@item bookmark
a @code{<g-bookmark-file>}

@item old-uri
a valid URI

@item new-uri
a valid URI, or @samp{@code{#f}}

@item error
return location for a @code{<g-error>} or @samp{@code{#f}}

@item ret
@samp{@code{#t}} if the URI was successfully changed

@end table

Since 2.12

@end deffn


@c %end of fragment
