1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/netwerk/base/public/nsIAuthPrompt2.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,103 @@
1.4 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.5 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.6 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.7 +
1.8 +#include "nsISupports.idl"
1.9 +
1.10 +interface nsIAuthPromptCallback;
1.11 +interface nsIChannel;
1.12 +interface nsICancelable;
1.13 +interface nsIAuthInformation;
1.14 +
1.15 +/**
1.16 + * An interface allowing to prompt for a username and password. This interface
1.17 + * is usually acquired using getInterface on notification callbacks or similar.
1.18 + * It can be used to prompt users for authentication information, either
1.19 + * synchronously or asynchronously.
1.20 + */
1.21 +[scriptable, uuid(651395EB-8612-4876-8AC0-A88D4DCE9E1E)]
1.22 +interface nsIAuthPrompt2 : nsISupports
1.23 +{
1.24 + /** @name Security Levels */
1.25 + /* @{ */
1.26 + /**
1.27 + * The password will be sent unencrypted. No security provided.
1.28 + */
1.29 + const uint32_t LEVEL_NONE = 0;
1.30 + /**
1.31 + * Password will be sent encrypted, but the connection is otherwise
1.32 + * insecure.
1.33 + */
1.34 + const uint32_t LEVEL_PW_ENCRYPTED = 1;
1.35 + /**
1.36 + * The connection, both for password and data, is secure.
1.37 + */
1.38 + const uint32_t LEVEL_SECURE = 2;
1.39 + /* @} */
1.40 +
1.41 + /**
1.42 + * Requests a username and a password. Implementations will commonly show a
1.43 + * dialog with a username and password field, depending on flags also a
1.44 + * domain field.
1.45 + *
1.46 + * @param aChannel
1.47 + * The channel that requires authentication.
1.48 + * @param level
1.49 + * One of the level constants from above. See there for descriptions
1.50 + * of the levels.
1.51 + * @param authInfo
1.52 + * Authentication information object. The implementation should fill in
1.53 + * this object with the information entered by the user before
1.54 + * returning.
1.55 + *
1.56 + * @retval true
1.57 + * Authentication can proceed using the values in the authInfo
1.58 + * object.
1.59 + * @retval false
1.60 + * Authentication should be cancelled, usually because the user did
1.61 + * not provide username/password.
1.62 + *
1.63 + * @note Exceptions thrown from this function will be treated like a
1.64 + * return value of false.
1.65 + */
1.66 + boolean promptAuth(in nsIChannel aChannel,
1.67 + in uint32_t level,
1.68 + in nsIAuthInformation authInfo);
1.69 +
1.70 + /**
1.71 + * Asynchronously prompt the user for a username and password.
1.72 + * This has largely the same semantics as promptUsernameAndPassword(),
1.73 + * but must return immediately after calling and return the entered
1.74 + * data in a callback.
1.75 + *
1.76 + * If the user closes the dialog using a cancel button or similar,
1.77 + * the callback's nsIAuthPromptCallback::onAuthCancelled method must be
1.78 + * called.
1.79 + * Calling nsICancelable::cancel on the returned object SHOULD close the
1.80 + * dialog and MUST call nsIAuthPromptCallback::onAuthCancelled on the provided
1.81 + * callback.
1.82 + *
1.83 + * This implementation may:
1.84 + *
1.85 + * 1) Coalesce identical prompts. This means prompts that are guaranteed to
1.86 + * want the same auth information from the user. A single prompt will be
1.87 + * shown; then the callbacks for all the coalesced prompts will be notified
1.88 + * with the resulting auth information.
1.89 + * 2) Serialize prompts that are all in the same "context" (this might mean
1.90 + * application-wide, for a given window, or something else depending on
1.91 + * the user interface) so that the user is not deluged with prompts.
1.92 + *
1.93 + * @throw
1.94 + * This method may throw any exception when the prompt fails to queue e.g
1.95 + * because of out-of-memory error. It must not throw when the prompt
1.96 + * could already be potentially shown to the user. In that case information
1.97 + * about the failure has to come through the callback. This way we
1.98 + * prevent multiple dialogs shown to the user because consumer may fall
1.99 + * back to synchronous prompt on synchronous failure of this method.
1.100 + */
1.101 + nsICancelable asyncPromptAuth(in nsIChannel aChannel,
1.102 + in nsIAuthPromptCallback aCallback,
1.103 + in nsISupports aContext,
1.104 + in uint32_t level,
1.105 + in nsIAuthInformation authInfo);
1.106 +};
