WebKitGTK+ Reference Manual: WebKitFaviconDatabase

## WebKitFaviconDatabase WebKitFaviconDatabase — A WebKit favicon database |

## Synopsis

                        WebKitFaviconDatabase;
    void                webkit_favicon_database_clear       (WebKitFaviconDatabase *database);
    void                webkit_favicon_database_get_favicon_pixbuf
                                                            (WebKitFaviconDatabase *database,
                                                             const gchar *page_uri,
                                                             guint width,
                                                             guint height,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    GdkPixbuf *         webkit_favicon_database_get_favicon_pixbuf_finish
                                                            (WebKitFaviconDatabase *database,
                                                             GAsyncResult *result,
                                                             GError **error);
    gchar *             webkit_favicon_database_get_favicon_uri
                                                            (WebKitFaviconDatabase *database,
                                                             const gchar *page_uri);
    const gchar *       webkit_favicon_database_get_path    (WebKitFaviconDatabase *database);
    GType               webkit_favicon_database_get_type    (void);
    void                webkit_favicon_database_set_path    (WebKitFaviconDatabase *database,
                                                             const gchar *path);
    GdkPixbuf *         webkit_favicon_database_try_get_favicon_pixbuf
                                                            (WebKitFaviconDatabase *database,
                                                             const gchar *page_uri,
                                                             guint width,
                                                             guint height);

## Object Hierarchy

      GObject
       +----WebKitFaviconDatabase

## Properties

      "path"                     gchar*                : Read / Write

## Signals

      "icon-loaded"                                    : Run Last

## Description

WebKitFaviconDatabase provides access to the icons associated with web sites.

WebKit will automatically look for available icons in link elements on opened pages as well as an existing favicon.ico and load the images found into a memory cache if possible. That cache is frozen to an on-disk database for persistence.

The database is disabled by default. In order for icons to be stored and accessed, you will need to set an icon database path using `webkit_favicon_database_set_path()`. Disable the database again passing `NULL` to the previous call.

If WebKitWebSettings::enable-private-browsing is `TRUE` new icons won't be added to the on-disk database and no existing icons will be deleted from it. Nevertheless, WebKit will still store them in the in-memory cache during the current execution.

## Details

### WebKitFaviconDatabase

    typedef struct _WebKitFaviconDatabase WebKitFaviconDatabase;

### webkit_favicon_database_clear ()

    void                webkit_favicon_database_clear       (WebKitFaviconDatabase *database);

Clears all icons from the database.

`database` : | a WebKitFaviconDatabase

Since 1.8

### webkit_favicon_database_get_favicon_pixbuf ()

    void                webkit_favicon_database_get_favicon_pixbuf
                                                            (WebKitFaviconDatabase *database,
                                                             const gchar *page_uri,
                                                             guint width,
                                                             guint height,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Asynchronously obtains a GdkPixbuf of the favicon for the given page URI. The advantage of this method over `webkit_favicon_database_try_get_favicon_pixbuf()` is that it always returns the cached icon if it's in the database asynchronously waiting for the icon to be read from the database.

This is an asynchronous method. When the operation is finished, callback will be invoked. You can then call `webkit_favicon_database_get_favicon_pixbuf_finish()` to get the result of the operation. See also `webkit_favicon_database_try_get_favicon_pixbuf()`.

If `width` and `height` are both 0 then this method will return the maximum available size for the icon. Note that if you specify a different size the icon will be scaled each time you call this function.

`database` : | a WebKitFaviconDatabase
`page_uri` : | URI of the page containing the icon
`width` : | the desired width for the icon
`height` : | the desired height for the icon
`cancellable` : | A GCancellable or `NULL`. [allow-none]
`callback` : | A GAsyncReadyCallback to call when the request is satisfied or `NULL` if you don't care about the result. [allow-none]
`user_data` : | The data to pass to `callback`.

Since 1.8

### webkit_favicon_database_get_favicon_pixbuf_finish ()

    GdkPixbuf *         webkit_favicon_database_get_favicon_pixbuf_finish
                                                            (WebKitFaviconDatabase *database,
                                                             GAsyncResult *result,
                                                             GError **error);

Finishes an operation started with `webkit_favicon_database_get_favicon_pixbuf()`.

`database` : | a WebKitFaviconDatabase
`result` : | A GAsyncResult obtained from the GAsyncReadyCallback passed to `webkit_favicon_database_get_favicon_pixbuf()`
`error` : | Return location for error or `NULL`. [allow-none]
Returns : | a new reference to a GdkPixbuf, or `NULL`. [transfer full]

Since 1.8

### webkit_favicon_database_get_favicon_uri ()

    gchar *             webkit_favicon_database_get_favicon_uri
                                                            (WebKitFaviconDatabase *database,
                                                             const gchar *page_uri);

Obtains the URI for the favicon for the given page URI. See also `webkit_web_view_get_icon_uri()`.

`database` : | a WebKitFaviconDatabase
`page_uri` : | URI of the page containing the icon
Returns : | a newly allocated URI for the favicon, or `NULL`

Since 1.8

### webkit_favicon_database_get_path ()

    const gchar *       webkit_favicon_database_get_path    (WebKitFaviconDatabase *database);

Determines the absolute path to the database folder on disk.

`database` : | a WebKitFaviconDatabase
Returns : | the absolute path of the database folder, or `NULL`

Since 1.8

### webkit_favicon_database_get_type ()

    GType               webkit_favicon_database_get_type    (void);

### webkit_favicon_database_set_path ()

    void                webkit_favicon_database_set_path    (WebKitFaviconDatabase *database,
                                                             const gchar *path);

Specifies the absolute path to the database folder on disk. The icon database will only be enabled after a call to this method.

Passing `NULL` or "" as path disables the icon database.

`database` : | a WebKitFaviconDatabase
`path` : | an absolute path to the icon database folder or `NULL` to disable the database. [allow-none]

Since 1.8

### webkit_favicon_database_try_get_favicon_pixbuf ()

    GdkPixbuf *         webkit_favicon_database_try_get_favicon_pixbuf
                                                            (WebKitFaviconDatabase *database,
                                                             const gchar *page_uri,
                                                             guint width,
                                                             guint height);

Obtains a GdkPixbuf of the favicon for the given page URI, or `NULL` if there is no icon for the given page or it hasn't been loaded from disk yet. Use `webkit_favicon_database_get_favicon_uri()` if you need to distinguish these cases. To make sure this method will return a valid icon when the given URI has one, you should connect to "icon-loaded" and use this function in the callback.

If `width` and `height` ar both 0 then this method will return the maximum available size for the icon. Note that if you specify a different size the icon will be scaled each time you call this function.

`database` : | a WebKitFaviconDatabase
`page_uri` : | URI of the page containing the icon
`width` : | the desired width for the icon
`height` : | the desired height for the icon
Returns : | a new reference to a GdkPixbuf, or `NULL` if the given URI doesn't have an icon or it hasn't been loaded yet. [transfer full]

Since 1.8

## Property Details

### The `"path"` property

      "path"                     gchar*                : Read / Write

The absolute path of the icon database folder.

Default value: NULL

Since 1.8

## Signal Details

### The `"icon-loaded"` signal

    void                user_function                      (WebKitFaviconDatabase *database,
                                                            gchar                 *frame_uri,
                                                            gpointer               user_data)      : Run Last

This signal is fired if an icon is loaded on any WebKitWebView. If you are only interested in a particular WebKitWebView see "icon-loaded".

Note that this signal carries the URI of the frame that loads the icon, while "icon-loaded" provides the URI of the favicon.

`database` : | the object on which the signal is emitted
`frame_uri` : | the URI of the main frame of a Web page containing the icon
`user_data` : | user data set when the signal handler was connected.

Since 1.8