nsIAuthPrompt2.idl (4178B)
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/. */ 4 5 #include "nsISupports.idl" 6 7 interface nsIAuthPromptCallback; 8 interface nsIChannel; 9 interface nsICancelable; 10 interface nsIAuthInformation; 11 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 /* @} */ 37 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 * @deprecated use asyncPromptAuth 63 */ 64 boolean promptAuth(in nsIChannel aChannel, 65 in uint32_t level, 66 in nsIAuthInformation authInfo); 67 68 /** 69 * Asynchronously prompt the user for a username and password. 70 * This has largely the same semantics as promptUsernameAndPassword(), 71 * but must return immediately after calling and return the entered 72 * data in a callback. 73 * 74 * If the user closes the dialog using a cancel button or similar, 75 * the callback's nsIAuthPromptCallback::onAuthCancelled method must be 76 * called. 77 * Calling nsICancelable::cancel on the returned object SHOULD close the 78 * dialog and MUST call nsIAuthPromptCallback::onAuthCancelled on the provided 79 * callback. 80 * 81 * This implementation may: 82 * 83 * 1) Coalesce identical prompts. This means prompts that are guaranteed to 84 * want the same auth information from the user. A single prompt will be 85 * shown; then the callbacks for all the coalesced prompts will be notified 86 * with the resulting auth information. 87 * 2) Serialize prompts that are all in the same "context" (this might mean 88 * application-wide, for a given window, or something else depending on 89 * the user interface) so that the user is not deluged with prompts. 90 * 91 * @throw 92 * This method may throw any exception when the prompt fails to queue e.g 93 * because of out-of-memory error. It must not throw when the prompt 94 * could already be potentially shown to the user. In that case information 95 * about the failure has to come through the callback. This way we 96 * prevent multiple dialogs shown to the user because consumer may fall 97 * back to synchronous prompt on synchronous failure of this method. 98 */ 99 nsICancelable asyncPromptAuth(in nsIChannel aChannel, 100 in nsIAuthPromptCallback aCallback, 101 in nsISupports aContext, 102 in uint32_t level, 103 in nsIAuthInformation authInfo); 104 };