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   * The POST data to submit with the returned URI (see nsISearchSubmission).
71   */
72  attribute nsIInputStream postData;
73};
74
75
76/**
77 * Interface implemented by objects capable of fixing up strings into URIs
78 */
79[scriptable, uuid(1da7e9d4-620b-4949-849a-1cd6077b1b2d)]
80interface nsIURIFixup : nsISupports
81{
82    /** No fixup flags. */
83    const unsigned long FIXUP_FLAG_NONE = 0;
84
85    /**
86     * Allow the fixup to use a keyword lookup service to complete the URI.
87     * The fixup object implementer should honour this flag and only perform
88     * any lengthy keyword (or search) operation if it is set.
89     */
90    const unsigned long FIXUP_FLAG_ALLOW_KEYWORD_LOOKUP = 1;
91
92    /**
93     * Tell the fixup to make an alternate URI from the input URI, for example
94     * to turn foo into www.foo.com.
95     */
96    const unsigned long FIXUP_FLAGS_MAKE_ALTERNATE_URI = 2;
97
98    /*
99     * Set when the fixup happens in a private context, the used search engine
100     * may differ in this case. Not all consumers care about this, because they
101     * may not want the url to be transformed in a search.
102     */
103    const unsigned long FIXUP_FLAG_PRIVATE_CONTEXT = 4;
104
105    /*
106     * Fix common scheme typos.
107     */
108    const unsigned long FIXUP_FLAG_FIX_SCHEME_TYPOS = 8;
109
110    /**
111     * Tries to converts the specified string into a URI, first attempting
112     * to correct any errors in the syntax or other vagaries.
113     * It returns information about what it corrected
114     * (e.g. whether we could rescue the URI or "just" generated a keyword
115     * search URI instead).
116     *
117     * @param aURIText    Candidate URI.
118     * @param aFixupFlags Flags that govern ways the URI may be fixed up.
119     *                    Defaults to FIXUP_FLAG_NONE.
120     */
121    nsIURIFixupInfo getFixupURIInfo(in AUTF8String aURIText,
122                                    [optional] in unsigned long aFixupFlags);
123
124    /**
125     * Convert load flags from nsIWebNavigation to URI fixup flags for use in
126     * getFixupURIInfo.
127     *
128     * @param aURIText       Candidate URI; used for determining whether to
129     *                       allow keyword lookups.
130     * @param aDocShellFlags Load flags from nsIDocShell to convert.
131     */
132    unsigned long webNavigationFlagsToFixupFlags(
133        in AUTF8String aURIText, in unsigned long aDocShellFlags);
134
135    /**
136     * Converts the specified keyword string into a URI.  Note that it's the
137     * caller's responsibility to check whether keywords are enabled and
138     * whether aKeyword is a sensible keyword.
139     *
140     * @param aKeyword  The keyword string to convert into a URI
141     * @param aIsPrivateContext Whether this is invoked from a private context.
142     */
143    nsIURIFixupInfo keywordToURI(in AUTF8String aKeyword,
144                                 [optional] in boolean aIsPrivateContext);
145
146    /**
147     * Returns true if the specified domain is known and false otherwise.
148     * A known domain is relevant when we have a single word and can't be
149     * sure whether to treat the word as a host name or should instead be
150     * treated as a search term.
151     *
152     * @param aDomain A domain name to query.
153     */
154    bool isDomainKnown(in AUTF8String aDomain);
155};
156
157