docshell/base/nsIURIFixup.idl

   1 /* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*-
   2  *
   3  * This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 #include "nsISupports.idl"
   8
   9 interface nsIURI;
  10 interface nsIInputStream;
  11
  12 /**
  13  * Interface indicating what we found/corrected when fixing up a URI
  14  */
  15 [scriptable, uuid(4819f183-b532-4932-ac09-b309cd853be7)]
  16 interface nsIURIFixupInfo : nsISupports
  17 {
  18   /**
  19    * Consumer that asked for fixed up URI.
  20    */
  21   attribute nsISupports consumer;
  22
  23   /**
  24    * Our best guess as to what URI the consumer will want. Might
  25    * be null if we couldn't salvage anything (for instance, because
  26    * the input was invalid as a URI and FIXUP_FLAG_ALLOW_KEYWORD_LOOKUP
  27    * was not passed)
  28    */
  29   readonly attribute nsIURI preferredURI;
  30
  31   /**
  32    * The fixed-up original input, *never* using a keyword search.
  33    * (might be null if the original input was not recoverable as
  34    * a URL, e.g. "foo bar"!)
  35    */
  36   readonly attribute nsIURI fixedURI;
  37
  38   /**
  39    * The name of the keyword search provider used to provide a keyword search;
  40    * empty string if no keyword search was done.
  41    */
  42   readonly attribute AString keywordProviderName;
  43
  44   /**
  45    * The keyword as used for the search (post trimming etc.)
  46    * empty string if no keyword search was done.
  47    */
  48   readonly attribute AString keywordAsSent;
  49
  50   /**
  51    * Whether we changed the protocol instead of using one from the input as-is.
  52    */
  53   readonly attribute boolean fixupChangedProtocol;
  54
  55   /**
  56    * Whether we created an alternative URI. We might have added a prefix and/or
  57    * suffix, the contents of which are controlled by the
  58    * browser.fixup.alternate.prefix and .suffix prefs, with the defaults being
  59    * "www." and ".com", respectively.
  60    */
  61   readonly attribute boolean fixupCreatedAlternateURI;
  62
  63   /**
  64    * The original input
  65    */
  66   readonly attribute AUTF8String originalInput;
  67 };
  68
  69
  70 /**
  71  * Interface implemented by objects capable of fixing up strings into URIs
  72  */
  73 [scriptable, uuid(1da7e9d4-620b-4949-849a-1cd6077b1b2d)]
  74 interface nsIURIFixup : nsISupports
  75 {
  76     /** No fixup flags. */
  77     const unsigned long FIXUP_FLAG_NONE = 0;
  78
  79     /**
  80      * Allow the fixup to use a keyword lookup service to complete the URI.
  81      * The fixup object implementer should honour this flag and only perform
  82      * any lengthy keyword (or search) operation if it is set.
  83      */
  84     const unsigned long FIXUP_FLAG_ALLOW_KEYWORD_LOOKUP = 1;
  85
  86     /**
  87      * Tell the fixup to make an alternate URI from the input URI, for example
  88      * to turn foo into www.foo.com.
  89      */
  90     const unsigned long FIXUP_FLAGS_MAKE_ALTERNATE_URI = 2;
  91
  92     /*
  93      * Fix common scheme typos.
  94      */
  95     const unsigned long FIXUP_FLAG_FIX_SCHEME_TYPOS = 8;
  96
  97     /* NB: If adding an extra flag, 4 is free (again) */
  98
  99     /**
 100      * Converts an internal URI (e.g. a wyciwyg URI) into one which we can
 101      * expose to the user, for example on the URL bar.
 102      *
 103      * @param  aURI       The URI to be converted
 104      * @return nsIURI     The converted, exposable URI
 105      * @throws NS_ERROR_MALFORMED_URI when the exposable portion of aURI is malformed
 106      * @throws NS_ERROR_UNKNOWN_PROTOCOL when we can't get a protocol handler service
 107      *         for the URI scheme.
 108      */
 109     nsIURI createExposableURI(in nsIURI aURI);
 110
 111     /**
 112      * Converts the specified string into a URI, first attempting
 113      * to correct any errors in the syntax or other vagaries. Returns
 114      * a wellformed URI or nullptr if it can't.
 115      *
 116      * @param aURIText    Candidate URI.
 117      * @param aFixupFlags Flags that govern ways the URI may be fixed up.
 118      * @param aPostData   The POST data to submit with the returned
 119      *                    URI (see nsISearchSubmission).
 120      */
 121     nsIURI createFixupURI(in AUTF8String aURIText, in unsigned long aFixupFlags,
 122                           [optional] out nsIInputStream aPostData);
 123
 124     /**
 125      * Same as createFixupURI, but returns information about what it corrected
 126      * (e.g. whether we could rescue the URI or "just" generated a keyword
 127      * search URI instead).
 128      *
 129      * @param aURIText    Candidate URI.
 130      * @param aFixupFlags Flags that govern ways the URI may be fixed up.
 131      * @param aPostData   The POST data to submit with the returned
 132      *                    URI (see nsISearchSubmission).
 133      */
 134     nsIURIFixupInfo getFixupURIInfo(in AUTF8String aURIText,
 135                                     in unsigned long aFixupFlags,
 136                                     [optional] out nsIInputStream aPostData);
 137
 138     /**
 139      * Converts the specified keyword string into a URI.  Note that it's the
 140      * caller's responsibility to check whether keywords are enabled and
 141      * whether aKeyword is a sensible keyword.
 142      *
 143      * @param aKeyword  The keyword string to convert into a URI
 144      * @param aPostData The POST data to submit to the returned URI
 145      *                  (see nsISearchSubmission).
 146      *
 147      * @throws NS_ERROR_FAILURE if the resulting URI requires submission of POST
 148      *         data and aPostData is null.
 149      */
 150     nsIURIFixupInfo keywordToURI(in AUTF8String aKeyword,
 151                                  [optional] out nsIInputStream aPostData);
 152
 153     /**
 154      * Returns true if the specified domain is whitelisted and false otherwise.
 155      * A whitelisted domain is relevant when we have a single word and can't be
 156      * sure whether to treat the word as a host name or should instead be
 157      * treated as a search term.
 158      *
 159      * @param aDomain A domain name to query.
 160      * @param aDotPos The position of the first '.' character in aDomain, or
 161      *                -1 if no '.' character exists.
 162      */
 163     bool isDomainWhitelisted(in AUTF8String aDomain,
 164                              in uint32_t aDotPos);
 165 };
 166