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
9interface nsIURI;
10interface nsIInputStream;
11webidl BrowsingContext;
12
13/**
14 * Interface indicating what we found/corrected when fixing up a URI
15 */
16[scriptable, uuid(4819f183-b532-4932-ac09-b309cd853be7)]
17interface nsIURIFixupInfo : nsISupports
18{
19  /**
20   * Consumer that asked for fixed up URI.
21   */
22  attribute BrowsingContext consumer;
23
24  /**
25   * Our best guess as to what URI the consumer will want. Might
26   * be null if we couldn't salvage anything (for instance, because
27   * the input was invalid as a URI and FIXUP_FLAG_ALLOW_KEYWORD_LOOKUP
28   * was not passed)
29   */
30  attribute nsIURI preferredURI;
31
32  /**
33   * The fixed-up original input, *never* using a keyword search.
34   * (might be null if the original input was not recoverable as
35   * a URL, e.g. "foo bar"!)
36   */
37  attribute nsIURI fixedURI;
38
39  /**
40   * The name of the keyword search provider used to provide a keyword search;
41   * empty string if no keyword search was done.
42   */
43  attribute AString keywordProviderName;
44
45  /**
46   * The keyword as used for the search (post trimming etc.)
47   * empty string if no keyword search was done.
48   */
49  attribute AString keywordAsSent;
50
51  /**
52   * Whether we changed the protocol instead of using one from the input as-is.
53   */
54  attribute boolean fixupChangedProtocol;
55
56  /**
57   * Whether we created an alternative URI. We might have added a prefix and/or
58   * suffix, the contents of which are controlled by the
59   * browser.fixup.alternate.prefix and .suffix prefs, with the defaults being
60   * "www." and ".com", respectively.
61   */
62  attribute boolean fixupCreatedAlternateURI;
63
64  /**
65   * The original input
66   */
67  attribute AUTF8String originalInput;
68};
69
70
71/**
72 * Interface implemented by objects capable of fixing up strings into URIs
73 */
74[scriptable, uuid(1da7e9d4-620b-4949-849a-1cd6077b1b2d)]
75interface nsIURIFixup : nsISupports
76{
77    /** No fixup flags. */
78    const unsigned long FIXUP_FLAG_NONE = 0;
79
80    /**
81     * Allow the fixup to use a keyword lookup service to complete the URI.
82     * The fixup object implementer should honour this flag and only perform
83     * any lengthy keyword (or search) operation if it is set.
84     */
85    const unsigned long FIXUP_FLAG_ALLOW_KEYWORD_LOOKUP = 1;
86
87    /**
88     * Tell the fixup to make an alternate URI from the input URI, for example
89     * to turn foo into www.foo.com.
90     */
91    const unsigned long FIXUP_FLAGS_MAKE_ALTERNATE_URI = 2;
92
93    /*
94     * Set when the fixup happens in a private context, the used search engine
95     * may differ in this case. Not all consumers care about this, because they
96     * may not want the url to be transformed in a search.
97     */
98    const unsigned long FIXUP_FLAG_PRIVATE_CONTEXT = 4;
99
100    /*
101     * Fix common scheme typos.
102     */
103    const unsigned long FIXUP_FLAG_FIX_SCHEME_TYPOS = 8;
104
105    /**
106     * Converts the specified string into a URI, first attempting
107     * to correct any errors in the syntax or other vagaries. Returns
108     * a wellformed URI or nullptr if it can't.
109     *
110     * @param aURIText    Candidate URI.
111     * @param aFixupFlags Flags that govern ways the URI may be fixed up.
112     * @param aPostData   The POST data to submit with the returned
113     *                    URI (see nsISearchSubmission).
114     */
115    nsIURI createFixupURI(in AUTF8String aURIText, in unsigned long aFixupFlags,
116                          [optional] out nsIInputStream aPostData);
117
118    /**
119     * Same as createFixupURI, but 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     * @param aPostData   The POST data to submit with the returned
126     *                    URI (see nsISearchSubmission).
127     */
128    nsIURIFixupInfo getFixupURIInfo(in AUTF8String aURIText,
129                                    in unsigned long aFixupFlags,
130                                    [optional] out nsIInputStream aPostData);
131
132    /**
133     * Convert load flags from nsIWebNavigation to URI fixup flags for use in
134     * createFixupURI or getFixupURIInfo.
135     *
136     * @param aURIText       Candidate URI; used for determining whether to
137     *                       allow keyword lookups.
138     * @param aDocShellFlags Load flags from nsIDocShell to convert.
139     */
140    unsigned long webNavigationFlagsToFixupFlags(
141        in AUTF8String aURIText, in unsigned long aDocShellFlags);
142
143    /**
144     * Converts the specified keyword string into a URI.  Note that it's the
145     * caller's responsibility to check whether keywords are enabled and
146     * whether aKeyword is a sensible keyword.
147     *
148     * @param aKeyword  The keyword string to convert into a URI
149     * @param aIsPrivateContext Whether this is invoked from a private context.
150     * @param aPostData The POST data to submit to the returned URI
151     *                  (see nsISearchSubmission).
152     *
153     * @throws NS_ERROR_FAILURE if the resulting URI requires submission of POST
154     *         data and aPostData is null.
155     */
156    nsIURIFixupInfo keywordToURI(in AUTF8String aKeyword,
157                                 [optional] in boolean aIsPrivateContext,
158                                 [optional] out nsIInputStream aPostData);
159
160    /**
161     * Returns true if the specified domain is whitelisted and false otherwise.
162     * A whitelisted domain is relevant when we have a single word and can't be
163     * sure whether to treat the word as a host name or should instead be
164     * treated as a search term.
165     *
166     * @param aDomain A domain name to query.
167     */
168    bool isDomainWhitelisted(in AUTF8String aDomain);
169};
170
171