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