BookmarkFile

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.

A bookmark file might contain more than one bookmark; each bookmark is accessed through its URI.

The important caveat of bookmark files is that when you add a new bookmark you must also add the application that is registering it, using g_bookmark_file_add_application() or g_bookmark_file_set_app_info(). If a bookmark has no applications then it won't be dumped when creating the on disk representation, using g_bookmark_file_to_data() or g_bookmark_file_to_file().

The GBookmarkFile parser was added in GLib 2.12.

class BookmarkFile {

GBookmarkFile* gBookmarkFile;

GBookmarkFile* getBookmarkFileStruct();

void* getStruct();

this(GBookmarkFile* gBookmarkFile);

int loadFromFile(string filename);

int loadFromData(string data, gsize length);

int loadFromDataDirs(string file, string fullPath);

string toData();

int toFile(string filename);

int hasItem(string uri);

int hasGroup(string uri, string group);

int hasApplication(string uri, string name);

int getSize();

string[] getUris();

string getTitle(string uri);

string getDescription(string uri);

string getMimeType(string uri);

int getIsPrivate(string uri);

int getIcon(string uri, string href, string mimeType);

uint getAdded(string uri);

uint getModified(string uri);

uint getVisited(string uri);

string[] getGroups(string uri);

string[] getApplications(string uri);

int getAppInfo(string uri, string name, string exec, uint count, uint stamp);

void setTitle(string uri, string title);

void setDescription(string uri, string description);

void setMimeType(string uri, string mimeType);

void setIsPrivate(string uri, int isPrivate);

void setIcon(string uri, string href, string mimeType);

void setAdded(string uri, uint added);

void setGroups(string uri, string[] groups);

void setModified(string uri, uint modified);

void setVisited(string uri, uint visited);

int setAppInfo(string uri, string name, string exec, int count, uint stamp);

void addGroup(string uri, string group);

void addApplication(string uri, string name, string exec);

int removeGroup(string uri, string group);

int removeApplication(string uri, string name);

int removeItem(string uri);

int moveItem(string oldUri, string newUri);

}

Constructors

this this(GBookmarkFile* gBookmarkFile): Sets our main struct and passes it to the parent class
this this(): 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. Since 2.12

Destructor

~this ~this(): Undocumented in source.

Members

Functions

addApplication void addApplication(string uri, string name, string 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. Since 2.12
addGroup void addGroup(string uri, string 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. Since 2.12
free void free(): Frees a GBookmarkFile. Since 2.12
getAdded uint getAdded(string uri): 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. Since 2.12
getAppInfo int getAppInfo(string uri, string name, string exec, uint count, uint stamp): 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, 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. Since 2.12
getApplications string[] getApplications(string uri): 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. Since 2.12
getBookmarkFileStruct GBookmarkFile* getBookmarkFileStruct(): Undocumented in source. Be warned that the author may not have intended to support it.
getDescription string getDescription(string uri): 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. Since 2.12
getGroups string[] getGroups(string uri): 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. Since 2.12
getIcon int getIcon(string uri, string href, string mimeType): 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. Since 2.12
getIsPrivate int getIsPrivate(string uri): 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. Since 2.12
getMimeType string getMimeType(string uri): 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. Since 2.12
getModified uint getModified(string uri): 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. Since 2.12
getSize int getSize(): Gets the number of bookmarks inside bookmark. Since 2.12
getStruct void* getStruct(): the main Gtk struct as a void*
getTitle string getTitle(string uri): 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. Since 2.12
getUris string[] getUris(): 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. Since 2.12
getVisited uint getVisited(string uri): 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. Since 2.12
hasApplication int hasApplication(string uri, string name): 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. Since 2.12
hasGroup int hasGroup(string uri, string group): 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. Since 2.12
hasItem int hasItem(string uri): Looks whether the desktop bookmark has an item with its URI set to uri. Since 2.12
loadFromData int loadFromData(string data, gsize length): Loads a bookmark file from memory into an empty GBookmarkFile structure. If the object cannot be created then error is set to a GBookmarkFileError. Since 2.12
loadFromDataDirs int loadFromDataDirs(string file, string fullPath): This function looks for a desktop bookmark file named file in the paths returned from g_get_user_data_dir() and g_get_system_data_dirs(), loads the file into bookmark and returns the file's full path in full_path. If the file could not be loaded then an error is set to either a GFileError or GBookmarkFileError. Since 2.12
loadFromFile int loadFromFile(string filename): 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. Since 2.12
moveItem int moveItem(string oldUri, string newUri): 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. Since 2.12
removeApplication int removeApplication(string uri, string name): 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, 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. Since 2.12
removeGroup int removeGroup(string uri, string group): 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. Since 2.12
removeItem int removeItem(string uri): Removes the bookmark for uri from the bookmark file bookmark. Since 2.12
setAdded void setAdded(string uri, uint added): Sets the time the bookmark for uri was added into bookmark. If no bookmark for uri is found then it is created. Since 2.12
setAppInfo int setAppInfo(string uri, string name, string exec, int count, uint stamp): 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, 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. Since 2.12
setDescription void setDescription(string uri, string 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. Since 2.12
setGroups void setGroups(string uri, string[] 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. Since 2.12
setIcon void setIcon(string uri, string href, string mimeType): 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. Since 2.12
setIsPrivate void setIsPrivate(string uri, int isPrivate): Sets the private flag of the bookmark for uri. If a bookmark for uri cannot be found then it is created. Since 2.12
setMimeType void setMimeType(string uri, string mimeType): Sets mime_type as the MIME type of the bookmark for uri. If a bookmark for uri cannot be found then it is created. Since 2.12
setModified void setModified(string uri, uint modified): 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(). Since 2.12
setTitle void setTitle(string uri, string 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. Since 2.12
setVisited void setVisited(string uri, uint visited): 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. Since 2.12
toData string toData(): This function outputs bookmark as a string. Since 2.12
toFile int toFile(string filename): This function outputs bookmark into a file. The write process is guaranteed to be atomic by using g_file_set_contents() internally. Since 2.12

Variables

gBookmarkFile GBookmarkFile* gBookmarkFile;: the main Gtk struct

Meta

Source

See Implementation

glib BookmarkFile classes

BookmarkFile