WebKitWebContext

WebKitWebContext — Manages aspects common to all WebKitWebViews

Functions

WebKitWebContext * webkit_web_context_get_default ()
WebKitCacheModel webkit_web_context_get_cache_model ()
void webkit_web_context_set_cache_model ()
void webkit_web_context_clear_cache ()
WebKitDownload * webkit_web_context_download_uri ()
WebKitCookieManager * webkit_web_context_get_cookie_manager ()
WebKitFaviconDatabase * webkit_web_context_get_favicon_database ()
void webkit_web_context_set_favicon_database_directory ()
const gchar * webkit_web_context_get_favicon_database_directory ()
WebKitSecurityManager * webkit_web_context_get_security_manager ()
void webkit_web_context_set_additional_plugins_directory ()
void webkit_web_context_get_plugins ()
GList * webkit_web_context_get_plugins_finish ()
gboolean webkit_web_context_get_spell_checking_enabled ()
void webkit_web_context_set_spell_checking_enabled ()
const gchar * const * webkit_web_context_get_spell_checking_languages ()
void webkit_web_context_set_spell_checking_languages ()
void webkit_web_context_set_preferred_languages ()
void webkit_web_context_set_tls_errors_policy ()
WebKitTLSErrorsPolicy webkit_web_context_get_tls_errors_policy ()
void webkit_web_context_set_web_extensions_directory ()
void webkit_web_context_set_web_extensions_initialization_user_data ()
void webkit_web_context_prefetch_dns ()
void webkit_web_context_set_disk_cache_directory ()
void webkit_web_context_allow_tls_certificate_for_host ()
WebKitProcessModel webkit_web_context_get_process_model ()
void webkit_web_context_set_process_model ()
void (*WebKitURISchemeRequestCallback) ()
void webkit_web_context_register_uri_scheme ()

Signals

void download-started Run Last
void initialize-web-extensions Run Last

Types and Values

Object Hierarchy

    GObject
    ╰── WebKitWebContext

Description

The WebKitWebContext manages all aspects common to all WebKitWebViews.

You can define the WebKitCacheModel and WebKitProcessModel with webkit_web_context_set_cache_model() and webkit_web_context_set_process_model(), depending on the needs of your application. You can access the WebKitCookieManager or the WebKitSecurityManager to specify the behaviour of your application regarding cookies and security, using webkit_web_context_get_cookie_manager() and webkit_web_context_get_security_manager() for that.

It is also possible to change your preferred language or enable spell checking, using webkit_web_context_set_preferred_languages(), webkit_web_context_set_spell_checking_languages() and webkit_web_context_set_spell_checking_enabled().

You can use webkit_web_context_register_uri_scheme() to register custom URI schemes, and manage several other settings.

Functions

webkit_web_context_get_default ()

WebKitWebContext *
webkit_web_context_get_default (void);

Gets the default web context

Returns

a WebKitWebContext.

[transfer none]


webkit_web_context_get_cache_model ()

WebKitCacheModel
webkit_web_context_get_cache_model (WebKitWebContext *context);

Returns the current cache model. For more information about this value check the documentation of the function webkit_web_context_set_cache_model().

Parameters

context

the WebKitWebContext

 

Returns

the current WebKitCacheModel


webkit_web_context_set_cache_model ()

void
webkit_web_context_set_cache_model (WebKitWebContext *context,
                                    WebKitCacheModel cache_model);

Specifies a usage model for WebViews, which WebKit will use to determine its caching behavior. All web views follow the cache model. This cache model determines the RAM and disk space to use for caching previously viewed content .

Research indicates that users tend to browse within clusters of documents that hold resources in common, and to revisit previously visited documents. WebKit and the frameworks below it include built-in caches that take advantage of these patterns, substantially improving document load speed in browsing situations. The WebKit cache model controls the behaviors of all of these caches, including various WebCore caches.

Browsers can improve document load speed substantially by specifying WEBKIT_CACHE_MODEL_WEB_BROWSER. Applications without a browsing interface can reduce memory usage substantially by specifying WEBKIT_CACHE_MODEL_DOCUMENT_VIEWER. The default value is WEBKIT_CACHE_MODEL_WEB_BROWSER.

