netwerk/base/public/nsIAuthPrompt2.idl@b8a032363ba2
netwerk/base/public/nsIAuthPrompt2.idl
Thu, 22 Jan 2015 13:21:57 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Thu, 22 Jan 2015 13:21:57 +0100
- branch
- TOR_BUG_9701
- changeset 15
- b8a032363ba2
- permissions
- -rw-r--r--
Incorporate requested changes from Mozilla in review:
https://bugzilla.mozilla.org/show_bug.cgi?id=1123480#c6
1 /* This Source Code Form is subject to the terms of the Mozilla Public
2 * License, v. 2.0. If a copy of the MPL was not distributed with this
3 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
5 #include "nsISupports.idl"
7 interface nsIAuthPromptCallback;
8 interface nsIChannel;
9 interface nsICancelable;
10 interface nsIAuthInformation;
12 /**
13 * An interface allowing to prompt for a username and password. This interface
14 * is usually acquired using getInterface on notification callbacks or similar.
15 * It can be used to prompt users for authentication information, either
16 * synchronously or asynchronously.
17 */
18 [scriptable, uuid(651395EB-8612-4876-8AC0-A88D4DCE9E1E)]
19 interface nsIAuthPrompt2 : nsISupports
20 {
21 /** @name Security Levels */
22 /* @{ */
23 /**
24 * The password will be sent unencrypted. No security provided.
25 */
26 const uint32_t LEVEL_NONE = 0;
27 /**
28 * Password will be sent encrypted, but the connection is otherwise
29 * insecure.
30 */
31 const uint32_t LEVEL_PW_ENCRYPTED = 1;
32 /**
33 * The connection, both for password and data, is secure.
34 */
35 const uint32_t LEVEL_SECURE = 2;
36 /* @} */
38 /**
39 * Requests a username and a password. Implementations will commonly show a
40 * dialog with a username and password field, depending on flags also a
41 * domain field.
42 *
43 * @param aChannel
44 * The channel that requires authentication.
45 * @param level
46 * One of the level constants from above. See there for descriptions
47 * of the levels.
48 * @param authInfo
49 * Authentication information object. The implementation should fill in
50 * this object with the information entered by the user before
51 * returning.
52 *
53 * @retval true
54 * Authentication can proceed using the values in the authInfo
55 * object.
56 * @retval false
57 * Authentication should be cancelled, usually because the user did
58 * not provide username/password.
59 *
60 * @note Exceptions thrown from this function will be treated like a
61 * return value of false.
62 */
63 boolean promptAuth(in nsIChannel aChannel,
64 in uint32_t level,
65 in nsIAuthInformation authInfo);
67 /**
68 * Asynchronously prompt the user for a username and password.
69 * This has largely the same semantics as promptUsernameAndPassword(),
70 * but must return immediately after calling and return the entered
71 * data in a callback.
72 *
73 * If the user closes the dialog using a cancel button or similar,
74 * the callback's nsIAuthPromptCallback::onAuthCancelled method must be
75 * called.
76 * Calling nsICancelable::cancel on the returned object SHOULD close the
77 * dialog and MUST call nsIAuthPromptCallback::onAuthCancelled on the provided
78 * callback.
79 *
80 * This implementation may:
81 *
82 * 1) Coalesce identical prompts. This means prompts that are guaranteed to
83 * want the same auth information from the user. A single prompt will be
84 * shown; then the callbacks for all the coalesced prompts will be notified
85 * with the resulting auth information.
86 * 2) Serialize prompts that are all in the same "context" (this might mean
87 * application-wide, for a given window, or something else depending on
88 * the user interface) so that the user is not deluged with prompts.
89 *
90 * @throw
91 * This method may throw any exception when the prompt fails to queue e.g
92 * because of out-of-memory error. It must not throw when the prompt
93 * could already be potentially shown to the user. In that case information
94 * about the failure has to come through the callback. This way we
95 * prevent multiple dialogs shown to the user because consumer may fall
96 * back to synchronous prompt on synchronous failure of this method.
97 */
98 nsICancelable asyncPromptAuth(in nsIChannel aChannel,
99 in nsIAuthPromptCallback aCallback,
100 in nsISupports aContext,
101 in uint32_t level,
102 in nsIAuthInformation authInfo);
103 };
