GI.WebKit.Objects.WebContext

Manages aspects common to all WebViews

The WebContext manages all aspects common to all WebViews.

You can define the CacheModel with webContextSetCacheModel, depending on the needs of your application. You can access the SecurityManager to specify the behaviour of your application regarding security using webContextGetSecurityManager.

It is also possible to change your preferred language or enable spell checking, using webContextSetPreferredLanguages, webContextSetSpellCheckingLanguages and webContextSetSpellCheckingEnabled.

You can use webContextRegisterUriScheme to register custom URI schemes, and manage several other settings.

TLS certificate validation failure is now treated as a transport error by default. To handle TLS failures differently, you can connect to WebView::loadFailedWithTlsErrors. Alternatively, you can use webkit_web_context_set_tls_errors_policy() to set the policy TLSErrorsPolicyIgnore; however, this is not appropriate for Internet applications.

Exported types

newtype WebContext

Memory-managed wrapper type.

Constructors

WebContext (ManagedPtr WebContext)

Instances

Eq WebContext

Defined in GI.WebKit.Objects.WebContext

Methods

(==) :: WebContext -> WebContext -> Bool

(/=) :: WebContext -> WebContext -> Bool

GObject WebContext

Defined in GI.WebKit.Objects.WebContext

ManagedPtrNewtype WebContext

Defined in GI.WebKit.Objects.WebContext

Methods

toManagedPtr :: WebContext -> ManagedPtr WebContext

TypedObject WebContext

Defined in GI.WebKit.Objects.WebContext

Methods

glibType :: IO GType

HasParentTypes WebContext

Defined in GI.WebKit.Objects.WebContext

IsGValue (Maybe WebContext)

Convert WebContext to and from GValue. See toGValue and fromGValue.

Defined in GI.WebKit.Objects.WebContext

Methods

gvalueGType_ :: IO GType

gvalueSet_ :: Ptr GValue -> Maybe WebContext -> IO ()

gvalueGet_ :: Ptr GValue -> IO (Maybe WebContext)

type ParentTypes WebContext

Defined in GI.WebKit.Objects.WebContext

type ParentTypes WebContext = '[Object]

class (GObject o, IsDescendantOf WebContext o) => IsWebContext o

Type class for types which can be safely cast to WebContext, for instance with toWebContext.

Instances

(GObject o, IsDescendantOf WebContext o) => IsWebContext o

Defined in GI.WebKit.Objects.WebContext

toWebContext :: (MonadIO m, IsWebContext o) => o -> m WebContext

Cast to WebContext, for types for which this is known to be safe. For general casts, use castTo.

Methods

Click to display all available methods, including inherited ones

Methods

addPathToSandbox, bindProperty, bindPropertyFull, forceFloating, freezeNotify, getv, initializeNotificationPermissions, isAutomationAllowed, isFloating, notify, notifyByPspec, ref, refSink, registerUriScheme, runDispose, sendMessageToAllExtensions, stealData, stealQdata, thawNotify, unref, watchClosure.

Getters

getCacheModel, getData, getGeolocationManager, getNetworkSessionForAutomation, getProperty, getQdata, getSecurityManager, getSpellCheckingEnabled, getSpellCheckingLanguages, getTimeZoneOverride.

Setters

setAutomationAllowed, setCacheModel, setData, setDataFull, setPreferredLanguages, setProperty, setSpellCheckingEnabled, setSpellCheckingLanguages, setWebProcessExtensionsDirectory, setWebProcessExtensionsInitializationUserData.

addPathToSandbox

webContextAddPathToSandbox

Arguments

:: (HasCallStack, MonadIO m, IsWebContext a)

=> a

context: a WebContext

-> [Char]

path: an absolute path to mount in the sandbox

-> Bool

readOnly: if True the path will be read-only

-> m ()

Adds a path to be mounted in the sandbox.

path must exist before any web process has been created; otherwise, it will be silently ignored. It is a fatal error to add paths after a web process has been spawned.

Paths under /sys, /proc, and /dev are invalid. Attempting to add all of / is not valid. Since 2.40, adding the user's entire home directory or /home is also not valid.

See also webkit_web_context_set_sandbox_enabled()

Since: 2.26

getCacheModel

webContextGetCacheModel

Arguments

:: (HasCallStack, MonadIO m, IsWebContext a)

=> a

context: the WebContext

-> m CacheModel

Returns: the current CacheModel

Returns the current cache model.

For more information about this value check the documentation of the function webContextSetCacheModel.

getDefault

webContextGetDefault

Arguments

:: (HasCallStack, MonadIO m)

=> m WebContext

Returns: a WebContext

Gets the default web context.

getGeolocationManager

