summaryrefslogtreecommitdiffstats
path: root/docshell/base/nsIURIFixup.idl
blob: 23fa4ee296aa42b0d72d08dd76d67b9bc1683599 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
/* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*-
 *
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#include "nsISupports.idl"

interface nsIURI;
interface nsIInputStream;
interface nsIDNSListener;
webidl BrowsingContext;

/**
 * Interface indicating what we found/corrected when fixing up a URI
 */
[scriptable, uuid(4819f183-b532-4932-ac09-b309cd853be7)]
interface nsIURIFixupInfo : nsISupports
{
  /**
   * Consumer that asked for fixed up URI.
   */
  attribute BrowsingContext consumer;

  /**
   * Our best guess as to what URI the consumer will want. Might
   * be null if we couldn't salvage anything (for instance, because
   * the input was invalid as a URI and FIXUP_FLAG_ALLOW_KEYWORD_LOOKUP
   * was not passed)
   */
  attribute nsIURI preferredURI;

  /**
   * The fixed-up original input, *never* using a keyword search.
   * (might be null if the original input was not recoverable as
   * a URL, e.g. "foo bar"!)
   */
  attribute nsIURI fixedURI;

  /**
   * The name of the keyword search provider used to provide a keyword search;
   * empty string if no keyword search was done.
   */
  attribute AString keywordProviderName;

  /**
   * The keyword as used for the search (post trimming etc.)
   * empty string if no keyword search was done.
   */
  attribute AString keywordAsSent;

  /**
   * Whether there was no protocol at all and we had to add one in the first place.
   */
  attribute boolean wasSchemelessInput;

  /**
   * Whether we changed the protocol instead of using one from the input as-is.
   */
  attribute boolean fixupChangedProtocol;

  /**
   * Whether we created an alternative URI. We might have added a prefix and/or
   * suffix, the contents of which are controlled by the
   * browser.fixup.alternate.prefix and .suffix prefs, with the defaults being
   * "www." and ".com", respectively.
   */
  attribute boolean fixupCreatedAlternateURI;

  /**
   * The original input
   */
  attribute AUTF8String originalInput;

  /**
   * The POST data to submit with the returned URI (see nsISearchSubmission).
   */
  attribute nsIInputStream postData;
};


/**
 * Interface implemented by objects capable of fixing up strings into URIs
 */
[scriptable, uuid(1da7e9d4-620b-4949-849a-1cd6077b1b2d)]
interface nsIURIFixup : nsISupports
{
    /** No fixup flags. */
    const unsigned long FIXUP_FLAG_NONE = 0;

    /**
     * Allow the fixup to use a keyword lookup service to complete the URI.
     * The fixup object implementer should honour this flag and only perform
     * any lengthy keyword (or search) operation if it is set.
     */
    const unsigned long FIXUP_FLAG_ALLOW_KEYWORD_LOOKUP = 1;

    /**
     * Tell the fixup to make an alternate URI from the input URI, for example
     * to turn foo into www.foo.com.
     */
    const unsigned long FIXUP_FLAGS_MAKE_ALTERNATE_URI = 2;

    /*
     * Set when the fixup happens in a private context, the used search engine
     * may differ in this case. Not all consumers care about this, because they
     * may not want the url to be transformed in a search.
     */
    const unsigned long FIXUP_FLAG_PRIVATE_CONTEXT = 4;

    /*
     * Fix common scheme typos.
     */
    const unsigned long FIXUP_FLAG_FIX_SCHEME_TYPOS = 8;

    /**
     * Tries to converts the specified string into a URI, first attempting
     * to correct any errors in the syntax or other vagaries.
     * It returns information about what it corrected
     * (e.g. whether we could rescue the URI or "just" generated a keyword
     * search URI instead).
     *
     * @param aURIText    Candidate URI.
     * @param aFixupFlags Flags that govern ways the URI may be fixed up.
     *                    Defaults to FIXUP_FLAG_NONE.
     */
    nsIURIFixupInfo getFixupURIInfo(in AUTF8String aURIText,
                                    [optional] in unsigned long aFixupFlags);

    /**
     * Convert load flags from nsIWebNavigation to URI fixup flags for use in
     * getFixupURIInfo.
     *
     * @param aURIText       Candidate URI; used for determining whether to
     *                       allow keyword lookups.
     * @param aDocShellFlags Load flags from nsIDocShell to convert.
     */
    unsigned long webNavigationFlagsToFixupFlags(
        in AUTF8String aURIText, in unsigned long aDocShellFlags);

    /**
     * Converts the specified keyword string into a URI.  Note that it's the
     * caller's responsibility to check whether keywords are enabled and
     * whether aKeyword is a sensible keyword.
     *
     * @param aKeyword  The keyword string to convert into a URI
     * @param aIsPrivateContext Whether this is invoked from a private context.
     */
    nsIURIFixupInfo keywordToURI(in AUTF8String aKeyword,
                                 [optional] in boolean aIsPrivateContext);

    /**
     * Given a uri-like string with a protocol, attempt to fix and convert it
     * into an instance of nsIURIFixupInfo.
     *
     * Differently from getFixupURIInfo, this assumes the input string is an
     * http/https uri, and can add a prefix and/or suffix to its hostname.
     *
     * The scheme will be changed to the scheme defined in
     * "browser.fixup.alternate.protocol", which is by default, https.
     *
     * If the prefix and suffix of the host are missing, it will add them to
     * the host using the preferences "browser.fixup.alternate.prefix" and
     * "browser.fixup.alternate.suffix" as references.
     *
     * If a hostname suffix is present, but the URI doesn't contain a prefix,
     * it will add the prefix via "browser.fixup.alternate.prefix"
     *
     * @param aUriString The URI to fixup and convert.
     * @returns nsIURIFixupInfo
     *                   A nsIURIFixupInfo object with the property fixedURI
     *                   which contains the modified URI.
     * @throws NS_ERROR_FAILURE
     *                   If aUriString is undefined, or the scheme is not
     *                   http/https.
     */
    nsIURIFixupInfo forceHttpFixup(in AUTF8String aUriString);

    /**
     * With the host associated with the URI, use nsIDNSService to determine
     * if an IP address can be found for this host. This method will ignore checking
     * hosts that are IP addresses. If the host does not contain any periods, depending
     * on the browser.urlbar.dnsResolveFullyQualifiedNames preference value, a period
     * may be appended in order to make it a fully qualified domain name.
     *
     * @param aURI The URI to parse and pass into the DNS lookup.
     * @param aListener The listener when the result from the lookup is available.
     * @param aOriginAttributes The originAttributes to pass the DNS lookup.
     * @throws NS_ERROR_FAILURE if aURI does not have a displayHost or asciiHost.
     */
    void checkHost(in nsIURI aURI,
                    in nsIDNSListener aListener,
                    [optional] in jsval aOriginAttributes);

    /**
     * Returns true if the specified domain is known and false otherwise.
     * A known domain is relevant when we have a single word and can't be
     * sure whether to treat the word as a host name or should instead be
     * treated as a search term.
     *
     * @param aDomain A domain name to query.
     */
    boolean isDomainKnown(in AUTF8String aDomain);
};