WebKitGTK+ Reference Manual: WebKitFaviconDatabase

## WebKitFaviconDatabase WebKitFaviconDatabase — A WebKit favicon database |

## Functions

void | webkit_favicon_database_clear ()
void | webkit_favicon_database_get_favicon_pixbuf ()
GdkPixbuf * | webkit_favicon_database_get_favicon_pixbuf_finish ()
gchar * | webkit_favicon_database_get_favicon_uri ()
const gchar * | webkit_favicon_database_get_path ()
GType | webkit_favicon_database_get_type ()
void | webkit_favicon_database_set_path ()
GdkPixbuf * | webkit_favicon_database_try_get_favicon_pixbuf ()

## Properties

gchar * | path | Read / Write

## Signals

void | icon-loaded | Run Last

## Types and Values

| WebKitFaviconDatabase

## Object Hierarchy

        GObject
        ╰── WebKitFaviconDatabase

## 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.

## Functions

### webkit_favicon_database_clear ()

    void
    webkit_favicon_database_clear (WebKitFaviconDatabase *database);

Clears all icons from the database.

#### Parameters

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.

#### Parameters

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()`.

#### Parameters

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()`.

#### Parameters

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.

#### Parameters

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);

#### Returns

### 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.

#### Parameters

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.

#### Parameters

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

## Types and Values

### WebKitFaviconDatabase

    typedef struct _WebKitFaviconDatabase WebKitFaviconDatabase;

## Property Details

### The `“path”` property

      “path”                     gchar *

The absolute path of the icon database folder.

Flags: Read / Write

Default value: NULL

Since 1.8

## Signal Details

### The `“icon-loaded”` signal

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

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.

#### Parameters

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. |

Flags: Run Last

Since 1.8