webContextGetGeolocationManager

Arguments

:: (HasCallStack, MonadIO m, IsWebContext a)

=> a

context: a WebContext

-> m GeolocationManager

Returns: the GeolocationManager of context.

Get the GeolocationManager of context.

Since: 2.26

getNetworkSessionForAutomation

webContextGetNetworkSessionForAutomation

Arguments

:: (HasCallStack, MonadIO m, IsWebContext a)

=> a

context: the WebContext

-> m (Maybe NetworkSession)

Returns: a NetworkSession, or Nothing if automation is not enabled

Get the NetworkSession used for automation sessions started in context.

Since: 2.40

getSecurityManager

webContextGetSecurityManager

Arguments

:: (HasCallStack, MonadIO m, IsWebContext a)

=> a

context: a WebContext

-> m SecurityManager

Returns: the SecurityManager of context.

Get the SecurityManager of context.

getSpellCheckingEnabled

webContextGetSpellCheckingEnabled

Arguments

:: (HasCallStack, MonadIO m, IsWebContext a)

=> a

context: a WebContext

-> m Bool

Returns: True If spell checking is enabled, or False otherwise.

Get whether spell checking feature is currently enabled.

getSpellCheckingLanguages

webContextGetSpellCheckingLanguages

Arguments

:: (HasCallStack, MonadIO m, IsWebContext a)

=> a

context: a WebContext

-> m [Text]

Returns: A Nothing-terminated array of languages if available, or Nothing otherwise.

Get the the list of spell checking languages.

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

See webContextSetSpellCheckingLanguages for more details on the format of the languages in the list.

getTimeZoneOverride

webContextGetTimeZoneOverride

Arguments

:: (HasCallStack, MonadIO m, IsWebContext a)

=> a

context: a WebContext

-> m Text

Get the WebContext:timeZoneOverride property.

Since: 2.38

initializeNotificationPermissions

webContextInitializeNotificationPermissions

Arguments

:: (HasCallStack, MonadIO m, IsWebContext a)

=> a

context: the WebContext

-> [SecurityOrigin]

allowedOrigins: a List of security origins

-> [SecurityOrigin]

disallowedOrigins: a List of security origins

-> m ()

Sets initial desktop notification permissions for the context.

allowedOrigins and disallowedOrigins must each be List of SecurityOrigin objects representing origins that will, respectively, either always or never have permission to show desktop notifications. No NotificationPermissionRequest will ever be generated for any of the security origins represented in allowedOrigins or disallowedOrigins. This function is necessary because some webpages proactively check whether they have permission to display notifications without ever creating a permission request.

This function only affects web processes that have not already been created. The best time to call it is when handling WebContext::initializeNotificationPermissions so as to ensure that new web processes receive the most recent set of permissions.

Since: 2.16

isAutomationAllowed

webContextIsAutomationAllowed

Arguments

:: (HasCallStack, MonadIO m, IsWebContext a)

=> a

context: the WebContext

-> m Bool

Returns: True if automation is allowed or False otherwise.

Get whether automation is allowed in context.

See also webContextSetAutomationAllowed.

Since: 2.18

new

webContextNew

Arguments

:: (HasCallStack, MonadIO m)

=> m WebContext

Returns: a newly created WebContext

Create a new WebContext.

Since: 2.8

registerUriScheme

webContextRegisterUriScheme

Arguments

:: (HasCallStack, MonadIO m, IsWebContext a)

=> a

context: a WebContext

-> Text

scheme: the network scheme to register

-> URISchemeRequestCallback

callback: a URISchemeRequestCallback

-> m ()

Register scheme in context.

Register scheme in context, so that when an URI request with scheme is made in the WebContext, the URISchemeRequestCallback registered will be called with a URISchemeRequest. It is possible to handle URI scheme requests asynchronously, by calling objectRef on the URISchemeRequest and calling uRISchemeRequestFinish later when the data of the request is available or uRISchemeRequestFinishError in case of error.

c code

