From 6bf0a5cb5034a7e684dcc3500e841785237ce2dd Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 7 Apr 2024 19:32:43 +0200 Subject: Adding upstream version 1:115.7.0. Signed-off-by: Daniel Baumann --- uriloader/exthandler/docs/index.rst | 76 +++++++++++++++++++++++++++++++++++++ 1 file changed, 76 insertions(+) create mode 100644 uriloader/exthandler/docs/index.rst (limited to 'uriloader/exthandler/docs/index.rst') diff --git a/uriloader/exthandler/docs/index.rst b/uriloader/exthandler/docs/index.rst new file mode 100644 index 0000000000..40088ab6d3 --- /dev/null +++ b/uriloader/exthandler/docs/index.rst @@ -0,0 +1,76 @@ +.. _external_helper_app_service: + +External Helper App Service +=========================== + +The external helper app service is responsible for deciding how to handle an +attempt to load come content that cannot be loaded by the browser itself. + +Part of this involves using the Handler Service which manages the users +preferences for what to do by default with different content. + +When a Link is Clicked +---------------------- + +When a link in a page is clicked (or a form submitted) ``nsDocShell`` tests +whether the target protocol can be loaded by the browser itself, this is based +on the preferences under ``network.protocol-handler``. When the browser cannot +load the protocol it calls into ``nsExternalHelperAppService::LoadURI``. + +Some validation checks are performed but ultimateley we look for a registered +protocol handler. First the OS is queried for an app registration for the +protocol and then the handler server is asked to fill in any user settings from +the internal database. If there were no settings from the handler service then +some defaults are applied in ``nsExternalHelperAppService::SetProtocolHandlerDefaults``. + +If there is a default handler app chosen and the settings say to use it without +asking then that happens. If not a dialog s shown asking the user what they +want to do. + +During a Load +------------- + +When content is already being loaded the :ref:`URI Loader Service ` +determines whether the browser can handle the content or not. If not it calls +into the external helper app server through ``nsExternalHelperAppService::DoContent``. + +The content type of the loading content is retrieved from the channel. A file +extension is also generated using the Content-Disposition header or if the load +is not a HTTP POST request the file extension is generated from the requested URL. + +We then query the MIME Service for an nsIMIMEInfo to find information about +apps that can handle the content type or file extension based on OS and user +settings, :ref:`see below ` for further details. The result is +used to create a ``nsExternalAppHandler`` which is then used as a stream listener +for the content. + +The MIME info object contains settings that control whether to prompt the user +before doing anything and what the default action should be. If we need to ask +the user then a dialog is shown offering to let users cancel the load, save the +content to disk or send it to a registered application handler. + +Assuming the load isn't canceled the content is streamed to disk using a background +file saver with a target ``nsITransfer``. The ``nsITransfer`` is responsible for +showing the download in the UI. + +If the user opted to open the file with an application then once the transfer is +complete then ``nsIMIMEInfo::LaunchWithFile`` is used to +`launch the application `_. + +.. _mime_service: + +MIME Service +------------ + +The MIME service is responsible for getting an ``nsIMIMEInfo`` object for a +content type or file extension: + +1. Fills out an ``nsIMIMEInfo`` based on OS provided information. This is platform + specific but should try to find the default application registered to handle + the content. +2. Ask the handler service to fill out the ``nsIMIMEInfo`` with information held + in browser settings. This will not overwrite a any application found from + the OS. +3. If one has not been found already then try to find a type description from + a `lookup table `_ + or just by appending " File" to the file extension. -- cgit v1.2.3