// Copyright © 2018 The CefSharp Authors. All rights reserved.
|
//
|
// Use of this source code is governed by a BSD-style license that can be found in the LICENSE file.
|
|
using System;
|
|
namespace CefSharp
|
{
|
/// <summary>
|
/// Implement this interface to handle events related to browser extensions.
|
/// The methods of this class will be called on the CEF UI thread.
|
/// See <see cref="IRequestContext.LoadExtension"/> for information about extension loading.
|
/// </summary>
|
public interface IExtensionHandler : IDisposable
|
{
|
/// <summary>
|
/// Called if the <see cref="IRequestContext.LoadExtension"/> request fails.
|
/// </summary>
|
/// <param name="errorCode">error code</param>
|
void OnExtensionLoadFailed(CefErrorCode errorCode);
|
|
/// <summary>
|
/// Called if the <see cref="IRequestContext.LoadExtension"/> request succeeds.
|
/// </summary>
|
/// <param name="extension">is the loaded extension.</param>
|
void OnExtensionLoaded(IExtension extension);
|
|
/// <summary>
|
/// Called after the IExtension.Unload request has completed.
|
/// </summary>
|
/// <param name="extension">is the unloaded extension</param>
|
void OnExtensionUnloaded(IExtension extension);
|
|
/// <summary>
|
/// Called when an extension needs a browser to host a background script specified via the "background" manifest key.
|
/// The browser will have no visible window and cannot be displayed. To allow creation of the browser optionally
|
/// modify newBrowser and settings and return false. To cancel creation of the browser
|
/// (and consequently cancel load of the background script) return true. Successful creation will be indicated by a call to
|
/// ILifeSpanHandler.OnAfterCreated, and IBrowserHost.IsBackgroundHost
|
/// will return true for the resulting browser. See https://developer.chrome.com/extensions/event_pages for more information
|
/// about extension background script usage.
|
/// </summary>
|
/// <param name="extension">is the extension that is loading the background script</param>
|
/// <param name="url">is an internally generated reference to an HTML page that will be used to
|
/// load the background script via a script src attribute</param>
|
/// <param name="settings">browser settings</param>
|
/// <returns>To cancel creation of the browser (and consequently cancel load of the background script) return true, otherwise return false.</returns>
|
bool OnBeforeBackgroundBrowser(IExtension extension, string url, IBrowserSettings settings);
|
|
/// <summary>
|
/// Called when an extension API (e.g. chrome.tabs.create) requests creation of a new browser.
|
/// Successful creation will be indicated by a call to <see cref="ILifeSpanHandler.OnAfterCreated"/>.
|
/// </summary>
|
/// <param name="extension">the source of the API call</param>
|
/// <param name="browser">the source of the API call</param>
|
/// <param name="activeBrowser">may optionally be specified via the windowId property or
|
/// returned via the GetActiveBrowser() callback and provides the default for the new browser</param>
|
/// <param name="index">is the position value optionally specified via the index property</param>
|
/// <param name="url">is the URL that will be loaded in the browser</param>
|
/// <param name="active">is true if the new browser should be active when opened</param>
|
/// <param name="windowInfo">optionally modify if you are going to allow creation of the browser</param>
|
/// <param name="settings">optionally modify browser settings</param>
|
/// <returns>To cancel creation of the browser return true. To allow creation return false and optionally modify windowInfo and settings</returns>
|
bool OnBeforeBrowser(IExtension extension, IBrowser browser, IBrowser activeBrowser, int index, string url, bool active, IWindowInfo windowInfo, IBrowserSettings settings);
|
|
/// <summary>
|
/// Called when no tabId is specified to an extension API call that accepts a tabId parameter (e.g. chrome.tabs.*).
|
/// </summary>
|
/// <param name="extension">extension the call originates from</param>
|
/// <param name="browser">browser the call originates from</param>
|
/// <param name="includeIncognito">Incognito browsers should not be considered unless the source extension has incognito
|
/// access enabled, inwhich case this will be true</param>
|
/// <returns>Return the browser that will be acted on by the API call or return null to act on <paramref name="browser"/>.
|
/// The returned browser must share the same IRequestContext as <paramref name="browser"/></returns>
|
IBrowser GetActiveBrowser(IExtension extension, IBrowser browser, bool includeIncognito);
|
|
/// <summary>
|
/// Called when the tabId associated with <paramref name="targetBrowser"/> is specified to an extension API call that accepts a tabId
|
/// parameter (e.g. chrome.tabs.*).
|
/// </summary>
|
/// <param name="extension">extension the call originates from</param>
|
/// <param name="browser">browser the call originates from</param>
|
/// <param name="includeIncognito">Access to incognito browsers should not be allowed unless the source extension has
|
/// incognito access
|
/// enabled, in which case this will be true.</param>
|
/// <param name="targetBrowser"></param>
|
/// <returns>Return true to allow access of false to deny access.</returns>
|
bool CanAccessBrowser(IExtension extension, IBrowser browser, bool includeIncognito, IBrowser targetBrowser);
|
|
/// <summary>
|
/// Called to retrieve an extension resource that would normally be loaded from disk
|
/// (e.g. if a file parameter is specified to chrome.tabs.executeScript).
|
/// Localization substitutions will not be applied to resources handled via this method.
|
/// </summary>
|
/// <param name="extension">extension the call originates from</param>
|
/// <param name="browser">browser the call originates from</param>
|
/// <param name="file">is the requested relative file path.</param>
|
/// <param name="callback">callback used to handle custom resource requests</param>
|
/// <returns>To handle the resource request return true and execute <paramref name="callback"/> either synchronously or asynchronously.
|
/// For the default behavior which reads the resource from the extension directory on disk return false</returns>
|
bool GetExtensionResource(IExtension extension, IBrowser browser, string file, IGetExtensionResourceCallback callback);
|
}
|
}
|