static void
about_uri_scheme_request_cb (WebKitURISchemeRequest *request,
                             gpointer                user_data)
{
    GInputStream *stream;
    gsize         stream_length;
    const gchar  *path = webkit_uri_scheme_request_get_path (request);

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

sendMessageToAllExtensions

webContextSendMessageToAllExtensions

Arguments

:: (HasCallStack, MonadIO m, IsWebContext a, IsUserMessage b)

=> a

context: the WebContext

-> b

message: a UserMessage

-> m ()

Send message to all web process extensions associated to context.

If message is floating, it's consumed.

Since: 2.28

setAutomationAllowed

webContextSetAutomationAllowed

Arguments

:: (HasCallStack, MonadIO m, IsWebContext a)

=> a

context: the WebContext

-> Bool

allowed: value to set

-> m ()

Set whether automation is allowed in context.

When automation is enabled the browser could be controlled by another process by requesting an automation session. When a new automation session is requested the signal WebContext::automationStarted is emitted. Automation is disabled by default, so you need to explicitly call this method passing True to enable it.

Note that only one WebContext can have automation enabled, so this will do nothing if there's another WebContext with automation already enabled.

Since: 2.18

setCacheModel

webContextSetCacheModel

Arguments

:: (HasCallStack, MonadIO m, IsWebContext a)

=> a

context: the WebContext

-> CacheModel

cacheModel: a CacheModel

-> m ()

Specifies a usage model for WebViews.

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 CacheModelWebBrowser. Applications without a browsing interface can reduce memory usage substantially by specifying CacheModelDocumentViewer. The default value is CacheModelWebBrowser.

setPreferredLanguages

webContextSetPreferredLanguages

Arguments

:: (HasCallStack, MonadIO m, IsWebContext a)

=> a

context: a WebContext

-> Maybe [Text]

languages: a Nothing-terminated list of language identifiers

-> m ()

Set the list of preferred languages.

Set the list of preferred languages, sorted from most desirable to least desirable. The list will be used in the following ways:

• Determining how to build the Accept-Language HTTP header that will be included in the network requests started by the WebContext.
• Setting the values of navigator.language and navigator.languages.
• The first item in the list sets the default locale for JavaScript Intl functions.

setSpellCheckingEnabled

webContextSetSpellCheckingEnabled

Arguments

:: (HasCallStack, MonadIO m, IsWebContext a)

=> a

context: a WebContext

-> Bool

enabled: Value to be set

-> m ()

Enable or disable the spell checking feature.

setSpellCheckingLanguages

webContextSetSpellCheckingLanguages

Arguments

:: (HasCallStack, MonadIO m, IsWebContext a)

=> a

context: a WebContext

-> [Text]

languages: a Nothing-terminated list of spell checking languages

-> m ()

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.

setWebProcessExtensionsDirectory

webContextSetWebProcessExtensionsDirectory

Arguments

:: (HasCallStack, MonadIO m, IsWebContext a)

=> a

context: a WebContext

-> Text

directory: the directory to add

-> m ()

Set the directory where WebKit will look for web process extensions.

This method must be called before loading anything in this context, otherwise it will not have any effect. You can connect to WebContext::initializeWebProcessExtensions to call this method before anything is loaded.

setWebProcessExtensionsInitializationUserData

webContextSetWebProcessExtensionsInitializationUserData

Arguments

:: (HasCallStack, MonadIO m, IsWebContext a)

=> a

context: a WebContext

-> GVariant

userData: a GVariant

-> m ()

Set user data to be passed to Web Extensions on initialization.

The data will be passed to the WebKitWebProcessExtensionInitializeWithUserDataFunction. This method must be called before loading anything in this context, otherwise it will not have any effect. You can connect to WebContext::initializeWebProcessExtensions to call this method before anything is loaded.

Since: 2.4

Properties

memoryPressureSettings

The MemoryPressureSettings applied to the web processes created by this context.

Since: 2.34

constructWebContextMemoryPressureSettings :: (IsWebContext o, MonadIO m) => MemoryPressureSettings -> m (GValueConstruct o)

Construct a GValueConstruct with valid value for the “memory-pressure-settings” property. This is rarely needed directly, but it is used by new.

timeZoneOverride

The timezone override for this web context. Setting this property provides a better alternative to configure the timezone information for all webviews managed by the WebContext. The other, less optimal, approach is to globally set the TZ environment variable in the process before creating the context. However this approach might not be very convenient and can have side-effects in your application.

The expected values for this property are defined in the IANA timezone database. See this wikipedia page for instance, https://en.wikipedia.org/wiki/List_of_tz_database_time_zones.

Since: 2.38

constructWebContextTimeZoneOverride :: (IsWebContext o, MonadIO m) => Text -> m (GValueConstruct o)

Construct a GValueConstruct with valid value for the “time-zone-override” property. This is rarely needed directly, but it is used by new.

getWebContextTimeZoneOverride :: (MonadIO m, IsWebContext o) => o -> m Text

Get the value of the “time-zone-override” property. When overloading is enabled, this is equivalent to

get webContext #timeZoneOverride

Signals

automationStarted

type WebContextAutomationStartedCallback

Arguments

 = AutomationSession

session: the AutomationSession associated with this event

-> IO ()

This signal is emitted when a new automation request is made. Note that it will never be emitted if automation is not enabled in context, see webContextSetAutomationAllowed for more details.

Since: 2.18

afterWebContextAutomationStarted :: (IsWebContext a, MonadIO m) => a -> ((?self :: a) => WebContextAutomationStartedCallback) -> m SignalHandlerId

Connect a signal handler for the automationStarted signal, to be run after the default handler. When overloading is enabled, this is equivalent to

after webContext #automationStarted callback

By default the object invoking the signal is not passed to the callback. If you need to access it, you can use the implit ?self parameter. Note that this requires activating the ImplicitParams GHC extension.

onWebContextAutomationStarted :: (IsWebContext a, MonadIO m) => a -> ((?self :: a) => WebContextAutomationStartedCallback) -> m SignalHandlerId

Connect a signal handler for the automationStarted signal, to be run before the default handler. When overloading is enabled, this is equivalent to

on webContext #automationStarted callback

initializeNotificationPermissions

type WebContextInitializeNotificationPermissionsCallback = IO ()

This signal is emitted when a WebContext needs to set initial notification permissions for a web process. It is emitted when a new web process is about to be launched, and signals the most appropriate moment to use webContextInitializeNotificationPermissions. If no notification permissions have changed since the last time this signal was emitted, then there is no need to call webContextInitializeNotificationPermissions again.

Since: 2.16

afterWebContextInitializeNotificationPermissions :: (IsWebContext a, MonadIO m) => a -> ((?self :: a) => WebContextInitializeNotificationPermissionsCallback) -> m SignalHandlerId

Connect a signal handler for the initializeNotificationPermissions signal, to be run after the default handler. When overloading is enabled, this is equivalent to

after webContext #initializeNotificationPermissions callback

By default the object invoking the signal is not passed to the callback. If you need to access it, you can use the implit ?self parameter. Note that this requires activating the ImplicitParams GHC extension.

onWebContextInitializeNotificationPermissions :: (IsWebContext a, MonadIO m) => a -> ((?self :: a) => WebContextInitializeNotificationPermissionsCallback) -> m SignalHandlerId

Connect a signal handler for the initializeNotificationPermissions signal, to be run before the default handler. When overloading is enabled, this is equivalent to

on webContext #initializeNotificationPermissions callback

initializeWebProcessExtensions

type WebContextInitializeWebProcessExtensionsCallback = IO ()

This signal is emitted when a new web process is about to be launched. It signals the most appropriate moment to use webContextSetWebProcessExtensionsInitializationUserData and webContextSetWebProcessExtensionsDirectory.

Since: 2.4

afterWebContextInitializeWebProcessExtensions :: (IsWebContext a, MonadIO m) => a -> ((?self :: a) => WebContextInitializeWebProcessExtensionsCallback) -> m SignalHandlerId

Connect a signal handler for the initializeWebProcessExtensions signal, to be run after the default handler. When overloading is enabled, this is equivalent to

after webContext #initializeWebProcessExtensions callback

By default the object invoking the signal is not passed to the callback. If you need to access it, you can use the implit ?self parameter. Note that this requires activating the ImplicitParams GHC extension.

onWebContextInitializeWebProcessExtensions :: (IsWebContext a, MonadIO m) => a -> ((?self :: a) => WebContextInitializeWebProcessExtensionsCallback) -> m SignalHandlerId

Connect a signal handler for the initializeWebProcessExtensions signal, to be run before the default handler. When overloading is enabled, this is equivalent to

on webContext #initializeWebProcessExtensions callback

userMessageReceived

type WebContextUserMessageReceivedCallback

Arguments

 = UserMessage

message: the UserMessage received

-> IO Bool

Returns: True if the message was handled, or False otherwise.

This signal is emitted when a UserMessage is received from a web process extension. You can reply to the message using userMessageSendReply.

You can handle the user message asynchronously by calling objectRef on message and returning True.

Since: 2.28

afterWebContextUserMessageReceived :: (IsWebContext a, MonadIO m) => a -> ((?self :: a) => WebContextUserMessageReceivedCallback) -> m SignalHandlerId

Connect a signal handler for the userMessageReceived signal, to be run after the default handler. When overloading is enabled, this is equivalent to

after webContext #userMessageReceived callback

By default the object invoking the signal is not passed to the callback. If you need to access it, you can use the implit ?self parameter. Note that this requires activating the ImplicitParams GHC extension.

onWebContextUserMessageReceived :: (IsWebContext a, MonadIO m) => a -> ((?self :: a) => WebContextUserMessageReceivedCallback) -> m SignalHandlerId

Connect a signal handler for the userMessageReceived signal, to be run before the default handler. When overloading is enabled, this is equivalent to

on webContext #userMessageReceived callback