Parameters

context

the WebKitWebContext

 

cache_model

a WebKitCacheModel

 

webkit_web_context_clear_cache ()

void
webkit_web_context_clear_cache (WebKitWebContext *context);

Clears all resources currently cached. See also webkit_web_context_set_cache_model().

Parameters

context

a WebKitWebContext

 

webkit_web_context_download_uri ()

WebKitDownload *
webkit_web_context_download_uri (WebKitWebContext *context,
                                 const gchar *uri);

Requests downloading of the specified URI string. The download operation will not be associated to any WebKitWebView, if you are interested in starting a download from a particular WebKitWebView use webkit_web_view_download_uri() instead.

Parameters

context

a WebKitWebContext

 

uri

the URI to download

 

Returns

a new WebKitDownload representing the the download operation.

[transfer full]


webkit_web_context_get_cookie_manager ()

WebKitCookieManager *
webkit_web_context_get_cookie_manager (WebKitWebContext *context);

Get the WebKitCookieManager of context .

Parameters

context

a WebKitWebContext

 

Returns

the WebKitCookieManager of context .

[transfer none]


webkit_web_context_get_favicon_database ()

WebKitFaviconDatabase *
webkit_web_context_get_favicon_database
                               (WebKitWebContext *context);

Get the WebKitFaviconDatabase associated with context .

To initialize the database you need to call webkit_web_context_set_favicon_database_directory().

Parameters

context

a WebKitWebContext

 

Returns

the WebKitFaviconDatabase of context .

[transfer none]


webkit_web_context_set_favicon_database_directory ()

void
webkit_web_context_set_favicon_database_directory
                               (WebKitWebContext *context,
                                const gchar *path);

Set the directory path to be used to store the favicons database for context on disk. Passing NULL as path means using the default directory for the platform (see g_get_user_data_dir()).

Calling this method also means enabling the favicons database for its use from the applications, so that's why it's expected to be called only once. Further calls for the same instance of WebKitWebContext won't cause any effect.

Parameters

context

a WebKitWebContext

 

path

an absolute path to the icon database directory or NULL to use the defaults.

[allow-none]

webkit_web_context_get_favicon_database_directory ()

const gchar *
webkit_web_context_get_favicon_database_directory
                               (WebKitWebContext *context);

Get the directory path being used to store the favicons database for context , or NULL if webkit_web_context_set_favicon_database_directory() hasn't been called yet.

This function will always return the same path after having called webkit_web_context_set_favicon_database_directory() for the first time.

Parameters

context

a WebKitWebContext

 

Returns

the path of the directory of the favicons database associated with context , or NULL.

[transfer none]


webkit_web_context_get_security_manager ()

WebKitSecurityManager *
webkit_web_context_get_security_manager
                               (WebKitWebContext *context);

Get the WebKitSecurityManager of context .

Parameters

context

a WebKitWebContext

 

Returns

the WebKitSecurityManager of context .

[transfer none]


webkit_web_context_set_additional_plugins_directory ()

void
webkit_web_context_set_additional_plugins_directory
                               (WebKitWebContext *context,
                                const gchar *directory);

Set an additional directory where WebKit will look for plugins.

Parameters

context

a WebKitWebContext

 

directory

the directory to add

 

webkit_web_context_get_plugins ()

void
webkit_web_context_get_plugins (WebKitWebContext *context,
                                GCancellable *cancellable,
                                GAsyncReadyCallback callback,
                                gpointer user_data);

Asynchronously get the list of installed plugins.

When the operation is finished, callback will be called. You can then call webkit_web_context_get_plugins_finish() to get the result of the operation.

Parameters

context

a WebKitWebContext

 

cancellable

a GCancellable or NULL to ignore.

[allow-none]

callback

a GAsyncReadyCallback to call when the request is satisfied.

[scope async]

user_data

the data to pass to callback function.

[closure]

webkit_web_context_get_plugins_finish ()

