Adding upstream version 115.8.0esr.upstream/115.8.0esr

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 46 insertions, 0 deletions

diff --git a/uriloader/docs/uriloader.rst b/uriloader/docs/uriloader.rst
new file mode 100644
index 0000000000..e0763233e5
--- /dev/null
+++ b/uriloader/docs/uriloader.rst
@@ -0,0 +1,46 @@
+.. _uri_loader_service:
+
+URI Loader Service
+==================
+
+As its name might suggest the URI loader service is responsible for loading URIs
+but it is also responsible for deciding how to handle that content, whether to
+display it as part of a DOM window or hand it off to something else.
+
+It is generally used when loading content for display to the user, normally from
+``nsDocShell`` for display as a webpage or ``nsObjectLoadingContent`` for display inside
+a webpage's ``<object>`` tag. The normal entrypoint is through ``nsIURILoader::OpenURI``.
+
+The URI loader starts the load and registers an ``nsDocumentOpenInfo`` as a stream
+listener for the content. Once headers have been received `DispatchContent <https://searchfox.org/mozilla-central/search?q=nsDocumentOpenInfo%3A%3ADispatchContent&path=>`_
+then decides what to do with the content as it may need to be handled by something
+other than the caller. It uses a few criteria to decide this including:
+
+* Content-Type header.
+* Content-Disposition header.
+* Load flags.
+
+Part of this handling may include running the content through a registered stream
+converter to convert the content type from one to another. This is done through
+the `stream converter service <https://searchfox.org/mozilla-central/source/netwerk/streamconv>`_.
+When this happens a new ``nsDocumentOpenInfo`` is created to handle the new content
+in the same way as the current content.
+
+The rough flow goes as follows (though note that this can vary depending on the
+flags passed to the loader service):
+
+1. The caller may provide an ``nsIURIContentListener`` which can offer to handle
+   the content type or a content type that we can convert the original type to).
+   If so the load is passed off to the listener.
+2. Global instances of ``nsIURIContentListener`` can be registered with the URI
+   loader service so these are consulted in the same way.
+3. Global instances of ``nsIURIContentListener`` can be registered in the category
+   manager so these are consulted in the same way.
+4. Global instances of ``nsIContentHandler`` can be registered. If one agrees to
+   handle the content then the load is handed over to it.
+5. We attempt to convert the content to a different type.
+6. The load is handed over to the :ref:`External Helper App Service <external_helper_app_service>`.
+
+For the most part the process ends at step 1 because nsDocShell passes a ``nsDSURIContentListener``
+for the ``nsIURIContentListener`` consulted first and it accepts most of the
+`web content types <https://searchfox.org/mozilla-central/search?q=CONTENTDLF_CATEGORIES&redirect=false>`_.