uriloader/docs/uriloader.rst

   1 .. _uri_loader_service:
   2
   3 URI Loader Service
   4 ==================
   5
   6 As its name might suggest the URI loader service is responsible for loading URIs
   7 but it is also responsible for deciding how to handle that content, whether to
   8 display it as part of a DOM window or hand it off to something else.
   9
  10 It is generally used when loading content for display to the user, normally from
  11 ``nsDocShell`` for display as a webpage or ``nsObjectLoadingContent`` for display inside
  12 a webpage's ``<object>`` tag. The normal entrypoint is through ``nsIURILoader::OpenURI``.
  13
  14 The URI loader starts the load and registers an ``nsDocumentOpenInfo`` as a stream
  15 listener for the content. Once headers have been received `DispatchContent <https://searchfox.org/mozilla-central/search?q=nsDocumentOpenInfo%3A%3ADispatchContent&path=>`_
  16 then decides what to do with the content as it may need to be handled by something
  17 other than the caller. It uses a few criteria to decide this including:
  18
  19 * Content-Type header.
  20 * Content-Disposition header.
  21 * Load flags.
  22
  23 Part of this handling may include running the content through a registered stream
  24 converter to convert the content type from one to another. This is done through
  25 the `stream converter service <https://searchfox.org/mozilla-central/source/netwerk/streamconv>`_.
  26 When this happens a new ``nsDocumentOpenInfo`` is created to handle the new content
  27 in the same way as the current content.
  28
  29 The rough flow goes as follows (though note that this can vary depending on the
  30 flags passed to the loader service):
  31
  32 1. The caller may provide an ``nsIURIContentListener`` which can offer to handle
  33    the content type or a content type that we can convert the original type to).
  34    If so the load is passed off to the listener.
  35 2. Global instances of ``nsIURIContentListener`` can be registered with the URI
  36    loader service so these are consulted in the same way.
  37 3. Global instances of ``nsIURIContentListener`` can be registered in the category
  38    manager so these are consulted in the same way.
  39 4. Global instances of ``nsIContentHandler`` can be registered. If one agrees to
  40    handle the content then the load is handed over to it.
  41 5. We attempt to convert the content to a different type.
  42 6. The load is handed over to the :ref:`External Helper App Service <external_helper_app_service>`.
  43
  44 For the most part the process ends at step 1 because nsDocShell passes a ``nsDSURIContentListener``
  45 for the ``nsIURIContentListener`` consulted first and it accepts most of the
  46 `web content types <https://searchfox.org/mozilla-central/search?q=CONTENTDLF_CATEGORIES&redirect=false>`_.