GList *
webkit_web_context_get_plugins_finish (WebKitWebContext *context,
                                       GAsyncResult *result,
                                       GError **error);

Finish an asynchronous operation started with webkit_web_context_get_plugins.

Parameters

context

a WebKitWebContext

 

result

a GAsyncResult

 

error

return location for error or NULL to ignore

 

Returns

a GList of WebKitPlugin. You must free the GList with g_list_free() and unref the WebKitPlugins with g_object_unref() when you're done with them.

[element-type WebKitPlugin][transfer full]


webkit_web_context_get_spell_checking_enabled ()

gboolean
webkit_web_context_get_spell_checking_enabled
                               (WebKitWebContext *context);

Get whether spell checking feature is currently enabled.

Parameters

context

a WebKitWebContext

 

Returns

TRUE If spell checking is enabled, or FALSE otherwise.


webkit_web_context_set_spell_checking_enabled ()

void
webkit_web_context_set_spell_checking_enabled
                               (WebKitWebContext *context,
                                gboolean enabled);

Enable or disable the spell checking feature.

Parameters

context

a WebKitWebContext

 

enabled

Value to be set

 

webkit_web_context_get_spell_checking_languages ()

const gchar * const *
webkit_web_context_get_spell_checking_languages
                               (WebKitWebContext *context);

Get the the list of spell checking languages associated with context , or NULL if no languages have been previously set.

See webkit_web_context_set_spell_checking_languages() for more details on the format of the languages in the list.

Parameters

context

a WebKitWebContext

 

Returns

A NULL-terminated array of languages if available, or NULL otherwise.

[array zero-terminated=1][element-type utf8][transfer none]


webkit_web_context_set_spell_checking_languages ()

void
webkit_web_context_set_spell_checking_languages
                               (WebKitWebContext *context,
                                const gchar * const *languages);

Set the list of spell checking languages to be used for spell checking.

The locale string typically is in the form lang_COUNTRY, where lang is an ISO-639 language code, and COUNTRY is an ISO-3166 country code. For instance, sv_FI for Swedish as written in Finland or pt_BR for Portuguese as written in Brazil.

You need to call this function with a valid list of languages at least once in order to properly enable the spell checking feature in WebKit.

Parameters

context

a WebKitWebContext

 

languages

a NULL-terminated list of spell checking languages.

[array zero-terminated=1][transfer none]

webkit_web_context_set_preferred_languages ()

void
webkit_web_context_set_preferred_languages
                               (WebKitWebContext *context,
                                const gchar * const *languages);

Set the list of preferred languages, sorted from most desirable to least desirable. The list will be used to build the "Accept-Language" header that will be included in the network requests started by the WebKitWebContext.

Parameters

context

a WebKitWebContext

 

languages

a NULL-terminated list of language identifiers.

[allow-none][array zero-terminated=1][element-type utf8][transfer none]

webkit_web_context_set_tls_errors_policy ()

void
webkit_web_context_set_tls_errors_policy
                               (WebKitWebContext *context,
                                WebKitTLSErrorsPolicy policy);

Set the TLS errors policy of context as policy

Parameters

context

a WebKitWebContext

 

policy

a WebKitTLSErrorsPolicy

 

webkit_web_context_get_tls_errors_policy ()

WebKitTLSErrorsPolicy
webkit_web_context_get_tls_errors_policy
                               (WebKitWebContext *context);

Get the TLS errors policy of context

Parameters

context

a WebKitWebContext

 

webkit_web_context_set_web_extensions_directory ()

void
webkit_web_context_set_web_extensions_directory
                               (WebKitWebContext *context,
                                const gchar *directory);

Set the directory where WebKit will look for Web Extensions. This method must be called before loading anything in this context, otherwise it will not have any effect. You can connect to “initialize-web-extensions” to call this method before anything is loaded.

Parameters

context

a WebKitWebContext

 

directory

the directory to add

 

webkit_web_context_set_web_extensions_initialization_user_data ()

void
webkit_web_context_set_web_extensions_initialization_user_data
                               (WebKitWebContext *context,
                                GVariant *user_data);

