WebKit2GTK+ Reference Manual: WebKitFaviconDatabase

## WebKitFaviconDatabase WebKitFaviconDatabase — A WebKit favicon database |

## Synopsis

    struct              WebKitFaviconDatabase;
    #define             WEBKIT_FAVICON_DATABASE_ERROR
    enum                WebKitFaviconDatabaseError;
    void                webkit_favicon_database_get_favicon (WebKitFaviconDatabase *database,
                                                             const gchar *page_uri,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    cairo_surface_t *   webkit_favicon_database_get_favicon_finish
                                                            (WebKitFaviconDatabase *database,
                                                             GAsyncResult *result,
                                                             GError **error);
    gchar *             webkit_favicon_database_get_favicon_uri
                                                            (WebKitFaviconDatabase *database,
                                                             const gchar *page_uri);
    void                webkit_favicon_database_clear       (WebKitFaviconDatabase *database);

## Object Hierarchy

      GObject
       +----WebKitFaviconDatabase

## Signals

      "favicon-changed"                                : 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.

If "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

### struct WebKitFaviconDatabase

    struct WebKitFaviconDatabase;

### WEBKIT_FAVICON_DATABASE_ERROR

    #define WEBKIT_FAVICON_DATABASE_ERROR           (webkit_favicon_database_error_quark())

### enum WebKitFaviconDatabaseError

    typedef enum {
        WEBKIT_FAVICON_DATABASE_ERROR_NOT_INITIALIZED,
        WEBKIT_FAVICON_DATABASE_ERROR_FAVICON_NOT_FOUND,
        WEBKIT_FAVICON_DATABASE_ERROR_FAVICON_UNKNOWN
    } WebKitFaviconDatabaseError;

Enum values used to denote the various errors related to the WebKitFaviconDatabase.

`WEBKIT_FAVICON_DATABASE_ERROR_NOT_INITIALIZED` | The WebKitFaviconDatabase has not been initialized yet
`WEBKIT_FAVICON_DATABASE_ERROR_FAVICON_NOT_FOUND` | There is not an icon available for the requested URL
`WEBKIT_FAVICON_DATABASE_ERROR_FAVICON_UNKNOWN` | There might be an icon for the requested URL, but its data is unknown at the moment

### webkit_favicon_database_get_favicon ()

    void                webkit_favicon_database_get_favicon (WebKitFaviconDatabase *database,
                                                             const gchar *page_uri,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Asynchronously obtains a cairo_surface_t of the favicon for the given page URI. It 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_finish()` to get the result of the operation.

`database` : | a WebKitFaviconDatabase
`page_uri` : | URI of the page for which we want to retrieve the favicon
`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. [scope async]
`user_data` : | The data to pass to `callback`. [closure]

### webkit_favicon_database_get_favicon_finish ()

    cairo_surface_t *   webkit_favicon_database_get_favicon_finish
                                                            (WebKitFaviconDatabase *database,
                                                             GAsyncResult *result,
                                                             GError **error);

Finishes an operation started with `webkit_favicon_database_get_favicon()`.

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

### webkit_favicon_database_get_favicon_uri ()

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

Obtains the URI of the favicon for the given `page_uri`.

`database` : | a WebKitFaviconDatabase
`page_uri` : | URI of the page containing the icon
Returns : | a newly allocated URI for the favicon, or `NULL` if the database doesn't have a favicon for `page_uri`.

### webkit_favicon_database_clear ()

    void                webkit_favicon_database_clear       (WebKitFaviconDatabase *database);

Clears all icons from the database.

`database` : | a WebKitFaviconDatabase

## Signal Details

### The `"favicon-changed"` signal

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

This signal is emitted when the favicon URI of `page_uri` has been changed to `favicon_uri` in the database. You can connect to this signal and call `webkit_favicon_database_get_favicon()` to get the favicon. If you are interested in the favicon of a WebKitWebView it's easier to use the "favicon" property. See `webkit_web_view_get_favicon()` for more details.

`database` : | the object on which the signal is emitted
`page_uri` : | the URI of the Web page containing the icon
`favicon_uri` : | the URI of the favicon
`user_data` : | user data set when the signal handler was connected.