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 interface nsIDNSListener;
  12 webidl BrowsingContext;
  13
  14 /**
  15  * Interface indicating what we found/corrected when fixing up a URI
  16  */
  17 [scriptable, uuid(4819f183-b532-4932-ac09-b309cd853be7)]
  18 interface nsIURIFixupInfo : nsISupports
  19 {
  20   /**
  21    * Consumer that asked for fixed up URI.
  22    */
  23   attribute BrowsingContext consumer;
  24
  25   /**
  26    * Our best guess as to what URI the consumer will want. Might
  27    * be null if we couldn't salvage anything (for instance, because
  28    * the input was invalid as a URI and FIXUP_FLAG_ALLOW_KEYWORD_LOOKUP
  29    * was not passed)
  30    */
  31   attribute nsIURI preferredURI;
  32
  33   /**
  34    * The fixed-up original input, *never* using a keyword search.
  35    * (might be null if the original input was not recoverable as
  36    * a URL, e.g. "foo bar"!)
  37    */
  38   attribute nsIURI fixedURI;
  39
  40   /**
  41    * The name of the keyword search provider used to provide a keyword search;
  42    * empty string if no keyword search was done.
  43    */
  44   attribute AString keywordProviderName;
  45
  46   /**
  47    * The keyword as used for the search (post trimming etc.)
  48    * empty string if no keyword search was done.
  49    */
  50   attribute AString keywordAsSent;
  51
  52   /**
  53    * Whether there was no protocol at all and we had to add one in the first place.
  54    */
  55   attribute boolean wasSchemelessInput;
  56
  57   /**
  58    * Whether we changed the protocol instead of using one from the input as-is.
  59    */
  60   attribute boolean fixupChangedProtocol;
  61
  62   /**
  63    * Whether we created an alternative URI. We might have added a prefix and/or
  64    * suffix, the contents of which are controlled by the
  65    * browser.fixup.alternate.prefix and .suffix prefs, with the defaults being
  66    * "www." and ".com", respectively.
  67    */
  68   attribute boolean fixupCreatedAlternateURI;
  69
  70   /**
  71    * The original input
  72    */
  73   attribute AUTF8String originalInput;
  74
  75   /**
  76    * The POST data to submit with the returned URI (see nsISearchSubmission).
  77    */
  78   attribute nsIInputStream postData;
  79 };
  80
  81
  82 /**
  83  * Interface implemented by objects capable of fixing up strings into URIs
  84  */
  85 [scriptable, uuid(1da7e9d4-620b-4949-849a-1cd6077b1b2d)]
  86 interface nsIURIFixup : nsISupports
  87 {
  88     /** No fixup flags. */
  89     const unsigned long FIXUP_FLAG_NONE = 0;
  90
  91     /**
  92      * Allow the fixup to use a keyword lookup service to complete the URI.
  93      * The fixup object implementer should honour this flag and only perform
  94      * any lengthy keyword (or search) operation if it is set.
  95      */
  96     const unsigned long FIXUP_FLAG_ALLOW_KEYWORD_LOOKUP = 1;
  97
  98     /**
  99      * Tell the fixup to make an alternate URI from the input URI, for example
 100      * to turn foo into www.foo.com.
 101      */
 102     const unsigned long FIXUP_FLAGS_MAKE_ALTERNATE_URI = 2;
 103
 104     /*
 105      * Set when the fixup happens in a private context, the used search engine
 106      * may differ in this case. Not all consumers care about this, because they
 107      * may not want the url to be transformed in a search.
 108      */
 109     const unsigned long FIXUP_FLAG_PRIVATE_CONTEXT = 4;
 110
 111     /*
 112      * Fix common scheme typos.
 113      */
 114     const unsigned long FIXUP_FLAG_FIX_SCHEME_TYPOS = 8;
 115
 116     /**
 117      * Tries to converts the specified string into a URI, first attempting
 118      * to correct any errors in the syntax or other vagaries.
 119      * It returns information about what it corrected
 120      * (e.g. whether we could rescue the URI or "just" generated a keyword
 121      * search URI instead).
 122      *
 123      * @param aURIText    Candidate URI.
 124      * @param aFixupFlags Flags that govern ways the URI may be fixed up.
 125      *                    Defaults to FIXUP_FLAG_NONE.
 126      */
 127     nsIURIFixupInfo getFixupURIInfo(in AUTF8String aURIText,
 128                                     [optional] in unsigned long aFixupFlags);
 129
 130     /**
 131      * Convert load flags from nsIWebNavigation to URI fixup flags for use in
 132      * getFixupURIInfo.
 133      *
 134      * @param aURIText       Candidate URI; used for determining whether to
 135      *                       allow keyword lookups.
 136      * @param aDocShellFlags Load flags from nsIDocShell to convert.
 137      */
 138     unsigned long webNavigationFlagsToFixupFlags(
 139         in AUTF8String aURIText, in unsigned long aDocShellFlags);
 140
 141     /**
 142      * Converts the specified keyword string into a URI.  Note that it's the
 143      * caller's responsibility to check whether keywords are enabled and
 144      * whether aKeyword is a sensible keyword.
 145      *
 146      * @param aKeyword  The keyword string to convert into a URI
 147      * @param aIsPrivateContext Whether this is invoked from a private context.
 148      */
 149     nsIURIFixupInfo keywordToURI(in AUTF8String aKeyword,
 150                                  [optional] in boolean aIsPrivateContext);
 151
 152     /**
 153      * Given a uri-like string with a protocol, attempt to fix and convert it
 154      * into an instance of nsIURIFixupInfo.
 155      *
 156      * Differently from getFixupURIInfo, this assumes the input string is an
 157      * http/https uri, and can add a prefix and/or suffix to its hostname.
 158      *
 159      * The scheme will be changed to the scheme defined in
 160      * "browser.fixup.alternate.protocol", which is by default, https.
 161      *
 162      * If the prefix and suffix of the host are missing, it will add them to
 163      * the host using the preferences "browser.fixup.alternate.prefix" and
 164      * "browser.fixup.alternate.suffix" as references.
 165      *
 166      * If a hostname suffix is present, but the URI doesn't contain a prefix,
 167      * it will add the prefix via "browser.fixup.alternate.prefix"
 168      *
 169      * @param aUriString The URI to fixup and convert.
 170      * @returns nsIURIFixupInfo
 171      *                   A nsIURIFixupInfo object with the property fixedURI
 172      *                   which contains the modified URI.
 173      * @throws NS_ERROR_FAILURE
 174      *                   If aUriString is undefined, or the scheme is not
 175      *                   http/https.
 176      */
 177     nsIURIFixupInfo forceHttpFixup(in AUTF8String aUriString);
 178
 179     /**
 180      * With the host associated with the URI, use nsIDNSService to determine
 181      * if an IP address can be found for this host. This method will ignore checking
 182      * hosts that are IP addresses. If the host does not contain any periods, depending
 183      * on the browser.urlbar.dnsResolveFullyQualifiedNames preference value, a period
 184      * may be appended in order to make it a fully qualified domain name.
 185      *
 186      * @param aURI The URI to parse and pass into the DNS lookup.
 187      * @param aListener The listener when the result from the lookup is available.
 188      * @param aOriginAttributes The originAttributes to pass the DNS lookup.
 189      * @throws NS_ERROR_FAILURE if aURI does not have a displayHost or asciiHost.
 190      */
 191     void checkHost(in nsIURI aURI,
 192                     in nsIDNSListener aListener,
 193                     [optional] in jsval aOriginAttributes);
 194
 195     /**
 196      * Returns true if the specified domain is known and false otherwise.
 197      * A known domain is relevant when we have a single word and can't be
 198      * sure whether to treat the word as a host name or should instead be
 199      * treated as a search term.
 200      *
 201      * @param aDomain A domain name to query.
 202      */
 203     bool isDomainKnown(in AUTF8String aDomain);
 204 };