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