Package org.mozilla.geckoview

Class GeckoSession

Object
org.mozilla.geckoview.GeckoSession
public class GeckoSession extends Object

  • Field Details

    • mWindow

      @Nullable protected org.mozilla.geckoview.GeckoSession.Window mWindow

    • PRIORITY_DEFAULT

      public static final int PRIORITY_DEFAULT
      Value for Priority when it is default.
      See Also:

    • PRIORITY_HIGH

      public static final int PRIORITY_HIGH
      Value for Priority when it is high.
      See Also:

    • LOAD_FLAGS_NONE

      public static final int LOAD_FLAGS_NONE
      Default load flag, no special considerations.
      See Also:

    • LOAD_FLAGS_BYPASS_CACHE

      public static final int LOAD_FLAGS_BYPASS_CACHE
      Bypass the cache.
      See Also:

    • LOAD_FLAGS_BYPASS_PROXY

      public static final int LOAD_FLAGS_BYPASS_PROXY
      Bypass the proxy, if one has been configured.
      See Also:

    • LOAD_FLAGS_EXTERNAL

      public static final int LOAD_FLAGS_EXTERNAL
      The load is coming from an external app. Perform additional checks.
      See Also:

    • LOAD_FLAGS_ALLOW_POPUPS

      public static final int LOAD_FLAGS_ALLOW_POPUPS
      Popup blocking will be disabled for this load
      See Also:

    • LOAD_FLAGS_BYPASS_CLASSIFIER

      public static final int LOAD_FLAGS_BYPASS_CLASSIFIER
      Bypass the URI classifier (content blocking and Safe Browsing).
      See Also:

    • LOAD_FLAGS_FORCE_ALLOW_DATA_URI

      public static final int LOAD_FLAGS_FORCE_ALLOW_DATA_URI
      Allows a top-level data: navigation to occur. E.g. view-image is an explicit user action which should be allowed.
      See Also:

    • LOAD_FLAGS_REPLACE_HISTORY

      public static final int LOAD_FLAGS_REPLACE_HISTORY
      This flag specifies that any existing history entry should be replaced.
      See Also:

    • LOAD_FLAGS_BYPASS_LOAD_URI_DELEGATE

      public static final int LOAD_FLAGS_BYPASS_LOAD_URI_DELEGATE
      This load should bypass the NavigationDelegate.onLoadRequest.
      See Also:

    • HEADER_FILTER_CORS_SAFELISTED

      public static final int HEADER_FILTER_CORS_SAFELISTED
      Filter headers according to the CORS safelisted rules.

      See CORS-safelisted request header .

      See Also:

    • HEADER_FILTER_UNRESTRICTED_UNSAFE

      public static final int HEADER_FILTER_UNRESTRICTED_UNSAFE
      Allows most headers.

      Note: the Host and Connection headers are still ignored.

      This should only be used when input is hard-coded from the app or when properly sanitized, as some headers could cause unexpected consequences and security issues.

      Only use this if you know what you're doing.

      See Also:

    • FINDER_FIND_FORWARD

      public static final int FINDER_FIND_FORWARD
      Go forward when finding the next match.
      See Also:

    • FINDER_FIND_BACKWARDS

      public static final int FINDER_FIND_BACKWARDS
      Go backwards when finding the next match.
      See Also:

    • FINDER_FIND_MATCH_CASE

      public static final int FINDER_FIND_MATCH_CASE
      Perform case-sensitive match; default is to perform a case-insensitive match.
      See Also:

    • FINDER_FIND_WHOLE_WORD

      public static final int FINDER_FIND_WHOLE_WORD
      Must match entire words; default is to allow matching partial words.
      See Also:

    • FINDER_DISPLAY_HIGHLIGHT_ALL

      public static final int FINDER_DISPLAY_HIGHLIGHT_ALL
      Highlight all find-in-page matches.
      See Also:

    • FINDER_DISPLAY_DIM_PAGE

      public static final int FINDER_DISPLAY_DIM_PAGE
      Dim the rest of the page when showing a find-in-page match.
      See Also:

  • Constructor Details

    • GeckoSession

      public GeckoSession()

    • GeckoSession

      public GeckoSession(@Nullable GeckoSessionSettings settings)

  • Method Details

    • getUserAgent

      @AnyThread @NonNull public GeckoResult<String> getUserAgent()
      Get the current user agent string for this GeckoSession.
      Returns:
      a GeckoResult containing the UserAgent string

    • getDefaultUserAgent

      @AnyThread @NonNull public static String getDefaultUserAgent()
      Get the default user agent for this GeckoView build.

      This method does not account for any override that might have been applied to the user agent string.

      Returns:
      the default user agent string

    • getPermissionDelegate

      @UiThread @Nullable public GeckoSession.PermissionDelegate getPermissionDelegate()
      Get the current permission delegate for this GeckoSession.
      Returns:
      PermissionDelegate instance or null if using default delegate.

    • setPermissionDelegate

      @UiThread public void setPermissionDelegate(@Nullable GeckoSession.PermissionDelegate delegate)
      Set the current permission delegate for this GeckoSession.
      Parameters:
      delegate - PermissionDelegate instance or null to use the default delegate.

    • isOpen

      @UiThread public boolean isOpen()
      Return whether this session is open.
      Returns:
      True if session is open.
      See Also:

    • open

      @UiThread public void open(@NonNull GeckoRuntime runtime)
      Opens the session.

      Call this when you are ready to use a GeckoSession instance.

      The session is in a 'closed' state when first created. Opening it creates the underlying Gecko objects necessary to load a page, etc. Most GeckoSession methods only take affect on an open session, and are queued until the session is opened here. Opening a session is an asynchronous operation.

      Parameters:
      runtime - The Gecko runtime to attach this session to.
      See Also:

    • close

      @UiThread public void close()
      Closes the session.

      This frees the underlying Gecko objects and unloads the current page. The session may be reopened later, but page state is not restored. Call this when you are finished using a GeckoSession instance.

      See Also:

    • getTextInput

      @AnyThread @NonNull public SessionTextInput getTextInput()
      Get the SessionTextInput instance for this session. May be called on any thread.
      Returns:
      SessionTextInput instance.

    • getAccessibility

      @UiThread @NonNull public SessionAccessibility getAccessibility()
      Get the SessionAccessibility instance for this session.
      Returns:
      SessionAccessibility instance.

    • load

      @AnyThread public void load(@NonNull GeckoSession.Loader request)
      Load page using the GeckoSession.Loader specified.
      Parameters:
      request - Loader for this request.
      See Also:

    • loadUri

      @AnyThread public void loadUri(@NonNull String uri)
      Load the given URI.

      Convenience method for 

      
     session.load(new Loader().uri(uri));
      Parameters:
      uri - The URI of the resource to load.

    • reload

      @AnyThread public void reload()
      Reload the current URI.

    • reload

      @AnyThread public void reload(int flags)
      Reload the current URI.
      Parameters:
      flags - the load flags to use, an OR-ed value of LOAD_FLAGS_*

    • stop

      @AnyThread public void stop()
      Stop loading.

    • goBack

      @AnyThread public void goBack()
      Go back in history and assumes the call was based on a user interaction.
      See Also:

    • goBack

      @AnyThread public void goBack(boolean userInteraction)
      Go back in history.
      Parameters:
      userInteraction - Whether the action was invoked by a user interaction.

    • goForward

      @AnyThread public void goForward()
      Go forward in history and assumes the call was based on a user interaction.
      See Also:

    • goForward

      @AnyThread public void goForward(boolean userInteraction)
      Go forward in history.
      Parameters:
      userInteraction - Whether the action was invoked by a user interaction.

    • gotoHistoryIndex

      @AnyThread public void gotoHistoryIndex(int index)
      Navigate to an index in browser history; the index of the currently viewed page can be retrieved from an up-to-date HistoryList by calling GeckoSession.HistoryDelegate.HistoryList.getCurrentIndex().
      Parameters:
      index - The index of the location in browser history you want to navigate to.

    • getWebExtensionController

      @UiThread @NonNull public WebExtension.SessionController getWebExtensionController()
      Returns a WebExtensionController for this GeckoSession. Delegates attached to this controller will receive events specific to this session.
      Returns:
      an instance of WebExtension.SessionController.

    • purgeHistory

      @AnyThread public void purgeHistory()
      Purge history for the session. The session history is used for back and forward history. Purging the session history means GeckoSession.NavigationDelegate.onCanGoBack(GeckoSession, boolean) and GeckoSession.NavigationDelegate.onCanGoForward(GeckoSession, boolean) will be false.

    • getFinder

      @AnyThread @NonNull public SessionFinder getFinder()
      Get the SessionFinder instance for this session, to perform find-in-page operations.
      Returns:
      SessionFinder instance.

    • hasCookieBannerRuleForBrowsingContextTree

      @AnyThread @NonNull public GeckoResult<Boolean> hasCookieBannerRuleForBrowsingContextTree()
      Checks whether we have a rule for this session. Uses the browsing context or any of its children, calls nsICookieBannerService.hasRuleForBrowsingContextTree
      Returns:
      GeckoResult with boolean

    • getPdfFileSaver

      @AnyThread @NonNull public SessionPdfFileSaver getPdfFileSaver()
      Get the SessionPdfFileSaver instance for this session, to save a pdf document.
      Returns:
      SessionPdfFileSaver instance.

    • isPdfJs

      @AnyThread @NonNull public GeckoResult<Boolean> isPdfJs()
      Check if the document being viewed is a pdf.
      Returns:
      Result of the check operation as a GeckoResult object.

    • setActive

      @AnyThread public void setActive(boolean active)
      Set this GeckoSession as active or inactive, which represents if the session is currently visible or not. Setting a GeckoSession to inactive will significantly reduce its memory footprint, but should only be done if the GeckoSession is not currently visible. Note that a session can be active (i.e. visible) but not focused. When a session is set inactive, it will flush the session state and trigger a `ProgressDelegate.onSessionStateChange` callback.
      Parameters:
      active - A boolean determining whether the GeckoSession is active.
      See Also:

    • setFocused

      @AnyThread public void setFocused(boolean focused)
      Move focus to this session or away from this session. Only one session has focus at a given time. Note that a session can be unfocused but still active (i.e. visible).
      Parameters:
      focused - True if the session should gain focus or false if the session should lose focus.
      See Also:

    • setPriorityHint

      @AnyThread public void setPriorityHint(int priorityHint)
      Notify GeckoView of the priority for this GeckoSession.

      Set this GeckoSession to high priority (PRIORITY_HIGH) whenever the app wants to signal to GeckoView that this GeckoSession is important to the app. GeckoView will keep the session state as long as possible. Set this to default priority (PRIORITY_DEFAULT) in any other case.

      Parameters:
      priorityHint - Priority of the geckosession, either high priority or default.

    • restoreState

      @AnyThread public void restoreState(@NonNull GeckoSession.SessionState state)
      Restore a saved state to this GeckoSession; only data that is saved (history, scroll position, zoom, and form data) will be restored. These will overwrite the corresponding state of this GeckoSession.
      Parameters:
      state - A saved session state; this should originate from onSessionStateChange().

    • containsFormData

      @AnyThread @NonNull public GeckoResult<Boolean> containsFormData()
      Get whether this GeckoSession has form data.
      Returns:
      a GeckoResult result of if there is existing form data.

    • getWebCompatInfo

      @AnyThread @NonNull public GeckoResult<JSONObject> getWebCompatInfo()
      Get the web compatibility info when a site is reported as broken.
      Returns:
      a GeckoResult containing the WebCompatInfo as a JSONObject.

    • sendMoreWebCompatInfo

      @AnyThread @NonNull public GeckoResult<Void> sendMoreWebCompatInfo(@NonNull JSONObject info)
      Send more web compatibility info when a site is reported as broken.
      Parameters:
      info - A JSONObject containing the web compatibility report details. The expected format of the JSON object is: 
      
             {
               "reason": "User-selected reason for reporting",
               "description": "User-provided description of the issue",
               "endpointUrl": "https://webcompat.com/issues/new",
               "reportUrl": "URL of the reported site",
               "reporterConfig": {
                 "src": "android-components-reporter",
                 "utm_campaign": "report-site-issue-button",
                 "utm_source": "android-components-reporter"
               },
               "webcompatInfo": { //JSONObject from GeckoSession.getWebCompatInfo() }
             }
      Returns:
      a GeckoResult wil complete if sending more web compatibility info was successful. Will complete exceptionally if the web compat info was not sent.

    • acquireDisplay

      @UiThread @NonNull public GeckoDisplay acquireDisplay()
      Acquire the GeckoDisplay instance for providing the session with a drawing Surface. Be sure to call GeckoDisplay.surfaceChanged(SurfaceInfo) on the acquired display if there is already a valid Surface.
      Returns:
      GeckoDisplay instance.
      See Also:

    • releaseDisplay

      @UiThread public void releaseDisplay(@NonNull GeckoDisplay display)
      Release an acquired GeckoDisplay instance. Be sure to call GeckoDisplay.surfaceDestroyed() before releasing the display if it still has a valid Surface.
      Parameters:
      display - Acquired GeckoDisplay instance.
      See Also:

    • getSettings

      @AnyThread @NonNull public GeckoSessionSettings getSettings()

    • exitFullScreen

      @AnyThread public void exitFullScreen()
      Exits fullscreen mode

    • setContentDelegate

      @UiThread public void setContentDelegate(@Nullable GeckoSession.ContentDelegate delegate)
      Set the content callback handler. This will replace the current handler.
      Parameters:
      delegate - An implementation of ContentDelegate.

    • getContentDelegate

      @UiThread @Nullable public GeckoSession.ContentDelegate getContentDelegate()
      Get the content callback handler.
      Returns:
      The current content callback handler.

    • setProgressDelegate

      @UiThread public void setProgressDelegate(@Nullable GeckoSession.ProgressDelegate delegate)
      Set the progress callback handler. This will replace the current handler.
      Parameters:
      delegate - An implementation of ProgressDelegate.

    • getProgressDelegate

      @UiThread @Nullable public GeckoSession.ProgressDelegate getProgressDelegate()
      Get the progress callback handler.
      Returns:
      The current progress callback handler.

    • setNavigationDelegate

      @UiThread public void setNavigationDelegate(@Nullable GeckoSession.NavigationDelegate delegate)
      Set the navigation callback handler. This will replace the current handler.
      Parameters:
      delegate - An implementation of NavigationDelegate.

    • getNavigationDelegate

      @UiThread @Nullable public GeckoSession.NavigationDelegate getNavigationDelegate()
      Get the navigation callback handler.
      Returns:
      The current navigation callback handler.

    • setScrollDelegate

      @UiThread public void setScrollDelegate(@Nullable GeckoSession.ScrollDelegate delegate)
      Set the content scroll callback handler. This will replace the current handler.
      Parameters:
      delegate - An implementation of ScrollDelegate.

    • getScrollDelegate

      @UiThread @Nullable public GeckoSession.ScrollDelegate getScrollDelegate()
      Get the current scroll callback handler.
      Returns:
      An implementation of ScrollDelegate.

    • setCompositorScrollDelegate

      @UiThread public void setCompositorScrollDelegate(@Nullable GeckoSession.CompositorScrollDelegate delegate)
      Set the compositor scroll callback handler. This will replace the current handler.
      Parameters:
      delegate - An implementation of CompositorScrollDelegate.

    • getCompositorScrollDelegate

      @UiThread @Nullable public GeckoSession.CompositorScrollDelegate getCompositorScrollDelegate()
      Get the current compositor scroll callback handler.
      Returns:
      An implementation of CompositorScrollDelegate.

    • setHistoryDelegate

      @AnyThread public void setHistoryDelegate(@Nullable GeckoSession.HistoryDelegate delegate)
      Set the history tracking delegate for this session, replacing the current delegate if one is set.
      Parameters:
      delegate - The history tracking delegate, or null to unset.

    • getHistoryDelegate

      @AnyThread @Nullable public GeckoSession.HistoryDelegate getHistoryDelegate()
      Returns:
      The history tracking delegate for this session.

    • setContentBlockingDelegate

      @AnyThread public void setContentBlockingDelegate(@Nullable ContentBlocking.Delegate delegate)
      Set the content blocking callback handler. This will replace the current handler.
      Parameters:
      delegate - An implementation of ContentBlocking.Delegate.

    • getContentBlockingDelegate

      @AnyThread @Nullable public ContentBlocking.Delegate getContentBlockingDelegate()
      Get the content blocking callback handler.
      Returns:
      The current content blocking callback handler.

    • setPromptDelegate

      @AnyThread public void setPromptDelegate(@Nullable GeckoSession.PromptDelegate delegate)
      Set the current prompt delegate for this GeckoSession.
      Parameters:
      delegate - PromptDelegate instance or null to use the built-in delegate.

    • getPromptDelegate

      @AnyThread @Nullable public GeckoSession.PromptDelegate getPromptDelegate()
      Get the current prompt delegate for this GeckoSession.
      Returns:
      PromptDelegate instance or null if using built-in delegate.

    • setSelectionActionDelegate

      @UiThread public void setSelectionActionDelegate(@Nullable GeckoSession.SelectionActionDelegate delegate)
      Set the current selection action delegate for this GeckoSession.
      Parameters:
      delegate - SelectionActionDelegate instance or null to unset.

    • setMediaDelegate

      @AnyThread public void setMediaDelegate(@Nullable GeckoSession.MediaDelegate delegate)
      Set the media callback handler. This will replace the current handler.
      Parameters:
      delegate - An implementation of MediaDelegate.

    • getMediaDelegate

      @AnyThread @Nullable public GeckoSession.MediaDelegate getMediaDelegate()
      Get the Media callback handler.
      Returns:
      The current Media callback handler.

    • setMediaSessionDelegate

      @AnyThread public void setMediaSessionDelegate(@Nullable MediaSession.Delegate delegate)
      Set the media session delegate. This will replace the current handler.
      Parameters:
      delegate - An implementation of MediaSession.Delegate.

    • getMediaSessionDelegate

      @AnyThread @Nullable public MediaSession.Delegate getMediaSessionDelegate()
      Get the media session delegate.
      Returns:
      The current media session delegate.

    • getSessionTranslation

      @AnyThread @Nullable public TranslationsController.SessionTranslation getSessionTranslation()
      The session translation object coordinates receiving and sending session messages with the translations toolkit. Notably, it can be used to request translations.
      Returns:
      The current translation session coordinator.

    • setTranslationsSessionDelegate

      @AnyThread public void setTranslationsSessionDelegate(@Nullable TranslationsController.SessionTranslation.Delegate delegate)
      Set the translation delegate, which receives translations events.
      Parameters:
      delegate - An implementation of @link{TranslationsController.SessionTranslation.Delegate}.

    • getTranslationsSessionDelegate

      @AnyThread @Nullable public TranslationsController.SessionTranslation.Delegate getTranslationsSessionDelegate()
      Get the translations delegate. The application embedder must initially set the translations delegate for use.
      Returns:
      The current translations delegate.

    • getSelectionActionDelegate

      @AnyThread @Nullable public GeckoSession.SelectionActionDelegate getSelectionActionDelegate()
      Get the current selection action delegate for this GeckoSession.
      Returns:
      SelectionActionDelegate instance or null if not set.

    • setShouldPinOnScreen

      @UiThread protected void setShouldPinOnScreen(boolean pinned)

    • getPanZoomController

      @UiThread @NonNull public PanZoomController getPanZoomController()
      Get the PanZoomController instance for this session.
      Returns:
      PanZoomController instance.

    • getOverscrollEdgeEffect

      @UiThread @NonNull public OverscrollEdgeEffect getOverscrollEdgeEffect()
      Get the OverscrollEdgeEffect instance for this session.
      Returns:
      OverscrollEdgeEffect instance.

    • getCompositorController

      @UiThread @NonNull public CompositorController getCompositorController()
      Get the CompositorController instance for this session.
      Returns:
      CompositorController instance.

    • getClientToSurfaceMatrix

      @UiThread public void getClientToSurfaceMatrix(@NonNull Matrix matrix)
      Get a matrix for transforming from client coordinates to surface coordinates.
      Parameters:
      matrix - Matrix to be replaced by the transformation matrix.
      See Also:

    • getClientToScreenMatrix

      @UiThread public void getClientToScreenMatrix(@NonNull Matrix matrix)
      Get a matrix for transforming from client coordinates to screen coordinates. The client coordinates are in CSS pixels and are relative to the viewport origin; their relation to screen coordinates does not depend on the current scroll position.
      Parameters:
      matrix - Matrix to be replaced by the transformation matrix.
      See Also:

    • getPageToScreenMatrix

      @UiThread public void getPageToScreenMatrix(@NonNull Matrix matrix)
      Get a matrix for transforming from page coordinates to screen coordinates. The page coordinates are in CSS pixels and are relative to the page origin; their relation to screen coordinates depends on the current scroll position of the outermost frame.
      Parameters:
      matrix - Matrix to be replaced by the transformation matrix.
      See Also:

    • getPageToSurfaceMatrix

      @UiThread public void getPageToSurfaceMatrix(@NonNull Matrix matrix)
      Get a matrix for transforming from page coordinates to surface coordinates.
      Parameters:
      matrix - Matrix to be replaced by the transformation matrix.
      See Also:

    • getClientBounds

      @UiThread public void getClientBounds(@NonNull RectF rect)
      Get the bounds of the client area in client coordinates. The returned top-left coordinates are always (0, 0). Use the matrix from getClientToSurfaceMatrix(Matrix) or getClientToScreenMatrix(Matrix) to map these bounds to surface or screen coordinates, respectively.
      Parameters:
      rect - RectF to be replaced by the client bounds in client coordinates.
      See Also:

    • getSurfaceBounds

      @UiThread public void getSurfaceBounds(@NonNull Rect rect)
      Get the bounds of the client area in surface coordinates. This is equivalent to mapping the bounds returned by #getClientBounds(RectF) with the matrix returned by #getClientToSurfaceMatrix(Matrix).
      Parameters:
      rect - Rect to be replaced by the client bounds in surface coordinates.

    • setAutofillDelegate

      @UiThread public void setAutofillDelegate(@Nullable Autofill.Delegate delegate)
      Sets the autofill delegate for this session.
      Parameters:
      delegate - An instance of Autofill.Delegate.

    • getAutofillDelegate

      @UiThread @Nullable public Autofill.Delegate getAutofillDelegate()
      Returns:
      The current Autofill.Delegate for this session, if any.

    • getAutofillSession

      @UiThread @NonNull public Autofill.Session getAutofillSession()
      Provides an autofill structure similar to View.onProvideAutofillVirtualStructure(ViewStructure, int) , but does not rely on ViewStructure to build the tree. This is useful for apps that want to provide autofill functionality without using the Android autofill system or requiring API 26.
      Returns:
      The elements available for autofill.

    • saveAsPdf

      @AnyThread @NonNull public GeckoResult<InputStream> saveAsPdf()
      Saves a PDF of the currently displayed page.
      Returns:
      A GeckoResult with an InputStream containing the PDF. The result could CompleteExceptionally with a GeckoSession.GeckoPrintExceptions, if there are any issues while generating the PDF.

    • printPageContent

      @AnyThread public void printPageContent()
      Prints the currently displayed page.

    • didPrintPageContent

      @AnyThread @NonNull public GeckoResult<Boolean> didPrintPageContent()
      Prints the currently displayed page and provides dialog finished status or if an exception occured.
      Returns:
      if the printing dialog finished or an exception.

    • getPrintDelegate

      @AnyThread @Nullable public GeckoSession.PrintDelegate getPrintDelegate()
      Gets the print delegate for this session.
      Returns:
      The current GeckoSession.PrintDelegate for this session, if any.

    • setPrintDelegate

      @AnyThread public void setPrintDelegate(@Nullable GeckoSession.PrintDelegate delegate)
      Sets the print delegate for this session.
      Parameters:
      delegate - An instance of GeckoSession.PrintDelegate.

    • getExperimentDelegate

      @AnyThread @Nullable public ExperimentDelegate getExperimentDelegate()
      Gets the experiment delegate for this session.
      Returns:
      The current ExperimentDelegate for this session, if any.

    • setExperimentDelegate

      @AnyThread public void setExperimentDelegate(@Nullable ExperimentDelegate delegate)
      Sets the experiment delegate for this session. Default is set to the runtime experiment delegate.
      Parameters:
      delegate - An instance of ExperimentDelegate.