Set user data to be passed to Web Extensions on initialization. The data will be passed to the WebKitWebExtensionInitializeWithUserDataFunction. This method must be called before loading anything in this context, otherwise it will not have any effect. You can connect to “initialize-web-extensions” to call this method before anything is loaded.

Parameters

context

a WebKitWebContext

 

user_data

a GVariant

 

Since 2.4


webkit_web_context_prefetch_dns ()

void
webkit_web_context_prefetch_dns (WebKitWebContext *context,
                                 const gchar *hostname);

Resolve the domain name of the given hostname in advance, so that if a URI of hostname is requested the load will be performed more quickly.

Parameters

context

a WebKitWebContext

 

hostname

a hostname to be resolved

 

webkit_web_context_set_disk_cache_directory ()

void
webkit_web_context_set_disk_cache_directory
                               (WebKitWebContext *context,
                                const gchar *directory);

Set the directory where disk cache files will be stored This method must be called before loading anything in this context, otherwise it will not have any effect.

Parameters

context

a WebKitWebContext

 

directory

the directory to set

 

webkit_web_context_allow_tls_certificate_for_host ()

void
webkit_web_context_allow_tls_certificate_for_host
                               (WebKitWebContext *context,
                                GTlsCertificate *certificate,
                                const gchar *host);

Ignore further TLS errors on the host for the certificate present in info .

Parameters

context

a WebKitWebContext

 

certificate

a GTlsCertificate

 

host

the host for which a certificate is to be allowed

 

Since 2.6


webkit_web_context_get_process_model ()

WebKitProcessModel
webkit_web_context_get_process_model (WebKitWebContext *context);

Returns the current process model. For more information about this value see webkit_web_context_set_process_model().

Parameters

context

the WebKitWebContext

 

Returns

the current WebKitProcessModel

Since 2.4


webkit_web_context_set_process_model ()

void
webkit_web_context_set_process_model (WebKitWebContext *context,
                                      WebKitProcessModel process_model);

Specifies a process model for WebViews, which WebKit will use to determine how auxiliary processes are handled. The default setting (WEBKIT_PROCESS_MODEL_SHARED_SECONDARY_PROCESS) is suitable for most applications which embed a small amount of WebViews, or are used to display documents which are considered safe — like local files.

Applications which may potentially use a large amount of WebViews —for example a multi-tabbed web browser— may want to use WEBKIT_PROCESS_MODEL_MULTIPLE_SECONDARY_PROCESSES, which will use one process per view most of the time, while still allowing for web views to share a process when needed (for example when different views interact with each other). Using this model, when a process hangs or crashes, only the WebViews using it stop working, while the rest of the WebViews in the application will still function normally.

This method **must be called before any other functions**, as early as possible in your application. Calling it later will make your application crash.

Parameters

context

the WebKitWebContext

 

process_model

a WebKitProcessModel

 

Since 2.4


WebKitURISchemeRequestCallback ()

void
(*WebKitURISchemeRequestCallback) (WebKitURISchemeRequest *request,
                                   gpointer user_data);

Type definition for a function that will be called back when an URI request is made for a user registered URI scheme.

Parameters

request

the WebKitURISchemeRequest

 

user_data

user data passed to the callback

 

webkit_web_context_register_uri_scheme ()

void
webkit_web_context_register_uri_scheme
                               (WebKitWebContext *context,
                                const gchar *scheme,
                                WebKitURISchemeRequestCallback callback,
                                gpointer user_data,
                                GDestroyNotify user_data_destroy_func);

Register scheme in context , so that when an URI request with scheme is made in the WebKitWebContext, the WebKitURISchemeRequestCallback registered will be called with a WebKitURISchemeRequest. It is possible to handle URI scheme requests asynchronously, by calling g_object_ref() on the WebKitURISchemeRequest and calling webkit_uri_scheme_request_finish() later when the data of the request is available or webkit_uri_scheme_request_finish_error() in case of error.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
static void
about_uri_scheme_request_cb (WebKitURISchemeRequest *request,
                             gpointer                user_data)
{
    GInputStream *stream;
    gsize         stream_length;
    const gchar  *path;

    path = webkit_uri_scheme_request_get_path (request);
    if (!g_strcmp0 (path, "plugins")) {
        /* Create a GInputStream with the contents of plugins about page, and set its length to stream_length */
    } else if (!g_strcmp0 (path, "memory")) {
        /* Create a GInputStream with the contents of memory about page, and set its length to stream_length */
    } else if (!g_strcmp0 (path, "applications")) {
        /* Create a GInputStream with the contents of applications about page, and set its length to stream_length */
    } else if (!g_strcmp0 (path, "example")) {
        gchar *contents;

        contents = g_strdup_printf ("<html><body><p>Example about page</p></body></html>");
        stream_length = strlen (contents);
        stream = g_memory_input_stream_new_from_data (contents, stream_length, g_free);
    } else {
        GError *error;

        error = g_error_new (ABOUT_HANDLER_ERROR, ABOUT_HANDLER_ERROR_INVALID, "Invalid about:%s page.", path);
        webkit_uri_scheme_request_finish_error (request, error);
        g_error_free (error);
        return;
    }
    webkit_uri_scheme_request_finish (request, stream, stream_length, "text/html");
    g_object_unref (stream);
}

Parameters

context

a WebKitWebContext

 

scheme

the network scheme to register

 

callback

a WebKitURISchemeRequestCallback.

[scope async]

user_data

data to pass to callback function

 

user_data_destroy_func

destroy notify for user_data

 

Types and Values

struct WebKitWebContext

struct WebKitWebContext;


enum WebKitCacheModel

Enum values used for determining the WebKitWebContext cache model.

Members

WEBKIT_CACHE_MODEL_DOCUMENT_VIEWER

Disable the cache completely, which substantially reduces memory usage. Useful for applications that only access a single local file, with no navigation to other pages. No remote resources will be cached.

 

WEBKIT_CACHE_MODEL_WEB_BROWSER

Improve document load speed substantially by caching a very large number of resources and previously viewed content.

 

WEBKIT_CACHE_MODEL_DOCUMENT_BROWSER

A cache model optimized for viewing a series of local files -- for example, a documentation viewer or a website designer. WebKit will cache a moderate number of resources.

 

enum WebKitProcessModel

Enum values used for determining the WebKitWebContext process model.

Members

WEBKIT_PROCESS_MODEL_SHARED_SECONDARY_PROCESS

Use a single process to perform content rendering. The process is shared among all the WebKitWebView instances created by the application: if the process hangs or crashes all the web views in the application will be affected. This is the default process model, and it should suffice for most cases.

 

WEBKIT_PROCESS_MODEL_MULTIPLE_SECONDARY_PROCESSES

Use one process for each WebKitWebView, while still allowing for some of them to share a process in certain situations. The main advantage of this process model is that the rendering process for a web view can crash while the rest of the views keep working normally. This process model is indicated for applications which may use a number of web views and the content of in each must not interfere with the rest — for example a full-fledged web browser with support for multiple tabs.

 

Since 2.4


enum WebKitTLSErrorsPolicy

Enum values used to denote the TLS errors policy.

Members

WEBKIT_TLS_ERRORS_POLICY_IGNORE

Ignore TLS errors.

 

WEBKIT_TLS_ERRORS_POLICY_FAIL

TLS errors will emit “load-failed-with-tls-errors” and, if the signal is handled, finish the load. In case the signal is not handled, “load-failed” is emitted before the load finishes.

 

Signal Details

The “download-started” signal

void
user_function (WebKitWebContext *context,
               WebKitDownload   *download,
               gpointer          user_data)

This signal is emitted when a new download request is made.

Parameters

context

the WebKitWebContext

 

download

the WebKitDownload associated with this event

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “initialize-web-extensions” signal

void
user_function (WebKitWebContext *context,
               gpointer          user_data)

This signal is emitted when a new web process is about to be launched. It signals the most appropriate moment to use webkit_web_context_set_web_extensions_initialization_user_data() and webkit_web_context_set_web_extensions_directory().

Parameters

context

the WebKitWebContext

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

Since 2.4